ds@1952: /**
ds@1952:  * vim: set ts=4 :
ds@1952:  * =============================================================================
ds@1952:  * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.
ds@1952:  * =============================================================================
ds@1952:  *
ds@1952:  * This file is part of the SourceMod/SourcePawn SDK.
ds@1952:  *
ds@1952:  * This program is free software; you can redistribute it and/or modify it under
ds@1952:  * the terms of the GNU General Public License, version 3.0, as published by the
ds@1952:  * Free Software Foundation.
ds@1952:  * 
ds@1952:  * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1952:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1952:  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
ds@1952:  * details.
ds@1952:  *
ds@1952:  * You should have received a copy of the GNU General Public License along with
ds@1952:  * this program.  If not, see <http://www.gnu.org/licenses/>.
ds@1952:  *
ds@1952:  * As a special exception, AlliedModders LLC gives you permission to link the
ds@1952:  * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1952:  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1952:  * by the Valve Corporation.  You must obey the GNU General Public License in
ds@1952:  * all respects for all other code used.  Additionally, AlliedModders LLC grants
ds@1952:  * this exception to all derivative works.  AlliedModders LLC defines further
ds@1952:  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1952:  * or <http://www.sourcemod.net/license.php>.
ds@1952:  *
ds@1952:  * Version: $Id$
ds@1952:  */
ds@1952:  
ds@1952: #if defined _textparse_included
ds@1952:  #endinput
ds@1952: #endif
ds@1952: #define _textparse_included
ds@1952: 
ds@1952: 
ds@1952: /********************************
ds@1952:  * Everything below describes the SMC Parse, or "SourceMod Configuration" format.
ds@1952:  * This parser is entirely event based.  You must hook events to receive data.
ds@1952:  * The file format itself is nearly identical to Valve's KeyValues format.
ds@1952:  ********************************/
ds@1952: 
ds@1952: /**
ds@1952:  * Parse result directive.
ds@1952:  */
ds@1952: enum SMCResult
ds@1952: {
ds@1952: 	SMCParse_Continue,			/**< Continue parsing */
ds@1952: 	SMCParse_Halt,				/**< Stop parsing here */
ds@1952: 	SMCParse_HaltFail			/**< Stop parsing and return failure */
ds@1952: };
ds@1952: 
ds@1952: /**
ds@1952:  * Parse error codes.
ds@1952:  */
ds@1952: enum SMCError
ds@1952: {
ds@1952: 	SMCError_Okay = 0,			/**< No error */
ds@1952: 	SMCError_StreamOpen,		/**< Stream failed to open */
ds@1952: 	SMCError_StreamError,		/**< The stream died... somehow */
ds@1952: 	SMCError_Custom,			/**< A custom handler threw an error */
ds@1952: 	SMCError_InvalidSection1,	/**< A section was declared without quotes, and had extra tokens */
ds@1952: 	SMCError_InvalidSection2,	/**< A section was declared without any header */
ds@1952: 	SMCError_InvalidSection3,	/**< A section ending was declared with too many unknown tokens */
ds@1952: 	SMCError_InvalidSection4,	/**< A section ending has no matching beginning */
ds@1952: 	SMCError_InvalidSection5,	/**< A section beginning has no matching ending */
ds@1952: 	SMCError_InvalidTokens,		/**< There were too many unidentifiable strings on one line */
ds@1952: 	SMCError_TokenOverflow,		/**< The token buffer overflowed */
ds@1952: 	SMCError_InvalidProperty1,	/**< A property was declared outside of any section */
ds@1952: };
ds@1952: 
ds@1952: /**
ds@1952:  * Creates a new SMC file format parser.  This is used to set parse hooks.
ds@1952:  *
ds@1952:  * @return			A new Handle to an SMC Parse structure.
ds@1952:  */
ds@1952: native Handle:SMC_CreateParser();
ds@1952: 
ds@1952: /**
ds@1952:  * Parses an SMC file.
ds@1952:  *
ds@1952:  * @param smc			A Handle to an SMC Parse structure.
ds@1952:  * @param file			A string containing the file path.
ds@1952:  * @param line			An optional by reference cell to store the last line number read.
ds@1952:  * @param col			An optional by reference cell to store the last column number read.
ds@1952:  * @return				An SMCParseError result.
ds@1952:  * @error				Invalid or corrupt Handle. 
ds@1952:  */
ds@1952: native SMCError:SMC_ParseFile(Handle:smc, const String:file[], &line=0, &col=0);
ds@1952: 
ds@1952: /**
ds@1952:  * Gets an error string for an SMCError code.
ds@1952:  * @note SMCError_Okay returns false.
ds@1952:  * @note SMCError_Custom (which is thrown on SMCParse_HaltFail) returns false.
ds@1952:  *
ds@1952:  * @param error			The SMCParseError code.
ds@1952:  * @param buffer		A string buffer for the error (contents undefined on failure).
ds@1952:  * @param buf_max		The maximum size of the buffer.
ds@1952:  * @return				True on success, false otherwise.
ds@1952:  */
ds@1952: native bool:SMC_GetErrorString(SMCError:error, String:buffer[], buf_max);
ds@1952: 
ds@1952: /**
ds@1952:  * Called when parsing is started.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @noreturn
ds@1952:  */
ds@1952: functag SMC_ParseStart public(Handle:smc);
ds@1952: 
ds@1952: /**
ds@1952:  * Sets the SMC_ParseStart function of a parse Handle.
ds@1952:  *
ds@1952:  * @param smc			Handle to an SMC Parse.
ds@1952:  * @param func			SMC_ParseStart function.
ds@1952:  * @noreturn
ds@1952:  * @error				Invalid or corrupt Handle. 
ds@1952:  */
ds@1952: native SMC_SetParseStart(Handle:smc, SMC_ParseStart:func);
ds@1952: 
ds@1952: /**
ds@1952:  * Called when parsing is halted.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @param halted		True if abnormally halted, false otherwise.
ds@1952:  * @param failed		True if parsing failed, false otherwise.
ds@1952:  * @noreturn
ds@1952:  */
ds@1952: functag SMC_ParseEnd public(Handle:smc, bool:halted, bool:failed);
ds@1952: 
ds@1952: /**
ds@1952:  * Sets the SMC_ParseEnd of a parse handle.
ds@1952:  *
ds@1952:  * @param smc			Handle to an SMC Parse.
ds@1952:  * @param func			SMC_ParseEnd function.
ds@1952:  * @noreturn
ds@1952:  * @error				Invalid or corrupt Handle. 
ds@1952:  */
ds@1952: native SMC_SetParseEnd(Handle:smc, SMC_ParseEnd:func);
ds@1952: 
ds@1952: /**
ds@1952:  * Called when the parser is entering a new section or sub-section.
ds@1952:  * @note Enclosing quotes are always stripped.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @param name			String containing section name.
ds@1952:  * @param opt_quotes	True if the section name was quote-enclosed in the file.
ds@1952:  * @return				An SMCResult action to take.
ds@1952:  */
ds@1952: functag SMC_NewSection SMCResult:public(Handle:smc, const String:name[], bool:opt_quotes);
ds@1952: 
ds@1952: /**
ds@1952:  * Called when the parser finds a new key/value pair.
ds@1952:  * @note Enclosing quotes are always stripped.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @param key			String containing key name.
ds@1952:  * @param value			String containing value name.
ds@1952:  * @param key_quotes	Whether or not the key was enclosed in quotes.
ds@1952:  * @param value_quotes	Whether or not the value was enclosed in quotes.
ds@1952:  * @return				An SMCResult action to take.
ds@1952:  */
ds@1952: functag SMC_KeyValue SMCResult:public(Handle:smc, const String:key[], const String:value[], bool:key_quotes, bool:value_quotes);
ds@1952: 
ds@1952: /**
ds@1952:  * Called when the parser finds the end of the current section.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @return				An SMCResult action to take.
ds@1952:  */
ds@1952: functag SMC_EndSection SMCResult:public(Handle:smc);
ds@1952: 
ds@1952: /**
ds@1952:  * Sets the three main reader functions.
ds@1952:  *
ds@1952:  * @param smc			An SMC parse Handle.
ds@1952:  * @param ns			An SMC_NewSection function pointer.
ds@1952:  * @param kv			An SMC_KeyValue function pointer.
ds@1952:  * @param es			An SMC_EndSection function pointer.
ds@1952:  * @noreturn
ds@1952:  */
ds@1952: native SMC_SetReaders(Handle:smc, SMC_NewSection:ns, SMC_KeyValue:kv, SMC_EndSection:es);
ds@1952: 
ds@1952: /**
ds@1952:  * Called whenever a raw line is read.
ds@1952:  *
ds@1952:  * @param smc			The SMC Parse Handle.
ds@1952:  * @param line			A string containing the raw line from the file.
ds@1952:  * @param lineno		The line number it occurs on.
ds@1952:  * @return				An SMCResult action to take.
ds@1952:  */
ds@1952: functag SMC_RawLine SMCResult:public(Handle:smc, const String:line[], lineno);
ds@1952: 
ds@1952: /**
ds@1952:  * Sets a raw line reader on an SMC parser Handle.
ds@1952:  *
ds@1952:  * @param smc			Handle to an SMC Parse.
ds@1952:  * @param func			SMC_RawLine function.
ds@1952:  * @noreturn
ds@1952:  */
ds@1952: native SMC_SetRawLine(Handle:smc, SMC_RawLine:func);