3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _textparse_included
19 #define _textparse_included
22 /********************************
23 * Everything below describes the SMC Parse, or "SourceMod Configuration" format.
24 * This parser is entirely event based. You must hook events to receive data.
25 * The file format itself is nearly identical to Valve's KeyValues format.
26 ********************************/
29 * Parse result directive.
33 SMCParse_Continue, /**< Continue parsing */
34 SMCParse_Halt, /**< Stop parsing here */
35 SMCParse_HaltFail /**< Stop parsing and return failure */
43 SMCError_Okay = 0, /**< No error */
44 SMCError_StreamOpen, /**< Stream failed to open */
45 SMCError_StreamError, /**< The stream died... somehow */
46 SMCError_Custom, /**< A custom handler threw an error */
47 SMCError_InvalidSection1, /**< A section was declared without quotes, and had extra tokens */
48 SMCError_InvalidSection2, /**< A section was declared without any header */
49 SMCError_InvalidSection3, /**< A section ending was declared with too many unknown tokens */
50 SMCError_InvalidSection4, /**< A section ending has no matching beginning */
51 SMCError_InvalidSection5, /**< A section beginning has no matching ending */
52 SMCError_InvalidTokens, /**< There were too many unidentifiable strings on one line */
53 SMCError_TokenOverflow, /**< The token buffer overflowed */
54 SMCError_InvalidProperty1, /**< A property was declared outside of any section */
58 * Creates a new SMC file format parser. This is used to set parse hooks.
60 * @return A new Handle to an SMC Parse structure.
62 native Handle:SMC_CreateParser();
67 * @param smc A Handle to an SMC Parse structure.
68 * @param file A string containing the file path.
69 * @param line An optional by reference cell to store the last line number read.
70 * @param col An optional by reference cell to store the last column number read.
71 * @return An SMCParseError result.
72 * @error Invalid or corrupt Handle.
74 native SMCError:SMC_ParseFile(Handle:smc, const String:file[], &line=0, &col=0);
77 * Gets an error string for an SMCError code.
78 * @note SMCError_Okay returns false.
79 * @note SMCError_Custom (which is thrown on SMCParse_HaltFail) returns false.
81 * @param error The SMCParseError code.
82 * @param buffer A string buffer for the error (contents undefined on failure).
83 * @param buf_max The maximum size of the buffer.
84 * @return True on success, false otherwise.
86 native bool:SMC_GetErrorString(SMCError:error, String:buffer[], buf_max);
89 * Called when parsing is started.
91 * @param smc The SMC Parse Handle.
94 functag SMC_ParseStart public(Handle:smc);
97 * Sets the SMC_ParseStart function of a parse Handle.
99 * @param smc Handle to an SMC Parse.
100 * @param func SMC_ParseStart function.
102 * @error Invalid or corrupt Handle.
104 native SMC_SetParseStart(Handle:smc, SMC_ParseStart:func);
107 * Called when parsing is halted.
109 * @param smc The SMC Parse Handle.
110 * @param halted True if abnormally halted, false otherwise.
111 * @param failed True if parsing failed, false otherwise.
114 functag SMC_ParseEnd public(Handle:smc, bool:halted, bool:failed);
117 * Sets the SMC_ParseEnd of a parse handle.
119 * @param smc Handle to an SMC Parse.
120 * @param func SMC_ParseEnd function.
122 * @error Invalid or corrupt Handle.
124 native SMC_SetParseEnd(Handle:smc, SMC_ParseEnd:func);
127 * Called when the parser is entering a new section or sub-section.
128 * @note Enclosing quotes are always stripped.
130 * @param smc The SMC Parse Handle.
131 * @param name String containing section name.
132 * @param opt_quotes True if the section name was quote-enclosed in the file.
133 * @return An SMCResult action to take.
135 functag SMC_NewSection SMCResult:public(Handle:smc, const String:name[], bool:opt_quotes);
138 * Called when the parser finds a new key/value pair.
139 * @note Enclosing quotes are always stripped.
141 * @param smc The SMC Parse Handle.
142 * @param key String containing key name.
143 * @param value String containing value name.
144 * @param key_quotes Whether or not the key was enclosed in quotes.
145 * @param value_quotes Whether or not the value was enclosed in quotes.
146 * @return An SMCResult action to take.
148 functag SMC_KeyValue SMCResult:public(Handle:smc, const String:key[], const String:value[], bool:key_quotes, bool:value_quotes);
151 * Called when the parser finds the end of the current section.
153 * @param smc The SMC Parse Handle.
154 * @return An SMCResult action to take.
156 functag SMC_EndSection SMCResult:public(Handle:smc);
159 * Sets the three main reader functions.
161 * @param smc An SMC parse Handle.
162 * @param ns An SMC_NewSection function pointer.
163 * @param kv An SMC_KeyValue function pointer.
164 * @param es An SMC_EndSection function pointer.
167 native SMC_SetReaders(Handle:smc, SMC_NewSection:ns, SMC_KeyValue:kv, SMC_EndSection:es);
170 * Called whenever a raw line is read.
172 * @param smc The SMC Parse Handle.
173 * @param line A string containing the raw line from the file.
174 * @param lineno The line number it occurs on.
175 * @return An SMCResult action to take.
177 functag SMC_RawLine SMCResult:public(Handle:smc, const String:line[], lineno);
180 * Sets a raw line reader on an SMC parser Handle.
182 * @param smc Handle to an SMC Parse.
183 * @param func SMC_RawLine function.
186 native SMC_SetRawLine(Handle:smc, SMC_RawLine:func);
