Ru:KeyValues (SourceMod Scripting)

KeyValues это простая древовидная структура используемая для хранения вложенных разделов состоящих из пар ключ/значение. Детальная информация про KeyValues может быть найдена на Valve Developer Wiki.

Все KeyValues функции в этом документе находятся в public/include/keyvalues.inc.

Введение

KeyValues состоит из узлов и разделов, которые содержат пары ключей и значений. Разделы выглядят примерно так:

"раздел"
{
	"ключ"	"значение"
}

Сторка "раздел" является именем раздела. Строка "ключ" это имя ключа и строка "значение"" является значением.

KeyValues структуры создаются с помощью CreateKeyValues(). Handle должен быть освобожден после завершения работы для устранения утечки памяти.

Файлы

KeyValues могут быть экспортированы и импортированы с помощью KeyValues файлов. Эти файлы всегда состоят из главного узла и множества под-ключей или подразделов. Например файл может выглядеть вот так:

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

В этом примере STEAM_0:0:7 это раздел под главным узлом MyFile.

Для загрузки KeyValues из файла используйте FileToKeyValues. Для сохранения KeyValues в файл используйте KeyValuesFromFile. Для обоих случае вы всегда должны иметь Handle ссылающийся на KeyValues структуру.

Перемещение

SourceMod обеспечивает нативное перемещение по KeyValues структуре. Однако очень важно понимать как происходит это перемещение. Внутренне, SourceMod отслеживает из двух частей информации:

• Главный узел
• Стек перемещения

Поскольку структура KeyValues изначально рекурсивная (это дерево), стек перемещения используется для сохранения истории каждого перемещения (перемещение начинается рекурсивно погружаться в дерево, где текущий уровень вложенности углубляется на одну секцию). верх этого стека где все операции имеют место..

Например, KvJumpToKey будет пытаться найтим под-ключ под текущим разделом. При успехе позиция в дереве изменяется перемещением вниз на один уровень, и, следовательно, эта позиция помещается в стек перемещения. Теперь операции такие как KvGetString будут использовать эту новую позицию.

Это нативные изменяют положение, но не меняют стек перемещения. Например, KvGotoNextKey будет менять текущий раздел перед просмотром, но это не является push/pop операциями для стека перемещения. Это потому, что уровень вложенности не изменился; он проходит в следующий раздел на том же уровне, скорее чем найти секцию уровнем глубже.

Больше нативных перемещений:

• KvGotoFirstSubKey - Находит первый подраздел ниже текущей позиции. Это помещает раздел на стек перемещения.
• KvGoBack - Берет из стека перемещения (поднимается на уровень выше).
• KvRewind - Стирает из стека перемещения текущую позицию в главном узле.

Основной Просмотр

Давайте возьмем наш пример MyFile. Как мы можем получить имя "crab" учитывая Steam ID?

bool:GetNameFromSteamID(const String:steamid[], String:name[], maxlength)
{
	new Handle:kv = CreateKeyValues("MyFile");
	FileToKeyValues(kv, "myfile.txt");
	if (!KvJumpToKey(kv, steamid))
	{
		return false;
	}
	KvGetString(kv, "name", name, maxlength);
	CloseHandle(kv);
	return true;
}

Обратите внимание: KvJumpToKey является нативным перемещением, что изменения уровней вложенности стека перемещения. Однако CloseHandle не будет случайно закрывать текущий уровень структуры KeyValues. Это закроет всю вещь.

Повторяющийся просмотр

Давайте модифицируер предыдущий пример для использования повторов. Это имеет ту же функциональность, но демонстрирует, как для просмотра в течение многих разделах.

bool:GetNameFromSteamID(const String:steamid[], String:name[], maxlength)
{
	new Handle:kv = CreateKeyValues("MyFile");
	FileToKeyValues(kv, "myfile.txt");
 
	if (!KvGotoFirstSubKey(kv))
	{
		return false;
	}
 
	decl String:buffer[255];
	do
	{
		KvGetSectionName(kv, buffer, sizeof(buffer));
		if (StrEqual(buffer, steamid))
		{
			KvGetString(kv, "name", name, maxlength);
			CloseHandle(kv);
			return true;
		}
	} while (KvGotoNextKey(kv));
 
	CloseHandle(kv)
	return false
}

Обратите внимание: В этом примере отметим что KvGotoNextKey является итеративной функции, не однократное перемещение. Так как это не меняет уровень вложенности, мы не должны вызывать KvGoBack для возврата и продолжения итерации.

Полное Перемещение

Например мы хотим просмотреть каждую секцию файла KeyValues. Пример как это может выглядеть:

BrowseKeyValues(Handle:kv)
{
	do
	{
		if (KvGotoFirstSubKey(kv))
		{
			BrowseKeyValues(kv);
			KvGoBack(kv);
		}
	} while (KvGotoNextKey(kv));
}

Эта функция будет просматривать всю структуру KeyValues. Обратите внимаеие, что каждый успешный вызов KvGotoFirstSubKey сопровождается вызовом KvGoBack. Это потому, что первый помещается в стек перемещения. Мы должны взять позицию для того, чтоб могли продолжить просмотр с нашей старой позиции.

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 (!KvGotoFirstSubKey(kv))
	{
		return
	}
	KvDeleteKey(kv, steamid)
	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

Lastly, 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.