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