diff options
Diffstat (limited to 'sourcemod/scripting/include/keyvalues.inc')
| -rw-r--r-- | sourcemod/scripting/include/keyvalues.inc | 707 |
1 files changed, 707 insertions, 0 deletions
diff --git a/sourcemod/scripting/include/keyvalues.inc b/sourcemod/scripting/include/keyvalues.inc new file mode 100644 index 0000000..7318507 --- /dev/null +++ b/sourcemod/scripting/include/keyvalues.inc @@ -0,0 +1,707 @@ +/** + * vim: set ts=4 sw=4 tw=99 noet : + * ============================================================================= + * SourceMod (C)2004-2014 AlliedModders LLC. All rights reserved. + * ============================================================================= + * + * This file is part of the SourceMod/SourcePawn SDK. + * + * This program is free software; you can redistribute it and/or modify it under + * the terms of the GNU General Public License, version 3.0, as published by the + * Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more + * details. + * + * You should have received a copy of the GNU General Public License along with + * this program. If not, see <http://www.gnu.org/licenses/>. + * + * As a special exception, AlliedModders LLC gives you permission to link the + * code of this program (as well as its derivative works) to "Half-Life 2," the + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software + * by the Valve Corporation. You must obey the GNU General Public License in + * all respects for all other code used. Additionally, AlliedModders LLC grants + * this exception to all derivative works. AlliedModders LLC defines further + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), + * or <http://www.sourcemod.net/license.php>. + * + * Version: $Id$ + */ + +#if defined _keyvalues_included + #endinput +#endif +#define _keyvalues_included + +/** + * KeyValue data value types + */ +enum KvDataTypes +{ + KvData_None = 0, /**< Type could not be identified, or no type */ + KvData_String, /**< String value */ + KvData_Int, /**< Integer value */ + KvData_Float, /**< Floating point value */ + KvData_Ptr, /**< Pointer value (sometimes called "long") */ + KvData_WString, /**< Wide string value */ + KvData_Color, /**< Color value */ + KvData_UInt64, /**< Large integer value */ + /* --- */ + KvData_NUMTYPES +}; + +methodmap KeyValues < Handle +{ + // Creates a new KeyValues structure. The Handle must be closed with + // CloseHandle() or delete. + // + // @param name Name of the root section. + // @param firstKey If non-empty, specifies the first key value. + // @param firstValue If firstKey is non-empty, specifies the first key's value. + public native KeyValues(const char[] name, const char[] firstKey="", const char[] firstValue=""); + + // Exports a KeyValues tree to a file. The tree is dumped from the current position. + // + // @param file File to dump write to. + // @return True on success, false otherwise. + public native bool ExportToFile(const char[] file); + + // Exports a KeyValues tree to a string. The string is dumped from the current position. + // + // @param buffer Buffer to write to. + // @param maxlength Max length of buffer. + // @return Number of bytes that can be written to buffer. + public native int ExportToString(char[] buffer, int maxlength); + + // Amount of bytes written by ExportToFile & ExportToString. + property int ExportLength { + public native get(); + } + + // Imports a file in KeyValues format. The file is read into the current + // position of the tree. + // + // @param file File to read from. + // @return True on success, false otherwise. + public native bool ImportFromFile(const char[] file); + + // Converts a given string to a KeyValues tree. The string is read into + // the current postion of the tree. + // + // @param buffer String buffer to load into the KeyValues. + // @param resourceName The resource name of the KeyValues, used for error tracking purposes. + // @return True on success, false otherwise. + public native bool ImportFromString(const char[] buffer, const char[] resourceName="StringToKeyValues"); + + // Imports subkeys in the given KeyValues, at the current position in that + // KeyValues, into the current position in this KeyValues. Note that this + // copies keys; it does not embed a reference to them. + // + // @param other Origin KeyValues Handle. + public native void Import(KeyValues other); + + // Sets a string value of a KeyValues key. + // + // @param kv KeyValues Handle. + // @param key Name of the key, or NULL_STRING. + // @param value String value. + public native void SetString(const char[] key, const char[] value); + + // Sets an integer value of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param value Value number. + public native void SetNum(const char[] key, int value); + + // Sets a large integer value of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param value Large integer value (0=High bits, 1=Low bits) + public native void SetUInt64(const char[] key, const int value[2]); + + // Sets a floating point value of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param value Floating point value. + public native void SetFloat(const char[] key, float value); + + // Sets a set of color values of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param r Red value. + // @param g Green value. + // @param b Blue value. + // @param a Alpha value. + public native void SetColor(const char[] key, int r, int g, int b, int a=0); + + // Sets a set of color values of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param color Red, green, blue and alpha channels. + public void SetColor4(const char[] key, const int color[4]) { + this.SetColor(key, color[0], color[1], color[2], color[3]); + } + + // Sets a vector value of a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param vec Vector value. + public native void SetVector(const char[] key, const float vec[3]); + + // Retrieves a string value from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param value Buffer to store key value in. + // @param maxlength Maximum length of the value buffer. + // @param defvalue Optional default value to use if the key is not found. + public native void GetString(const char[] key, char[] value, int maxlength, const char[] defvalue=""); + + // Retrieves an integer value from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param defvalue Optional default value to use if the key is not found. + // @return Integer value of the key. + public native int GetNum(const char[] key, int defvalue=0); + + // Retrieves a floating point value from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param defvalue Optional default value to use if the key is not found. + // @return Floating point value of the key. + public native float GetFloat(const char[] key, float defvalue=0.0); + + // Retrieves a set of color values from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param r Red value, set by reference. + // @param g Green value, set by reference. + // @param b Blue value, set by reference. + // @param a Alpha value, set by reference. + public native void GetColor(const char[] key, int &r, int &g, int &b, int &a); + + // Retrieves a set of color values from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param color Red, green, blue, and alpha channels. + public void GetColor4(const char[] key, int color[4]) { + int r, g, b, a; + this.GetColor(key, r, g, b, a); + color[0] = r; + color[1] = g; + color[2] = b; + color[3] = a; + } + + // Retrieves a large integer value from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param value Array to represent the large integer. + // @param defvalue Optional default value to use if the key is not found. + public native void GetUInt64(const char[] key, int value[2], int defvalue[2]={0,0}); + + // Retrieves a vector value from a KeyValues key. + // + // @param key Name of the key, or NULL_STRING. + // @param vec Destination vector to store the value in. + // @param defvalue Optional default value to use if the key is not found. + public native void GetVector(const char[] key, float vec[3], const float defvalue[3]={0.0, 0.0, 0.0}); + + // Sets the current position in the KeyValues tree to the given key. + // + // @param key Name of the key. + // @param create If true, and the key does not exist, it will be created. + // @return True if the key exists, false if it does not and was not created. + public native bool JumpToKey(const char[] key, bool create=false); + + // Sets the current position in the KeyValues tree to the given key. + // + // @param id KeyValues id. + // @return True if the key exists, false if it does not. + public native bool JumpToKeySymbol(int id); + + // Sets the current position in the KeyValues tree to the first sub key. + // This native adds to the internal traversal stack. + // + // @param keyOnly If false, non-keys will be traversed (values). + // @return True on success, false if there was no first sub key. + public native bool GotoFirstSubKey(bool keyOnly=true); + + // Sets the current position in the KeyValues tree to the next sub key. + // This native does NOT add to the internal traversal stack, and thus + // GoBack() is not needed for each successive call to this function. + // + // @param keyOnly If false, non-keys will be traversed (values). + // @return True on success, false if there was no next sub key. + public native bool GotoNextKey(bool keyOnly=true); + + // Saves the current position in the traversal stack onto the traversal + // stack. This can be useful if you wish to use KvGotoNextKey() and + // have the previous key saved for backwards traversal. + // + // @param kv KeyValues Handle. + public native void SavePosition(); + + // Jumps back to the previous position. Returns false if there are no + // previous positions (i.e., at the root node). This should be called + // once for each successful Jump call, in order to return to the top node. + // This function pops one node off the internal traversal stack. + // + // @return True on success, false if there is no higher node. + public native bool GoBack(); + + // Removes the given key from the current position. + // + // @param key Name of the key. + // @return True on success, false if key did not exist. + public native bool DeleteKey(const char[] key); + + // Removes the current sub-key and attempts to set the position + // to the sub-key after the removed one. If no such sub-key exists, + // the position will be the parent key in the traversal stack. + // Given the sub-key having position "N" in the traversal stack, the + // removal will always take place from position "N-1." + // + // @param kv KeyValues Handle. + // @return 1 if removal succeeded and there was another key. + // 0 if the current node was not contained in the + // previous node, or no previous node exists. + // -1 if removal succeeded and there were no more keys, + // thus the state is as if KvGoBack() was called. + public native int DeleteThis(); + + // Sets the position back to the top node, emptying the entire node + // traversal history. This can be used instead of looping KvGoBack() + // if recursive iteration is not important. + // + // @param kv KeyValues Handle. + public native void Rewind(); + + // Retrieves the current section name. + // + // @param section Buffer to store the section name. + // @param maxlength Maximum length of the name buffer. + // @return True on success, false on failure. + public native bool GetSectionName(char[] section, int maxlength); + + // Sets the current section name. + // + // @param section Section name. + public native void SetSectionName(const char[] section); + + // Returns the data type at a key. + // + // @param key Key name. + // @return KvDataType value of the key. + public native KvDataTypes GetDataType(const char[] key); + + // Sets whether or not the KeyValues parser will read escape sequences. + // For example, \n would be read as a literal newline. This defaults + // to false for new KeyValues structures. + // + // @param useEscapes Whether or not to read escape sequences. + public native void SetEscapeSequences(bool useEscapes); + + // Returns the position in the jump stack; I.e. the number of calls + // required for KvGoBack to return to the root node. If at the root node, + // 0 is returned. + // + // @return Number of non-root nodes in the jump stack. + public native int NodesInStack(); + + // Finds a KeyValues name by id. + // + // @param id KeyValues id. + // @param name Buffer to store the name. + // @param maxlength Maximum length of the value buffer. + // @return True on success, false if id not found. + public native bool FindKeyById(int id, char[] name, int maxlength); + + // Finds a KeyValues id inside a KeyValues tree. + // + // @param key Key name. + // @param id Id of the found KeyValue. + // @return True on success, false if key not found. + public native bool GetNameSymbol(const char[] key, int &id); + + // Retrieves the current section id. + // + // @param kv KeyValues Handle. + // @param id Id of the current section. + // @return True on success, false on failure. + public native bool GetSectionSymbol(int &id); +}; + +/** + * Creates a new KeyValues structure. The Handle must always be closed. + * + * @param name Name of the root section. + * @param firstKey If non-empty, specifies the first key value. + * @param firstValue If firstKey is non-empty, specifies the first key's value. + * @return A Handle to a new KeyValues structure. + */ +native KeyValues CreateKeyValues(const char[] name, const char[] firstKey="", const char[] firstValue=""); + +/** + * Sets a string value of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value String value. + * @error Invalid Handle. + */ +native void KvSetString(Handle kv, const char[] key, const char[] value); + +/** + * Sets an integer value of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value Value number. + * @error Invalid Handle. + */ +native void KvSetNum(Handle kv, const char[] key, int value); + +/** + * Sets a large integer value of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value Large integer value (0=High bits, 1=Low bits) + * @error Invalid Handle. + */ +native void KvSetUInt64(Handle kv, const char[] key, const int value[2]); + +/** + * Sets a floating point value of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value Floating point value. + * @error Invalid Handle. + */ +native void KvSetFloat(Handle kv, const char[] key, float value); + +/** + * Sets a set of color values of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param r Red value. + * @param g Green value. + * @param b Blue value. + * @param a Alpha value. + * @error Invalid Handle. + */ +native void KvSetColor(Handle kv, const char[] key, int r, int g, int b, int a=0); + +/** + * Sets a vector value of a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param vec Vector value. + * @error Invalid Handle. + */ +native void KvSetVector(Handle kv, const char[] key, const float vec[3]); + +/** + * Retrieves a string value from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value Buffer to store key value in. + * @param maxlength Maximum length of the value buffer. + * @param defvalue Optional default value to use if the key is not found. + * @error Invalid Handle. + */ +native void KvGetString(Handle kv, const char[] key, char[] value, int maxlength, const char[] defvalue=""); + +/** + * Retrieves an integer value from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param defvalue Optional default value to use if the key is not found. + * @return Integer value of the key. + * @error Invalid Handle. + */ +native int KvGetNum(Handle kv, const char[] key, int defvalue=0); + +/** + * Retrieves a floating point value from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param defvalue Optional default value to use if the key is not found. + * @return Floating point value of the key. + * @error Invalid Handle. + */ +native float KvGetFloat(Handle kv, const char[] key, float defvalue=0.0); + +/** + * Retrieves a set of color values from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param r Red value, set by reference. + * @param g Green value, set by reference. + * @param b Blue value, set by reference. + * @param a Alpha value, set by reference. + * @error Invalid Handle. + */ +native void KvGetColor(Handle kv, const char[] key, int &r, int &g, int &b, int &a); + +/** + * Retrieves a large integer value from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param value Array to represent the large integer. + * @param defvalue Optional default value to use if the key is not found. + * @error Invalid Handle. + */ +native void KvGetUInt64(Handle kv, const char[] key, int value[2], int defvalue[2]={0,0}); + +/** + * Retrieves a vector value from a KeyValues key. + * + * @param kv KeyValues Handle. + * @param key Name of the key, or NULL_STRING. + * @param vec Destination vector to store the value in. + * @param defvalue Optional default value to use if the key is not found. + * @error Invalid Handle. + */ +native void KvGetVector(Handle kv, const char[] key, float vec[3], const float defvalue[3]={0.0, 0.0, 0.0}); + +/** + * Sets the current position in the KeyValues tree to the given key. + * + * @param kv KeyValues Handle. + * @param key Name of the key. + * @param create If true, and the key does not exist, it will be created. + * @return True if the key exists, false if it does not and was not created. + */ +native bool KvJumpToKey(Handle kv, const char[] key, bool create=false); + +/** + * Sets the current position in the KeyValues tree to the given key. + * + * @param kv KeyValues Handle. + * @param id KeyValues id. + * @return True if the key exists, false if it does not. + */ +native bool KvJumpToKeySymbol(Handle kv, int id); + +/** + * Sets the current position in the KeyValues tree to the first sub key. + * This native adds to the internal traversal stack. + * + * @param kv KeyValues Handle. + * @param keyOnly If false, non-keys will be traversed (values). + * @return True on success, false if there was no first sub key. + * @error Invalid Handle. + */ +native bool KvGotoFirstSubKey(Handle kv, bool keyOnly=true); + +/** + * Sets the current position in the KeyValues tree to the next sub key. + * This native does NOT add to the internal traversal stack, and thus + * KvGoBack() is not needed for each successive call to this function. + * + * @param kv KeyValues Handle. + * @param keyOnly If false, non-keys will be traversed (values). + * @return True on success, false if there was no next sub key. + * @error Invalid Handle. + */ +native bool KvGotoNextKey(Handle kv, bool keyOnly=true); + +/** + * Saves the current position in the traversal stack onto the traversal + * stack. This can be useful if you wish to use KvGotoNextKey() and + * have the previous key saved for backwards traversal. + * + * @param kv KeyValues Handle. + * @error Invalid Handle. + */ +native void KvSavePosition(Handle kv); + +/** + * Removes the given key from the current position. + * + * @param kv KeyValues Handle. + * @param key Name of the key. + * @return True on success, false if key did not exist. + * @error Invalid Handle. + */ +native bool KvDeleteKey(Handle kv, const char[] key); + +/** + * Removes the current sub-key and attempts to set the position + * to the sub-key after the removed one. If no such sub-key exists, + * the position will be the parent key in the traversal stack. + * Given the sub-key having position "N" in the traversal stack, the + * removal will always take place from position "N-1." + * + * @param kv KeyValues Handle. + * @return 1 if removal succeeded and there was another key. + * 0 if the current node was not contained in the + * previous node, or no previous node exists. + * -1 if removal succeeded and there were no more keys, + * thus the state is as if KvGoBack() was called. + * @error Invalid Handle. + */ +native int KvDeleteThis(Handle kv); + +/** + * Jumps back to the previous position. Returns false if there are no + * previous positions (i.e., at the root node). This should be called + * once for each successful Jump call, in order to return to the top node. + * This function pops one node off the internal traversal stack. + * + * @param kv KeyValues Handle. + * @return True on success, false if there is no higher node. + * @error Invalid Handle. + */ +native bool KvGoBack(Handle kv); + +/** + * Sets the position back to the top node, emptying the entire node + * traversal history. This can be used instead of looping KvGoBack() + * if recursive iteration is not important. + * + * @param kv KeyValues Handle. + * @error Invalid Handle. + */ +native void KvRewind(Handle kv); + +/** + * Retrieves the current section name. + * + * @param kv KeyValues Handle. + * @param section Buffer to store the section name. + * @param maxlength Maximum length of the name buffer. + * @return True on success, false on failure. + * @error Invalid Handle. + */ +native bool KvGetSectionName(Handle kv, char[] section, int maxlength); + +/** + * Sets the current section name. + * + * @param kv KeyValues Handle. + * @param section Section name. + * @error Invalid Handle. + */ +native void KvSetSectionName(Handle kv, const char[] section); + +/** + * Returns the data type at a key. + * + * @param kv KeyValues Handle. + * @param key Key name. + * @return KvDataType value of the key. + * @error Invalid Handle. + */ +native KvDataTypes KvGetDataType(Handle kv, const char[] key); + +/** + * Converts a KeyValues tree to a file. The tree is dumped + * from the current position. + * + * @param kv KeyValues Handle. + * @param file File to dump write to. + * @return True on success, false otherwise. + * @error Invalid Handle. + */ +native bool KeyValuesToFile(Handle kv, const char[] file); + +/** + * Converts a file to a KeyValues tree. The file is read into + * the current position of the tree. + * + * @param kv KeyValues Handle. + * @param file File to read from. + * @return True on success, false otherwise. + * @error Invalid Handle. + */ +native bool FileToKeyValues(Handle kv, const char[] file); + +/** + * Converts a given string to a KeyValues tree. The string is read into + * the current postion of the tree. + * + * @param kv KeyValues Handle. + * @param buffer String buffer to load into the KeyValues. + * @param resourceName The resource name of the KeyValues, used for error tracking purposes. + * @return True on success, false otherwise. + * @error Invalid Handle. + */ +native bool StringToKeyValues(Handle kv, const char[] buffer, const char[] resourceName="StringToKeyValues"); + +/** + * Sets whether or not the KeyValues parser will read escape sequences. + * For example, \n would be read as a literal newline. This defaults + * to false for new KeyValues structures. + * + * @param kv KeyValues Handle. + * @param useEscapes Whether or not to read escape sequences. + * @error Invalid Handle. + */ +native void KvSetEscapeSequences(Handle kv, bool useEscapes); + +/** + * Returns the position in the jump stack; I.e. the number of calls + * required for KvGoBack to return to the root node. If at the root node, + * 0 is returned. + * + * @param kv KeyValues Handle. + * @return Number of non-root nodes in the jump stack. + * @error Invalid Handle. + */ +native int KvNodesInStack(Handle kv); + +/** + * Makes a new copy of all subkeys in the origin KeyValues to + * the destination KeyValues. + * NOTE: All KeyValues are processed from the current location not the root one. + * + * @param origin Origin KeyValues Handle. + * @param dest Destination KeyValues Handle. + * @error Invalid Handle. + */ +native void KvCopySubkeys(Handle origin, Handle dest); + +/** + * Finds a KeyValues name by id. + * + * @param kv KeyValues Handle. + * @param id KeyValues id. + * @param name Buffer to store the name. + * @param maxlength Maximum length of the value buffer. + * @return True on success, false if id not found. + * @error Invalid Handle. + */ +native bool KvFindKeyById(Handle kv, int id, char[] name, int maxlength); + +/** + * Finds a KeyValues id inside a KeyValues tree. + * + * @param kv KeyValues Handle. + * @param key Key name. + * @param id Id of the found KeyValue. + * @return True on success, false if key not found. + * @error Invalid Handle. + */ +native bool KvGetNameSymbol(Handle kv, const char[] key, int &id); + +/** + * Retrieves the current section id. + * + * @param kv KeyValues Handle. + * @param id Id of the current section. + * @return True on success, false on failure. + * @error Invalid Handle. + */ +native bool KvGetSectionSymbol(Handle kv, int &id); |