Today’s article is a wiki article about KeyValues (SourceMod Scripting).
While we don’t encourage using KeyValues for C++, they work quite nicely in scripts, where event based parsers are more complicated to set up, especially since dynamic structures do not otherwise exist yet.
The original API for KeyValues was very confusing, which was a direct result of Valve’s header being poorly documented. However, the current version of the API is much more useful and covers most of the use cases as easily as possible. The wiki article goes into detail about iteration, traversal, and deletion.
The only noteworthy (and confusing) thing about SourceMod’s KeyValues API is the traversal stack. Why does it maintain an internal stack of how deep you’ve nested? Because the only other solution would be to return a new Handle. Observe the difference:
native bool:KvFindKey(Handle:kv, const String:name);
native Handle:KvFindKey(Handle:kv, const String:name);
In the second example, the user must explicitly call CloseHandle simply for finding a sub-section. Not only is this extremely annoying, but also inefficient, and would lead to a myriad of memory leaks due to people forgetting to close simple iterations everywhere.
C++ users don’t have to worry about this, of course. This is a consequence of pointers needing to be stuffed through Handles combined with the lack of a garbage collector.