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 ********************************/
30 SMCParse_Continue, /**< Continue parsing */
31 SMCParse_Halt, /**< Stop parsing here */
32 SMCParse_HaltFail /**< Stop parsing and return failure */
37 SMCError_Okay = 0, /**< No error */
38 SMCError_StreamOpen, /**< Stream failed to open */
39 SMCError_StreamError, /**< The stream died... somehow */
40 SMCError_Custom, /**< A custom handler threw an error */
41 SMCError_InvalidSection1, /**< A section was declared without quotes, and had extra tokens */
42 SMCError_InvalidSection2, /**< A section was declared without any header */
43 SMCError_InvalidSection3, /**< A section ending was declared with too many unknown tokens */
44 SMCError_InvalidSection4, /**< A section ending has no matching beginning */
45 SMCError_InvalidSection5, /**< A section beginning has no matching ending */
46 SMCError_InvalidTokens, /**< There were too many unidentifiable strings on one line */
47 SMCError_TokenOverflow, /**< The token buffer overflowed */
48 SMCError_InvalidProperty1, /**< A property was declared outside of any section */
52 * Creates a new SMC file format parser. This is used to set parse hooks.
54 * @return A new Handle to an SMC Parse structure.
56 native Handle:SMC_CreateParser();
61 * @param smc A Handle to an SMC Parse structure.
62 * @param file A string containing the file path.
63 * @param line An optional by reference cell to store the last line number read.
64 * @param col An optional by reference cell to store the last column number read.
65 * @return An SMCParseError result.
66 * @error Invalid or corrupt Handle.
68 native SMCError:SMC_ParseFile(Handle:smc, const String:file[], &line=0, &col=0);
71 * Gets an error string for an SMCError code.
72 * @note SMCError_Okay returns false.
73 * @note SMCError_Custom (which is thrown on SMCParse_HaltFail) returns false.
75 * @param error The SMCParseError code.
76 * @param buffer A string buffer for the error (contents undefined on failure).
77 * @param buf_max The maximum size of the buffer.
78 * @return True on success, false otherwise.
80 native bool:SMC_GetErrorString(SMCError:error, String:buffer[], buf_max);
83 * Called when parsing is started.
85 * @param smc The SMC Parse Handle.
88 functag SMC_ParseStart public(Handle:smc);
91 * Sets the SMC_ParseStart function of a parse Handle.
93 * @param smc Handle to an SMC Parse.
94 * @param func SMC_ParseStart function.
96 * @error Invalid or corrupt Handle.
98 native SMC_SetParseStart(Handle:smc, SMC_ParseStart:func);
101 * Called when parsing is halted.
103 * @param smc The SMC Parse Handle.
104 * @param halted True if abnormally halted, false otherwise.
105 * @param failed True if parsing failed, false otherwise.
108 functag SMC_ParseEnd public(Handle:smc, bool:halted, bool:failed);
111 * Sets the SMC_ParseEnd of a parse handle.
113 * @param smc Handle to an SMC Parse.
114 * @param func SMC_ParseEnd function.
116 * @error Invalid or corrupt Handle.
118 native SMC_SetParseEnd(Handle:smc, SMC_ParseEnd:func);
121 * Called when the parser is entering a new section or sub-section.
122 * @note Enclosing quotes are always stripped.
124 * @param smc The SMC Parse Handle.
125 * @param name String containing section name.
126 * @param opt_quotes True if the section name was quote-enclosed in the file.
127 * @return An SMCResult action to take.
129 functag SMC_NewSection SMCResult:public(Handle:smc, const String:name[], bool:opt_quotes);
132 * Called when the parser finds a new key/value pair.
133 * @note Enclosing quotes are always stripped.
135 * @param smc The SMC Parse Handle.
136 * @param key String containing key name.
137 * @param value String containing value name.
138 * @param key_quotes Whether or not the key was enclosed in quotes.
139 * @param value_quotes Whether or not the value was enclosed in quotes.
140 * @return An SMCResult action to take.
142 functag SMC_KeyValue SMCResult:public(Handle:smc, const String:key[], const String:value[], bool:key_quotes, bool:value_quotes);
145 * Called when the parser finds the end of the current section.
147 * @param smc The SMC Parse Handle.
148 * @return An SMCResult action to take.
150 functag SMC_EndSection SMCResult:public(Handle:smc);
153 * Sets the three main reader functions.
155 * @param smc An SMC parse Handle.
156 * @param ns An SMC_NewSection function pointer.
157 * @param kv An SMC_KeyValue function pointer.
158 * @param es An SMC_EndSection function pointer.
161 native SMC_SetReaders(Handle:smc, SMC_NewSection:ns, SMC_KeyValue:kv, SMC_EndSection:es);
164 * Called whenever a raw line is read.
166 * @param smc The SMC Parse Handle.
167 * @param line A string containing the raw line from the file.
168 * @param lineno The line number it occurs on.
169 * @return An SMCResult action to take.
171 functag SMC_RawLine SMCResult:public(Handle:smc, const String:line[], lineno);
174 * Sets a raw line reader on an SMC parser Handle.
176 * @param smc Handle to an SMC Parse.
177 * @param func SMC_RawLine function.
180 native SMC_SetRawLine(Handle:smc, SMC_RawLine:func);
