KeyValues (SourceMod Scripting)

KeyValues are simple, tree-based structures used for storing nested sections containing key/value pairs. Detailed information on KeyValues can be seen at the Valve Developer Wiki.

All KeyValues specific functions in this document are from public/include/keyvalues.inc.

Introduction

KeyValues consist of a nodes, or sections, which contain pairs of keys and values. A section looks like this:

"section"
{
	"key"	"value"
}

The "section" string denotes the section's name. The "key" string is the key name, and the "value"" string is the value.

KeyValues structures are created with CreateKeyValues(). The Handle must be freed when finished in order to avoid a memory leak.

Files

KeyValues can be exported and imported via KeyValues files. These files always consist of a root node and any number of sub-keys or sub-sections. For example, a file might look like this:

"MyFile"
{
	"STEAM_0:0:7"
	{
		"name"		"crab"
	}
}

In this example, STEAM_0:0:7 is a section under MyFile, the root node.

To load KeyValues from a file, use FileToKeyValues To save KeyValues to a file, use KeyValuesToFile. For both cases, you must already have a Handle to a KeyValues structure.

Traversal

SourceMod provides natives for traversing over a KeyValues structure. However, it is important to understand how this traversal works. Internally, SourceMod keeps track of two pieces of information:

• The root node
• A traversal stack

Since a KeyValues structure is inherently recursive (it's a tree), the traversal stack is used to save a history of each traversal made (a traversal being a recursive dive into the tree, where the current nesting level deepens by one section). The top of this stack is where all operations take place.

For example, kv.JumpToKey will attempt to find a sub-key under the current section. If it succeeds, the position in the tree has changed by moving down one level, and thus this position is pushed onto the traversal stack. Now, operations such as kv.GetString will use this new position.

There are natives which change the position but do not change the traversal stack. For example, kv.GotoNextKey will change the current section being viewed, but there are no push/pop operations to the traversal stack. This is because the nesting level did not change; it advances to the next section at the same level, rather than finding a section a level deeper.

More traversal natives:

• kv.GotoFirstSubKey - Finds the first sub-section under the current section. This pushes the section onto the traversal stack.
• kv.GoBack - Pops the traversal stack (moves up one level).
• kv.Rewind - Clears the traversal stack so the current position is the root node.

Basic Lookup

Let's take our MyFile example from above. How could we retrieve the name "crab" given the Steam ID?

bool GetNameFromSteamID(const char[] steamid, char[] name, int maxlength)
{
	KeyValues kv = new KeyValues("MyFile");
	kv.ImportFromFile("myfile.txt");
	if (!kv.JumpToKey(steamid))
	{
		return false;
	}
	kv.GetString("name", name, maxlength);
	delete kv;
	return true;
}

Note: kv.JumpToKey is a traversal native that changes the nesting level of the traversal stack. However, delete will not accidentally close only the current level of the KeyValues structure. It will close the entire thing.

Iterative Lookup

Let's modify our previous example to use iteration. This has the same functionality, but demonstrates how to browse over many sections.

bool GetNameFromSteamID(const char[] steamid, char[] name,int maxlength)
{
	KeyValues kv = new KeyValues("MyFile");
	kv.ImportFromFile("myfile.txt");
 
	if (!kv.GotoFirstSubKey())
	{
		return false;
	}
 
	char buffer[255];
	do
	{
		kv.GetSectionName(buffer, sizeof(buffer));
		if (StrEqual(buffer, steamid))
		{
			kv.GetString("name", name, maxlength);
			delete kv;
			return true;
		}
	} while (kv.GotoNextKey());
 
	delete kv;
	return false;
}

Note: In this example, note that kv.GotoNextKey is an iterative function, not a traversal one. Since it does not change the nesting level, we don't need to call kv.GoBack to return and continue iterating.

Full Traversal

Let's say we wanted to browse every section of a KeyValues file. An example of this might look like:

BrowseKeyValues(Handle:kv)
{
	do
	{
		// You can read the section/key name by using KvGetSectionName here.
 
		if (KvGotoFirstSubKey(kv, false))
		{
			// Current key is a section. Browse it recursively.
			BrowseKeyValues(kv);
			KvGoBack(kv);
		}
		else
		{
			// Current key is a regular key, or an empty section.
			if (KvGetDataType(kv, NULL_STRING) != KvData_None)
			{
				// Read value of key here (use NULL_STRING as key name). You can
				// also get the key name by using KvGetSectionName here.
			}
			else
			{
				// Found an empty sub section. It can be handled here if necessary.
			}
		}
	} while (KvGotoNextKey(kv, false));
}

This function will browse an entire KeyValues structure. Note that every successful call to KvGotoFirstSubKey is paired with a call to KvGoBack. This is because the former pushes onto the traversal stack. We must pop the position off so we can continue browsing from our old position.

Also note that keyOnly is set to false in both KvGotoFirstSubKey and KvGotoNextKey so that it will jump to regular keys and not just between sections. Because of this we also need to check if KvGotoFirstSubKey succeeded moving to a regular key before we read the value. This is simply done by getting the data type of the current key. If KvGotoFirstSubKey failed to move to any key (the section is empty), the cursor is still on the section, which doesn't have a data type. If there is a data type, we've confirmed that it's a regular key.

Deletion

There are two ways to delete sections from a KeyValues structure:

• KvDeleteKey - Safely removes a named sub-section and any of its child sections/keys.
• KvDeleteThis - Safely removes the current position if possible.

Simple Deletion

First, let's use our "basic lookup" example to delete a Steam ID section:

RemoveSteamID(const String:steamid[])
{
	new Handle:kv = CreateKeyValues("MyFile");
	FileToKeyValues(kv, "myfile.txt");
	if (!KvJumpToKey(kv, steamid))
	{
		return;
	}
	KvDeleteThis(kv);
	KvRewind(kv);
	KeyValuesToFile(kv, "myfile.txt");
	CloseHandle(kv);
}

Note: We called KvRewind so the file would be dumped from the root position, instead of the current one.

Iterative Deletion

Likewise, let's show how our earlier iterative example could be adapted for deleting a section. For this we can use KvDeleteThis, which deletes the current position from the previous position in the traversal stack.

RemoveSteamID(const String:steamid[])
{
	new Handle:kv = CreateKeyValues("MyFile")
	FileToKeyValues(kv, "myfile.txt")
 
	if (!KvGotoFirstSubKey(kv))
	{
		return
	}
 
	decl String:buffer[255]
	do
	{
		KvGetSectionName(kv, buffer, sizeof(buffer))
		if (StrEqual(buffer, steamid))
		{
			KvDeleteThis(kv)
			CloseHandle(kv)
			return
		}
	} while (KvGotoNextKey(kv))
 
	CloseHandle(kv)
}

Full Deletion

Now, let's take a look at how we would delete all (or some) keys. KvDeleteThis has the special property that it can act as an automatic iterator. When it deletes a key, it automatically attempts to advance to the next one, as KvGotoNextKey would. If it can't find any more keys, it simply pops the traversal stack.

An example of deleting all SteamIDs that have blank names:

DeleteAll(Handle:kv)
{
	if (!KvGotoFirstSubKey(kv))
	{
		return
	}
 
	for (;;)
	{
		decl String:name[4]
		KvGetString(kv, name, sizeof(name))
		if (name[0] == '\0')
		{
			if (KvDeleteThis(kv) < 1)
			{
				break
			}
		} else if (!KvGotoNextKey(kv)) {
			break
		}	
	}
}

While at first this loop looks infinite, it is not. If KvDeleteThis fails to find a subsequent key, it will break out of the loop. Similarly, if KvGotoNextKey fails, the loop will end.

KeyValue Creation

This is how you would create the MyFile example from above with the KeyValue API

new Handle:kv = CreateKeyValues("MyFile");
KvJumpToKey(kv, "STEAM_0:0:7", true);
KvSetString(kv, "name", "crab");
KvRewind(kv);
KeyValuesToFile(kv, "C:\javalia.txt");
CloseHandle(kv);

Warning: This template (and by extension, language format) should not be used, any pages using it should be switched to Template:Languages
View this page in:  English  Russian  简体中文(Simplified Chinese)