faluco@654: /**
faluco@654:  * vim: set ts=4 :
ds@1330:  * =============================================================================
faluco@654:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
ds@1330:  * =============================================================================
ds@1330:  *
ds@1330:  * This file is part of the SourceMod/SourcePawn SDK.
faluco@654:  *
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 <http://www.gnu.org/licenses/>.
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 <http://www.sourcemod.net/license.php>.
faluco@654:  *
faluco@654:  * Version: $Id$
faluco@654:  */
faluco@654:  
faluco@654: #if defined _keyvalues_included
faluco@654:  #endinput
faluco@654: #endif
faluco@654: #define _keyvalues_included
faluco@654: 
faluco@654: /**
faluco@654:  * KeyValue data value types
faluco@654:  */
faluco@654: enum KvDataTypes
faluco@654: {
faluco@654: 	KvData_None = 0,	/**< Type could not be identified, or no type */
faluco@654: 	KvData_String,		/**< String value */
faluco@654: 	KvData_Int,			/**< Integer value */
faluco@654: 	KvData_Float,		/**< Floating point value */
faluco@654: 	KvData_Ptr,			/**< Pointer value (sometimes called "long") */
faluco@654: 	KvData_WString,		/**< Wide string value */
faluco@654: 	KvData_Color,		/**< Color value */
faluco@654: 	KvData_UInt64,		/**< Large integer value */
faluco@654: 	/* --- */
faluco@654: 	KvData_NUMTYPES, 
faluco@654: };
faluco@654: 
faluco@654: /**
faluco@654:  * Creates a new KeyValues structure.  The Handle must always be closed.
faluco@654:  *
faluco@654:  * @param name			Name of the root section.
faluco@654:  * @param firstKey		If non-empty, specifies the first key value.
faluco@654:  * @param firstValue	If firstKey is non-empty, specifies the first key's value.
faluco@654:  * @return				A Handle to a new KeyValues structure.
faluco@654:  */
dvander@725: native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
faluco@654: 
faluco@654: /** 
faluco@654:  * Sets a string value of a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			String value.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetString(Handle:kv, const String:key[], const String:value[]);
faluco@654: 
faluco@654: /** 
faluco@654:  * Sets an integer value of a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			Value number.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetNum(Handle:kv, const String:key[], value);
faluco@654: 
faluco@654: /** 
faluco@654:  * Sets a large integer value of a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			Large integer value (0=High bits, 1=Low bits)
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
dvander@816: native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
faluco@654: 
faluco@654: /** 
faluco@654:  * Sets a floating point value of a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			Floating point value.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetFloat(Handle:kv, const String:key[], Float:value);
faluco@654: 
faluco@654: /** 
faluco@654:  * Sets a set of color values of a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param r				Red value.
faluco@654:  * @param g				Green value.
faluco@654:  * @param b				Blue value.
faluco@654:  * @param a				Alpha value.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
faluco@654: 
faluco@654: /** 
faluco@654:  * Retrieves a string value from a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			Buffer to store key value in.
faluco@654:  * @param maxlength		Maximum length of the value buffer.
faluco@654:  * @param defvalue		Optional default value to use if the key is not found.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
faluco@654: 
faluco@654: /** 
faluco@654:  * Retrieves an integer value from a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param defvalue		Optional default value to use if the key is not found.
faluco@654:  * @return				Integer value of the key.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvGetNum(Handle:kv, const String:key[], defvalue=0);
faluco@654: 
faluco@654: /** 
faluco@654:  * Retrieves a floating point value from a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param defvalue		Optional default value to use if the key is not found.
faluco@654:  * @return				Floating point value of the key.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
faluco@654: 
faluco@654: /** 
faluco@654:  * Retrieves a set of color values from a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param r				Red value, set by reference.
faluco@654:  * @param g				Green value, set by reference. 
faluco@654:  * @param b				Blue value, set by reference. 
faluco@654:  * @param a				Alpha value, set by reference. 
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
faluco@654: 
faluco@654: /** 
faluco@654:  * Retrieves a large integer value from a KeyValues key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@1000:  * @param key			Name of the key, or NULL_STRING.
faluco@654:  * @param value			Array to represent the large integer.
faluco@654:  * @param defvalue		Optional default value to use if the key is not found.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
dvander@816: native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
faluco@654: 
faluco@654: /**
faluco@654:  * Sets the current position in the KeyValues tree to the given key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param key			Name of the key.
faluco@654:  * @param create		If true, and the key does not exist, it will be created.
faluco@654:  * @return				True if the key exists, false if it does not and was not created.
faluco@654:  */
faluco@654: native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
faluco@654: 
faluco@654: /**
faluco@654:  * Sets the current position in the KeyValues tree to the first sub key.
dvander@753:  * This native adds to the internal traversal stack.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@753:  * @param keyOnly		If false, non-keys will be traversed (values).
faluco@654:  * @return				True on success, false if there was no first sub key.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
dvander@753: native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
faluco@654: 
faluco@654: /**
faluco@654:  * Sets the current position in the KeyValues tree to the next sub key.
dvander@753:  * This native does NOT add to the internal traversal stack, and thus
dvander@753:  * KvGoBack() is not needed for each successive call to this function.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
dvander@753:  * @param keyOnly		If false, non-keys will be traversed (values).
faluco@654:  * @return				True on success, false if there was no next sub key.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
dvander@753: native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
dvander@753: 
dvander@753: /**
dvander@753:  * Saves the current position in the traversal stack onto the traversal
dvander@753:  * stack.  This can be useful if you wish to use KvGotoNextKey() and 
dvander@753:  * have the previous key saved for backwards traversal.
dvander@753:  *
dvander@753:  * @param kv			KeyValues Handle.
dvander@753:  * @noreturn
dvander@753:  * @error				Invalid Handle.
dvander@753:  */
dvander@753: native KvSavePosition(Handle:kv);
faluco@654: 
faluco@654: /**
dvander@743:  * Removes the given key from the current position.
dvander@743:  *
dvander@743:  * @param kv			KeyValues Handle.
dvander@743:  * @param key			Name of the key.
dvander@743:  * @return				True on success, false if key did not exist.
dvander@743:  * @error				Invalid Handle.
dvander@743:  */
dvander@743: native bool:KvDeleteKey(Handle:kv, const String:key[]);
dvander@743: 
dvander@743: /**
dvander@753:  * Removes the current sub-key and attempts to set the position
dvander@753:  * to the sub-key after the removed one.  If no such sub-key exists,
dvander@753:  * the position will be the parent key in the traversal stack.
dvander@753:  * Given the sub-key having position "N" in the traversal stack, the 
dvander@753:  * removal will always take place from position "N-1."
dvander@743:  *
dvander@743:  * @param kv			KeyValues Handle.
dvander@753:  * @return				1 if removal succeeded and there was another key.
dvander@753:  *						0 if the current node was not contained in the
dvander@753:  *						  previous node, or no previous node exists.
dvander@753:  *						-1 if removal succeeded and there were no more keys,
dvander@753:  *						  thus the state is as if KvGoBack() was called.
dvander@743:  * @error				Invalid Handle.
dvander@743:  */
dvander@753: native KvDeleteThis(Handle:kv);
dvander@743: 
dvander@743: /**
faluco@654:  * Jumps back to the previous position.  Returns false if there are no
faluco@654:  * previous positions (i.e., at the root node).  This should be called
faluco@654:  * once for each successful Jump call, in order to return to the top node.
dvander@753:  * This function pops one node off the internal traversal stack.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @return				True on success, false if there is no higher node.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native bool:KvGoBack(Handle:kv);
faluco@654: 
faluco@654: /**
faluco@654:  * Sets the position back to the top node, emptying the entire node 
faluco@654:  * traversal history.  This can be used instead of looping KvGoBack()
faluco@654:  * if recursive iteration is not important.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvRewind(Handle:kv);
faluco@654: 
faluco@654: /**
faluco@654:  * Retrieves the current section name.
faluco@654:  * 
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param section		Buffer to store the section name.
faluco@654:  * @param maxlength		Maximum length of the name buffer.
faluco@654:  * @return				True on success, false on failure.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
faluco@654: 
faluco@654: /**
faluco@654:  * Sets the current section name.
faluco@654:  * 
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param section		Section name.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetSectionName(Handle:kv, const String:section[]);
faluco@654: 
faluco@654: /**
faluco@654:  * Returns the data type at a key.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param key			Key name.
faluco@654:  * @return				KvDataType value of the key.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
faluco@654: 
faluco@654: /**
faluco@654:  * Converts a KeyValues tree to a file.  The tree is dumped
faluco@654:  * from the current position.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param file			File to dump write to.
faluco@654:  * @return				True on success, false otherwise.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native bool:KeyValuesToFile(Handle:kv, const String:file[]);
faluco@654: 
faluco@654: /**
faluco@654:  * Converts a file to a KeyValues tree.  The file is read into
faluco@654:  * the current position of the tree.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param file			File to read from.
faluco@654:  * @return				True on success, false otherwise.
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native bool:FileToKeyValues(Handle:kv, const String:file[]);
faluco@654: 
faluco@654: /**
faluco@654:  * Sets whether or not the KeyValues parser will read escape sequences.
faluco@654:  * For example, \n would be read as a literal newline.  This defaults
faluco@654:  * to false for new KeyValues structures.
faluco@654:  *
faluco@654:  * @param kv			KeyValues Handle.
faluco@654:  * @param useEscapes	Whether or not to read escape sequences.
faluco@654:  * @noreturn
faluco@654:  * @error				Invalid Handle.
faluco@654:  */
faluco@654: native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
dvander@750: 
dvander@750: /**
dvander@750:  * Returns the position in the jump stack; I.e. the number of calls
dvander@750:  * required for KvGoBack to return to the root node.  If at the root node,
dvander@750:  * 0 is returned.
dvander@750:  *
dvander@750:  * @param kv			KeyValues Handle.
dvander@750:  * @return				Number of non-root nodes in the jump stack.
dvander@750:  * @error				Invalid Handle.
dvander@750:  */
ds@913: native KvNodesInStack(Handle:kv);
faluco@1401: 
faluco@1401: /**
faluco@1401:  * Makes a new copy of all subkeys in the origin KeyValues to
faluco@1401:  * the destination KeyValues.
faluco@1401:  * NOTE: All KeyValues are processed from the current location not the root one.
faluco@1401:  *
faluco@1401:  * @param origin		Origin KeyValues Handle.
faluco@1401:  * @param dest			Destination KeyValues Handlee.
faluco@1401:  * @noreturn
faluco@1401:  * @error				Invalid Handle.
faluco@1401:  */
faluco@1401: native KvCopySubkeys(Handle:origin, Handle:dest);
faluco@1401: 
faluco@1401: /** 
faluco@1401:  * Finds a KeyValues name by id.
faluco@1401:  *
faluco@1401:  * @param kv			KeyValues Handle.
faluco@1401:  * @param id			KeyValues id.
faluco@1401:  * @param name			Buffer to store the name.
faluco@1401:  * @param maxlength		Maximum length of the value buffer.
faluco@1401:  * @return			True on success, false if id not found.
faluco@1401:  * @error				Invalid Handle.
faluco@1401:  */
faluco@1401: native bool:KvFindKeyById(Handle:kv, id, String:name[], maxlength);
faluco@1401: 
faluco@1401: /** 
faluco@1401:  * Finds a KeyValues id inside a KeyValues tree.
faluco@1401:  *
faluco@1401:  * @param kv			KeyValues Handle.
faluco@1401:  * @param key			Key name.
faluco@1401:  * @param id			Id of the found KeyValue.
faluco@1401:  * @return			True on success, false if key not found.
faluco@1401:  * @error				Invalid Handle.
faluco@1401:  */
faluco@1401: native bool:KvGetNameSymbol(Handle:kv, const String:key[], &id);