sourcemod-central: plugins/include/keyvalues.inc@432f5aed9b1e

     1 /**

     2  * vim: set ts=4 :

     3  * ===============================================================

     4  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.

     5  * ===============================================================

     6  *

     7  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used

     8  * or modified under the Terms and Conditions of its License Agreement, which is found

     9  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins

    10  * may change at any time.  To view the latest information, see:

    11  *   http://www.sourcemod.net/license.php

    12  *

    13  * Version: $Id$

    14  */

    16 #if defined _keyvalues_included

    17  #endinput

    18 #endif

    19 #define _keyvalues_included

    21 /**

    22  * KeyValue data value types

    23  */

    24 enum KvDataTypes

    25 {

    26 	KvData_None = 0,	/**< Type could not be identified, or no type */

    27 	KvData_String,		/**< String value */

    28 	KvData_Int,			/**< Integer value */

    29 	KvData_Float,		/**< Floating point value */

    30 	KvData_Ptr,			/**< Pointer value (sometimes called "long") */

    31 	KvData_WString,		/**< Wide string value */

    32 	KvData_Color,		/**< Color value */

    33 	KvData_UInt64,		/**< Large integer value */

    34 	/* --- */

    35 	KvData_NUMTYPES,

    36 };

    38 /**

    39  * Creates a new KeyValues structure.  The Handle must always be closed.

    40  *

    41  * @param name			Name of the root section.

    42  * @param firstKey		If non-empty, specifies the first key value.

    43  * @param firstValue	If firstKey is non-empty, specifies the first key's value.

    44  * @return				A Handle to a new KeyValues structure.

    45  */

    46 native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");

    48 /**

    49  * Sets a string value of a KeyValues key.

    50  *

    51  * @param kv			KeyValues Handle.

    52  * @param key			Name of the key.

    53  * @param value			String value.

    54  * @noreturn

    55  * @error				Invalid Handle.

    56  */

    57 native KvSetString(Handle:kv, const String:key[], const String:value[]);

    59 /**

    60  * Sets an integer value of a KeyValues key.

    61  *

    62  * @param kv			KeyValues Handle.

    63  * @param key			Name of the key.

    64  * @param value			Value number.

    65  * @noreturn

    66  * @error				Invalid Handle.

    67  */

    68 native KvSetNum(Handle:kv, const String:key[], value);

    70 /**

    71  * Sets a large integer value of a KeyValues key.

    72  *

    73  * @param kv			KeyValues Handle.

    74  * @param key			Name of the key.

    75  * @param value			Large integer value (0=High bits, 1=Low bits)

    76  * @noreturn

    77  * @error				Invalid Handle.

    78  */

    79 native KvSetUint64(Handle:kv, const String:key[], const value[2]);

    81 /**

    82  * Sets a floating point value of a KeyValues key.

    83  *

    84  * @param kv			KeyValues Handle.

    85  * @param key			Name of the key.

    86  * @param value			Floating point value.

    87  * @noreturn

    88  * @error				Invalid Handle.

    89  */

    90 native KvSetFloat(Handle:kv, const String:key[], Float:value);

    92 /**

    93  * Sets a set of color values of a KeyValues key.

    94  *

    95  * @param kv			KeyValues Handle.

    96  * @param key			Name of the key.

    97  * @param r				Red value.

    98  * @param g				Green value.

    99  * @param b				Blue value.

   100  * @param a				Alpha value.

   101  * @noreturn

   102  * @error				Invalid Handle.

   103  */

   104 native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);

   106 /**

   107  * Retrieves a string value from a KeyValues key.

   108  *

   109  * @param kv			KeyValues Handle.

   110  * @param key			Name of the key.

   111  * @param value			Buffer to store key value in.

   112  * @param maxlength		Maximum length of the value buffer.

   113  * @param defvalue		Optional default value to use if the key is not found.

   114  * @noreturn

   115  * @error				Invalid Handle.

   116  */

   117 native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");

   119 /**

   120  * Retrieves an integer value from a KeyValues key.

   121  *

   122  * @param kv			KeyValues Handle.

   123  * @param key			Name of the key.

   124  * @param defvalue		Optional default value to use if the key is not found.

   125  * @return				Integer value of the key.

   126  * @error				Invalid Handle.

   127  */

   128 native KvGetNum(Handle:kv, const String:key[], defvalue=0);

   130 /**

   131  * Retrieves a floating point value from a KeyValues key.

   132  *

   133  * @param kv			KeyValues Handle.

   134  * @param key			Name of the key.

   135  * @param defvalue		Optional default value to use if the key is not found.

   136  * @return				Floating point value of the key.

   137  * @error				Invalid Handle.

   138  */

   139 native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);

   141 /**

   142  * Retrieves a set of color values from a KeyValues key.

   143  *

   144  * @param kv			KeyValues Handle.

   145  * @param key			Name of the key.

   146  * @param r				Red value, set by reference.

   147  * @param g				Green value, set by reference.

   148  * @param b				Blue value, set by reference.

   149  * @param a				Alpha value, set by reference.

   150  * @noreturn

   151  * @error				Invalid Handle.

   152  */

   153 native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);

   155 /**

   156  * Retrieves a large integer value from a KeyValues key.

   157  *

   158  * @param kv			KeyValues Handle.

   159  * @param key			Name of the key.

   160  * @param value			Array to represent the large integer.

   161  * @param defvalue		Optional default value to use if the key is not found.

   162  * @noreturn

   163  * @error				Invalid Handle.

   164  */

   165 native KvGetUint64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});

   167 /**

   168  * Sets the current position in the KeyValues tree to the given key.

   169  *

   170  * @param kv			KeyValues Handle.

   171  * @param key			Name of the key.

   172  * @param create		If true, and the key does not exist, it will be created.

   173  * @return				True if the key exists, false if it does not and was not created.

   174  */

   175 native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);

   177 /**

   178  * Sets the current position in the KeyValues tree to the first sub key.

   179  * This native adds to the internal traversal stack.

   180  *

   181  * @param kv			KeyValues Handle.

   182  * @param keyOnly		If false, non-keys will be traversed (values).

   183  * @return				True on success, false if there was no first sub key.

   184  * @error				Invalid Handle.

   185  */

   186 native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);

   188 /**

   189  * Sets the current position in the KeyValues tree to the next sub key.

   190  * This native does NOT add to the internal traversal stack, and thus

   191  * KvGoBack() is not needed for each successive call to this function.

   192  *

   193  * @param kv			KeyValues Handle.

   194  * @param keyOnly		If false, non-keys will be traversed (values).

   195  * @return				True on success, false if there was no next sub key.

   196  * @error				Invalid Handle.

   197  */

   198 native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);

   200 /**

   201  * Saves the current position in the traversal stack onto the traversal

   202  * stack.  This can be useful if you wish to use KvGotoNextKey() and

   203  * have the previous key saved for backwards traversal.

   204  *

   205  * @param kv			KeyValues Handle.

   206  * @noreturn

   207  * @error				Invalid Handle.

   208  */

   209 native KvSavePosition(Handle:kv);

   211 /**

   212  * Removes the given key from the current position.

   213  *

   214  * @param kv			KeyValues Handle.

   215  * @param key			Name of the key.

   216  * @return				True on success, false if key did not exist.

   217  * @error				Invalid Handle.

   218  */

   219 native bool:KvDeleteKey(Handle:kv, const String:key[]);

   221 /**

   222  * Removes the current sub-key and attempts to set the position

   223  * to the sub-key after the removed one.  If no such sub-key exists,

   224  * the position will be the parent key in the traversal stack.

   225  * Given the sub-key having position "N" in the traversal stack, the

   226  * removal will always take place from position "N-1."

   227  *

   228  * @param kv			KeyValues Handle.

   229  * @return				1 if removal succeeded and there was another key.

   230  *						0 if the current node was not contained in the

   231  *						  previous node, or no previous node exists.

   232  *						-1 if removal succeeded and there were no more keys,

   233  *						  thus the state is as if KvGoBack() was called.

   234  * @error				Invalid Handle.

   235  */

   236 native KvDeleteThis(Handle:kv);

   238 /**

   239  * Jumps back to the previous position.  Returns false if there are no

   240  * previous positions (i.e., at the root node).  This should be called

   241  * once for each successful Jump call, in order to return to the top node.

   242  * This function pops one node off the internal traversal stack.

   243  *

   244  * @param kv			KeyValues Handle.

   245  * @return				True on success, false if there is no higher node.

   246  * @error				Invalid Handle.

   247  */

   248 native bool:KvGoBack(Handle:kv);

   250 /**

   251  * Sets the position back to the top node, emptying the entire node

   252  * traversal history.  This can be used instead of looping KvGoBack()

   253  * if recursive iteration is not important.

   254  *

   255  * @param kv			KeyValues Handle.

   256  * @noreturn

   257  * @error				Invalid Handle.

   258  */

   259 native KvRewind(Handle:kv);

   261 /**

   262  * Retrieves the current section name.

   263  *

   264  * @param kv			KeyValues Handle.

   265  * @param section		Buffer to store the section name.

   266  * @param maxlength		Maximum length of the name buffer.

   267  * @return				True on success, false on failure.

   268  * @error				Invalid Handle.

   269  */

   270 native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);

   272 /**

   273  * Sets the current section name.

   274  *

   275  * @param kv			KeyValues Handle.

   276  * @param section		Section name.

   277  * @noreturn

   278  * @error				Invalid Handle.

   279  */

   280 native KvSetSectionName(Handle:kv, const String:section[]);

   282 /**

   283  * Returns the data type at a key.

   284  *

   285  * @param kv			KeyValues Handle.

   286  * @param key			Key name.

   287  * @return				KvDataType value of the key.

   288  * @error				Invalid Handle.

   289  */

   290 native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);

   292 /**

   293  * Converts a KeyValues tree to a file.  The tree is dumped

   294  * from the current position.

   295  *

   296  * @param kv			KeyValues Handle.

   297  * @param file			File to dump write to.

   298  * @return				True on success, false otherwise.

   299  * @error				Invalid Handle.

   300  */

   301 native bool:KeyValuesToFile(Handle:kv, const String:file[]);

   303 /**

   304  * Converts a file to a KeyValues tree.  The file is read into

   305  * the current position of the tree.

   306  *

   307  * @param kv			KeyValues Handle.

   308  * @param file			File to read from.

   309  * @return				True on success, false otherwise.

   310  * @error				Invalid Handle.

   311  */

   312 native bool:FileToKeyValues(Handle:kv, const String:file[]);

   314 /**

   315  * Sets whether or not the KeyValues parser will read escape sequences.

   316  * For example, \n would be read as a literal newline.  This defaults

   317  * to false for new KeyValues structures.

   318  *

   319  * @param kv			KeyValues Handle.

   320  * @param useEscapes	Whether or not to read escape sequences.

   321  * @noreturn

   322  * @error				Invalid Handle.

   323  */

   324 native KvSetEscapeSequences(Handle:kv, bool:useEscapes);

   326 /**

   327  * Returns the position in the jump stack; I.e. the number of calls

   328  * required for KvGoBack to return to the root node.  If at the root node,

   329  * 0 is returned.

   330  *

   331  * @param kv			KeyValues Handle.

   332  * @return				Number of non-root nodes in the jump stack.

   333  * @error				Invalid Handle.

   334  */

   335 native KvNodesInStack(Handle:kv);

author	David Anderson <dvander@alliedmods.net>
	Wed May 16 01:17:14 2007 +0000 (2007-05-16)
changeset 800	432f5aed9b1e
parent 753	41f5156d0e63
child 816	f5551f32680b
permissions	-rw-r--r--