3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _keyvalues_included
36 #define _keyvalues_included
39 * KeyValue data value types
43 KvData_None = 0, /**< Type could not be identified, or no type */
44 KvData_String, /**< String value */
45 KvData_Int, /**< Integer value */
46 KvData_Float, /**< Floating point value */
47 KvData_Ptr, /**< Pointer value (sometimes called "long") */
48 KvData_WString, /**< Wide string value */
49 KvData_Color, /**< Color value */
50 KvData_UInt64, /**< Large integer value */
56 * Creates a new KeyValues structure. The Handle must always be closed.
58 * @param name Name of the root section.
59 * @param firstKey If non-empty, specifies the first key value.
60 * @param firstValue If firstKey is non-empty, specifies the first key's value.
61 * @return A Handle to a new KeyValues structure.
63 native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
66 * Sets a string value of a KeyValues key.
68 * @param kv KeyValues Handle.
69 * @param key Name of the key, or NULL_STRING.
70 * @param value String value.
72 * @error Invalid Handle.
74 native KvSetString(Handle:kv, const String:key[], const String:value[]);
77 * Sets an integer value of a KeyValues key.
79 * @param kv KeyValues Handle.
80 * @param key Name of the key, or NULL_STRING.
81 * @param value Value number.
83 * @error Invalid Handle.
85 native KvSetNum(Handle:kv, const String:key[], value);
88 * Sets a large integer value of a KeyValues key.
90 * @param kv KeyValues Handle.
91 * @param key Name of the key, or NULL_STRING.
92 * @param value Large integer value (0=High bits, 1=Low bits)
94 * @error Invalid Handle.
96 native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
99 * Sets a floating point value of a KeyValues key.
101 * @param kv KeyValues Handle.
102 * @param key Name of the key, or NULL_STRING.
103 * @param value Floating point value.
105 * @error Invalid Handle.
107 native KvSetFloat(Handle:kv, const String:key[], Float:value);
110 * Sets a set of color values of a KeyValues key.
112 * @param kv KeyValues Handle.
113 * @param key Name of the key, or NULL_STRING.
114 * @param r Red value.
115 * @param g Green value.
116 * @param b Blue value.
117 * @param a Alpha value.
119 * @error Invalid Handle.
121 native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
124 * Sets a vector value of a KeyValues key.
126 * @param kv KeyValues Handle.
127 * @param key Name of the key, or NULL_STRING.
128 * @param vec Vector value.
130 * @error Invalid Handle.
132 native KvSetVector(Handle:kv, const String:key[], const Float:vec[3]);
135 * Retrieves a string value from a KeyValues key.
137 * @param kv KeyValues Handle.
138 * @param key Name of the key, or NULL_STRING.
139 * @param value Buffer to store key value in.
140 * @param maxlength Maximum length of the value buffer.
141 * @param defvalue Optional default value to use if the key is not found.
143 * @error Invalid Handle.
145 native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
148 * Retrieves an integer value from a KeyValues key.
150 * @param kv KeyValues Handle.
151 * @param key Name of the key, or NULL_STRING.
152 * @param defvalue Optional default value to use if the key is not found.
153 * @return Integer value of the key.
154 * @error Invalid Handle.
156 native KvGetNum(Handle:kv, const String:key[], defvalue=0);
159 * Retrieves a floating point value from a KeyValues key.
161 * @param kv KeyValues Handle.
162 * @param key Name of the key, or NULL_STRING.
163 * @param defvalue Optional default value to use if the key is not found.
164 * @return Floating point value of the key.
165 * @error Invalid Handle.
167 native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
170 * Retrieves a set of color values from a KeyValues key.
172 * @param kv KeyValues Handle.
173 * @param key Name of the key, or NULL_STRING.
174 * @param r Red value, set by reference.
175 * @param g Green value, set by reference.
176 * @param b Blue value, set by reference.
177 * @param a Alpha value, set by reference.
179 * @error Invalid Handle.
181 native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
184 * Retrieves a large integer value from a KeyValues key.
186 * @param kv KeyValues Handle.
187 * @param key Name of the key, or NULL_STRING.
188 * @param value Array to represent the large integer.
189 * @param defvalue Optional default value to use if the key is not found.
191 * @error Invalid Handle.
193 native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
196 * Retrieves a vector value from a KeyValues key.
198 * @param kv KeyValues Handle.
199 * @param key Name of the key, or NULL_STRING.
200 * @param vec Destination vector to store the value in.
201 * @param defvalue Optional default value to use if the key is not found.
203 * @error Invalid Handle.
205 native KvGetVector(Handle:kv, const String:key[], Float:vec[3], const Float:defvalue[3]={0.0, 0.0, 0.0});
208 * Sets the current position in the KeyValues tree to the given key.
210 * @param kv KeyValues Handle.
211 * @param key Name of the key.
212 * @param create If true, and the key does not exist, it will be created.
213 * @return True if the key exists, false if it does not and was not created.
215 native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
218 * Sets the current position in the KeyValues tree to the given key.
220 * @param kv KeyValues Handle.
221 * @param id KeyValues id.
222 * @return True if the key exists, false if it does not.
224 native bool:KvJumpToKeySymbol(Handle:kv, id);
227 * Sets the current position in the KeyValues tree to the first sub key.
228 * This native adds to the internal traversal stack.
230 * @param kv KeyValues Handle.
231 * @param keyOnly If false, non-keys will be traversed (values).
232 * @return True on success, false if there was no first sub key.
233 * @error Invalid Handle.
235 native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
238 * Sets the current position in the KeyValues tree to the next sub key.
239 * This native does NOT add to the internal traversal stack, and thus
240 * KvGoBack() is not needed for each successive call to this function.
242 * @param kv KeyValues Handle.
243 * @param keyOnly If false, non-keys will be traversed (values).
244 * @return True on success, false if there was no next sub key.
245 * @error Invalid Handle.
247 native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
250 * Saves the current position in the traversal stack onto the traversal
251 * stack. This can be useful if you wish to use KvGotoNextKey() and
252 * have the previous key saved for backwards traversal.
254 * @param kv KeyValues Handle.
256 * @error Invalid Handle.
258 native KvSavePosition(Handle:kv);
261 * Removes the given key from the current position.
263 * @param kv KeyValues Handle.
264 * @param key Name of the key.
265 * @return True on success, false if key did not exist.
266 * @error Invalid Handle.
268 native bool:KvDeleteKey(Handle:kv, const String:key[]);
271 * Removes the current sub-key and attempts to set the position
272 * to the sub-key after the removed one. If no such sub-key exists,
273 * the position will be the parent key in the traversal stack.
274 * Given the sub-key having position "N" in the traversal stack, the
275 * removal will always take place from position "N-1."
277 * @param kv KeyValues Handle.
278 * @return 1 if removal succeeded and there was another key.
279 * 0 if the current node was not contained in the
280 * previous node, or no previous node exists.
281 * -1 if removal succeeded and there were no more keys,
282 * thus the state is as if KvGoBack() was called.
283 * @error Invalid Handle.
285 native KvDeleteThis(Handle:kv);
288 * Jumps back to the previous position. Returns false if there are no
289 * previous positions (i.e., at the root node). This should be called
290 * once for each successful Jump call, in order to return to the top node.
291 * This function pops one node off the internal traversal stack.
293 * @param kv KeyValues Handle.
294 * @return True on success, false if there is no higher node.
295 * @error Invalid Handle.
297 native bool:KvGoBack(Handle:kv);
300 * Sets the position back to the top node, emptying the entire node
301 * traversal history. This can be used instead of looping KvGoBack()
302 * if recursive iteration is not important.
304 * @param kv KeyValues Handle.
306 * @error Invalid Handle.
308 native KvRewind(Handle:kv);
311 * Retrieves the current section name.
313 * @param kv KeyValues Handle.
314 * @param section Buffer to store the section name.
315 * @param maxlength Maximum length of the name buffer.
316 * @return True on success, false on failure.
317 * @error Invalid Handle.
319 native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
322 * Sets the current section name.
324 * @param kv KeyValues Handle.
325 * @param section Section name.
327 * @error Invalid Handle.
329 native KvSetSectionName(Handle:kv, const String:section[]);
332 * Returns the data type at a key.
334 * @param kv KeyValues Handle.
335 * @param key Key name.
336 * @return KvDataType value of the key.
337 * @error Invalid Handle.
339 native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
342 * Converts a KeyValues tree to a file. The tree is dumped
343 * from the current position.
345 * @param kv KeyValues Handle.
346 * @param file File to dump write to.
347 * @return True on success, false otherwise.
348 * @error Invalid Handle.
350 native bool:KeyValuesToFile(Handle:kv, const String:file[]);
353 * Converts a file to a KeyValues tree. The file is read into
354 * the current position of the tree.
356 * @param kv KeyValues Handle.
357 * @param file File to read from.
358 * @return True on success, false otherwise.
359 * @error Invalid Handle.
361 native bool:FileToKeyValues(Handle:kv, const String:file[]);
364 * Sets whether or not the KeyValues parser will read escape sequences.
365 * For example, \n would be read as a literal newline. This defaults
366 * to false for new KeyValues structures.
368 * @param kv KeyValues Handle.
369 * @param useEscapes Whether or not to read escape sequences.
371 * @error Invalid Handle.
373 native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
376 * Returns the position in the jump stack; I.e. the number of calls
377 * required for KvGoBack to return to the root node. If at the root node,
380 * @param kv KeyValues Handle.
381 * @return Number of non-root nodes in the jump stack.
382 * @error Invalid Handle.
384 native KvNodesInStack(Handle:kv);
387 * Makes a new copy of all subkeys in the origin KeyValues to
388 * the destination KeyValues.
389 * NOTE: All KeyValues are processed from the current location not the root one.
391 * @param origin Origin KeyValues Handle.
392 * @param dest Destination KeyValues Handlee.
394 * @error Invalid Handle.
396 native KvCopySubkeys(Handle:origin, Handle:dest);
399 * Finds a KeyValues name by id.
401 * @param kv KeyValues Handle.
402 * @param id KeyValues id.
403 * @param name Buffer to store the name.
404 * @param maxlength Maximum length of the value buffer.
405 * @return True on success, false if id not found.
406 * @error Invalid Handle.
408 native bool:KvFindKeyById(Handle:kv, id, String:name[], maxlength);
411 * Finds a KeyValues id inside a KeyValues tree.
413 * @param kv KeyValues Handle.
414 * @param key Key name.
415 * @param id Id of the found KeyValue.
416 * @return True on success, false if key not found.
417 * @error Invalid Handle.
419 native bool:KvGetNameSymbol(Handle:kv, const String:key[], &id);
422 * Retrieves the current section id.
424 * @param kv KeyValues Handle.
425 * @param id Id of the current section.
426 * @return True on success, false on failure.
427 * @error Invalid Handle.
429 native bool:KvGetSectionSymbol(Handle:kv, &id);
