3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _textparse_included
36 #define _textparse_included
39 /********************************
40 * Everything below describes the SMC Parse, or "SourceMod Configuration" format.
41 * This parser is entirely event based. You must hook events to receive data.
42 * The file format itself is nearly identical to Valve's KeyValues format.
43 ********************************/
46 * Parse result directive.
50 SMCParse_Continue, /**< Continue parsing */
51 SMCParse_Halt, /**< Stop parsing here */
52 SMCParse_HaltFail /**< Stop parsing and return failure */
60 SMCError_Okay = 0, /**< No error */
61 SMCError_StreamOpen, /**< Stream failed to open */
62 SMCError_StreamError, /**< The stream died... somehow */
63 SMCError_Custom, /**< A custom handler threw an error */
64 SMCError_InvalidSection1, /**< A section was declared without quotes, and had extra tokens */
65 SMCError_InvalidSection2, /**< A section was declared without any header */
66 SMCError_InvalidSection3, /**< A section ending was declared with too many unknown tokens */
67 SMCError_InvalidSection4, /**< A section ending has no matching beginning */
68 SMCError_InvalidSection5, /**< A section beginning has no matching ending */
69 SMCError_InvalidTokens, /**< There were too many unidentifiable strings on one line */
70 SMCError_TokenOverflow, /**< The token buffer overflowed */
71 SMCError_InvalidProperty1, /**< A property was declared outside of any section */
75 * Creates a new SMC file format parser. This is used to set parse hooks.
77 * @return A new Handle to an SMC Parse structure.
79 native Handle:SMC_CreateParser();
84 * @param smc A Handle to an SMC Parse structure.
85 * @param file A string containing the file path.
86 * @param line An optional by reference cell to store the last line number read.
87 * @param col An optional by reference cell to store the last column number read.
88 * @return An SMCParseError result.
89 * @error Invalid or corrupt Handle.
91 native SMCError:SMC_ParseFile(Handle:smc, const String:file[], &line=0, &col=0);
94 * Gets an error string for an SMCError code.
95 * @note SMCError_Okay returns false.
96 * @note SMCError_Custom (which is thrown on SMCParse_HaltFail) returns false.
98 * @param error The SMCParseError code.
99 * @param buffer A string buffer for the error (contents undefined on failure).
100 * @param buf_max The maximum size of the buffer.
101 * @return True on success, false otherwise.
103 native bool:SMC_GetErrorString(SMCError:error, String:buffer[], buf_max);
106 * Called when parsing is started.
108 * @param smc The SMC Parse Handle.
111 functag public SMC_ParseStart(Handle:smc);
114 * Sets the SMC_ParseStart function of a parse Handle.
116 * @param smc Handle to an SMC Parse.
117 * @param func SMC_ParseStart function.
119 * @error Invalid or corrupt Handle.
121 native SMC_SetParseStart(Handle:smc, SMC_ParseStart:func);
124 * Called when parsing is halted.
126 * @param smc The SMC Parse Handle.
127 * @param halted True if abnormally halted, false otherwise.
128 * @param failed True if parsing failed, false otherwise.
131 functag public SMC_ParseEnd(Handle:smc, bool:halted, bool:failed);
134 * Sets the SMC_ParseEnd of a parse handle.
136 * @param smc Handle to an SMC Parse.
137 * @param func SMC_ParseEnd function.
139 * @error Invalid or corrupt Handle.
141 native SMC_SetParseEnd(Handle:smc, SMC_ParseEnd:func);
144 * Called when the parser is entering a new section or sub-section.
145 * @note Enclosing quotes are always stripped.
147 * @param smc The SMC Parse Handle.
148 * @param name String containing section name.
149 * @param opt_quotes True if the section name was quote-enclosed in the file.
150 * @return An SMCResult action to take.
152 functag public SMCResult:SMC_NewSection(Handle:smc, const String:name[], bool:opt_quotes);
155 * Called when the parser finds a new key/value pair.
156 * @note Enclosing quotes are always stripped.
158 * @param smc The SMC Parse Handle.
159 * @param key String containing key name.
160 * @param value String containing value name.
161 * @param key_quotes Whether or not the key was enclosed in quotes.
162 * @param value_quotes Whether or not the value was enclosed in quotes.
163 * @return An SMCResult action to take.
165 functag public SMCResult:SMC_KeyValue(Handle:smc, const String:key[], const String:value[], bool:key_quotes, bool:value_quotes);
168 * Called when the parser finds the end of the current section.
170 * @param smc The SMC Parse Handle.
171 * @return An SMCResult action to take.
173 functag public SMCResult:SMC_EndSection(Handle:smc);
176 * Sets the three main reader functions.
178 * @param smc An SMC parse Handle.
179 * @param ns An SMC_NewSection function pointer.
180 * @param kv An SMC_KeyValue function pointer.
181 * @param es An SMC_EndSection function pointer.
184 native SMC_SetReaders(Handle:smc, SMC_NewSection:ns, SMC_KeyValue:kv, SMC_EndSection:es);
187 * Called whenever a raw line is read.
189 * @param smc The SMC Parse Handle.
190 * @param line A string containing the raw line from the file.
191 * @param lineno The line number it occurs on.
192 * @return An SMCResult action to take.
194 functag public SMCResult:SMC_RawLine(Handle:smc, const String:line[], lineno);
197 * Sets a raw line reader on an SMC parser Handle.
199 * @param smc Handle to an SMC Parse.
200 * @param func SMC_RawLine function.
203 native SMC_SetRawLine(Handle:smc, SMC_RawLine:func);
