AlliedModders - [EXTENSION] Config (1.0.2)

This extension provides a simple and comfortable configuration storage system suitable for both simple and advanced configurations. It is a wrapper for libconfig.

An extensive example for the format is available at http://www.hyperrealm.com/libconfig/test.cfg.txt

Installation

extract the attached config.zip file to your mod folder.

Configuration file format documentation

Located at http://www.hyperrealm.com/libconfig/...guration-Files

Configuration file grammar

Located at http://www.hyperrealm.com/libconfig/...n-File-Grammar

Examples

Load a simple configuration file with a few scalar settings (convar style, access setting values directly)

Example configuration file (addons/sourcemod/configs/IRC_Relay_-_Core_Plugin_Olly.conf (auto-generated from plugin name+author)):

PHP Code:


		
			
//********************************************************* 
//*  IRC Relay Core 
//********************************************************* 
irc_server = "irc.gamesurge";
irc_port = 6667;
irc_password = "";
irc_nickname = "IRCRelay";
 
// NAME CANNOT CONTAIN SPACES, OR QUOTES (This will be the bot trigger too!) 
irc_name = "eu.test";
 
// The delay from each message dispatch from the message queue 
irc_flood_limit = 0.5;
// [...]

Example SourceMod script:

PHP Code:


		
			
// We can use OnPluginStart() since it doesn't depend on the Source config+
// convar stuff
public OnPluginStart() {
    // create a new empty config object
    new Handle:config = ConfigCreate();

    // Load a config from a file
    // The filename is optional, the extension will automatically generate it
    // from the plugin's name+author
    if (!ConfigReadFile(config)) {
        LogError("can't read config file");
        return;
    }

    decl String:IRCServer[30];
    // retrieve a string from the config
    ConfigLookupString(config, "irc_server", IRCServer, sizeof(IRCServer));
    // retrieve a cell (integer) from the config
    new Port = ConfigLookupInt(config, "irc_port");
    // retrieve a float from the config
    new Float:FloodLimit = ConfigLookupFloat(config, "irc_flood_limit");
    // [...] (load more config settings here)

    // close the config handle
    CloseHandle(config);
}

Load a more advanced configuration file

Example configuration file (from message relay):

PHP Code:


		
			
/*
 * Message relay configuration file
 */

// prefix required to relay messages, set to "" for all
say_prefix = "+";

// output formatting
output = "[%remotehost]  %nick: %message";

// your server's ip
localhost = {
    host = "1.2.3.4";
    port = 48476;
};

// remote hosts to relay to
remotehosts = (
    { host = "3.4.5.6";
      port = 48476; },
    { host = "example.player.to";
      port = 48476; },
    { host = "5.6.7.8";
      port = 48476; }
);

Example SourceMod script:

PHP Code:


		
			
public OnPluginStart() {
    new Handle:config = ConfigCreate();

    if (!ConfigReadFile(config)) {
        LogError("can't read config file");
        return;
    }

    decl String:prefix[20];
    ConfigLookupString(config, "say_prefix", prefix, sizeof(prefix));

    decl String:outputFormat[100];
    ConfigLookupString(config, "output", outputFormat, sizeof(outputFormat));

    decl String:localHost[25];
    // . separates setting names in a path
    ConfigLookupString(config, "localhost.host",localHost,sizeof(localHost));

    new localPort = ConfigLookupInt(config, "localhost.port");

    // get parent setting containing the remote host groups
    new Handle:parent = ConfigLookup(config, "remotehosts");

    // get amount of children
    new length = ConfigSettingLength(parent);

    // iterate through children
    for (new i=0; i<length; i++) {
        // retrieve child setting (the group with remoteHost's host+port)
        new Handle:child = ConfigSettingGetElement(parent, i);

        // retrieve child "host" from the group
        new Handle:childHost = ConfigSettingGetMember(child, "host");
        // store host in a string
        decl String:remoteHost[25];
        ConfigSettingGetString(childHost, remoteHost, sizeof(remoteHost));

        // retrieve child "port" from the group
        new Handle:childPort = ConfigSettingGetMember(child, "port");
        // get the port
        new remotePort = ConfigSettingGetInt(childPort);

        // [...] do something with remoteHost+remotePort
        // don't close setting handles, only config handles!
    }

     // close the config handle
    CloseHandle(config);
}

Usage (Note: You won't need all of these natives)

A configuration will be represented by a config object which consists of several setting objects arranged in a tree structure. There is always an implicit root setting which is a group (type).

You always have to close handles to config objects (only created by ConfigCreate()) but must not close handles to setting objects which will be closed by the extension as soon as the config object or linked setting object is destroyed.

Settings with an aggregate type can have child (=sub) settings. Aggregate types are group, array and list, scalar types are int/cell, float, bool and string.

Refer to http://www.hyperrealm.com/libconfig/...guration-Files for explaination of the individual types.

General

PHP Code:


		
			
native Handle:ConfigCreate();

Create a new empty config object, returns a config handle. This handle has to be closed with CloseHandle().

File import/export

The FileName parameter for these natives is optional. The extension will automatically generate one from the plugin's name and author if it's missing.

PHP Code:


		
			
native bool:ConfigFileExists(const String:FileName[]="");

Returns whether a configuration file exists.

PHP Code:


		
			
native bool:ConfigReadFile(Handle:Config, const String:FileName[]="", String:ErrorMsg[]="", MaxLength=0, &ErrorLine=0);

Reads a configuration file into a config object. It'll clear the config object before.

PHP Code:


		
			
native bool:ConfigWriteFile(Handle:Config, const String:FileName[]="");

Writes a config object to a file.

Retrieve the value directly from a config object

PHP Code:


		
			
native ConfigLookupInt(Handle:Config, const String:Path[]);
native Float:ConfigLookupFloat(Handle:Config, const String:Path[]);
native bool:ConfigLookupBool(Handle:Config, const String:Path[]);

Returns the requested value or 0 on failure.

PHP Code:


		
			
native bool:ConfigLookupString(Handle:Config, const String:Path[], String:Result[], MaxLength);

Sets Result to the requested value, returns whether the path lookup+type check was successful.

Retrieve a setting object from a config object

PHP Code:


		
			
native Handle:ConfigLookup(Handle:Config, const String:Path[]);

Returns the setting object or INVALID_HANDLE on failure (invalid path). This handle must not be freed, the extension will free it after the config handle has been destroyed.

Retrieve the value from a scalar setting object

PHP Code:


		
			
native ConfigSettingGetIntElement(Handle:Setting, Index);
native Float:ConfigSettingGetFloatElement(Handle:Setting, Index);
native bool:ConfigSettingGetBoolElement(Handle:Setting, Index);

Returns the requested value or 0 on failure.

PHP Code:


		
			
native bool:ConfigSettingGetString(Handle:Setting, String:Result[], MaxLength);

Sets Result to the requested value, returns whether the type check was successful.

Set the value of a (scalar) setting object

PHP Code:


		
			
native bool:ConfigSettingSetInt(Handle:Setting, Value);
native bool:ConfigSettingSetFloat(Handle:Setting, Float:Value);
native bool:ConfigSettingSetBool(Handle:Setting, bool:Value);
native bool:ConfigSettingSetString(Handle:Setting, const String:Value[]);

Sets the setting object's value to a Value, returns whether the type check was successful.

Retrieve a child setting object handle of a (aggregate) setting object (Note: Usually these may be not used in conjunction with the *Element natives)

PHP Code:


		
			
native Handle:ConfigSettingGetMember(Handle:Setting, String:Name[]);

Returns the handle of a child setting with a specific name or INVALID_HANDLE on failure.

PHP Code:


		
			
native Handle:ConfigSettingGetElement(Handle:Setting, Index);

Returns handle of the nth child setting where n=Index starting from 0 or INVALID_HANDLE on failure.

Retrieve the value of the nth child setting object of an aggregate setting object

PHP Code:


		
			
native ConfigSettingGetIntElement(Handle:Setting, Index);
native Float:ConfigSettingGetFloatElement(Handle:Setting, Index);
native bool:ConfigSettingGetBoolElement(Handle:Setting, Index);

Returns the requested value or 0 on failure.

PHP Code:


		
			
native bool:ConfigSettingGetStringElement(Handle:Setting, Index, String:Result[], MaxLength);

Sets Result to the requested value, returns whether the lookup+type check was successful.

Set the value of the nth child setting object of an aggregate setting object

PHP Code:


		
			
native bool:ConfigSettingSetIntElement(Handle:Setting, Index, Value);
native bool:ConfigSettingSetFloatElement(Handle:Setting, Index, Float:Value);
native bool:ConfigSettingSetBoolElement(Handle:Setting, Index, bool:Value);
native bool:ConfigSettingSetStringElement(Handle:Setting, Index, const String:Value[]);

Sets the setting object's Indexth child's value to a Value, returns whether the lookup+type check was successful.

Add+Remove settings

PHP Code:


		
			
native Handle:ConfigSettingAdd(Handle:ParentSetting, String:Name[], SettingType:Type);

Adds a new child setting to ParentSetting. Name will not be used if ParentSetting is an array or a list. Returns the newly created setting object's handle or INVALID_HANDLE on failure (parent is no aggregate setting, name ambiguous or invalid type)

PHP Code:


		
			
native bool:ConfigSettingRemove(Handle:ParentSetting, String:Name[]);

Removes and destroys the childsetting named Name from ParentSetting recursively. All handles to destroyed settings will be closed. Returns whether the operation was successful.

Root setting

PHP Code:


		
			
native Handle:ConfigRootSetting(Handle:Config);

Returns a handle to the root setting object which is always a group and implicitly defined.

Setting information

PHP Code:


		
			
native ConfigSettingName(Handle:Setting, String:Result[], MaxLength);

Sets Result to the Name of a Setting object.

PHP Code:


		
			
native ConfigSettingLength(Handle:Setting);

Returns the amount of child settings under Setting. Use it for iterating.

PHP Code:


		
			
native SettingType:ConfigSettingType(Handle:Setting);

Returns the type of a Setting object.

PHP Code:


		
			
native bool:ConfigSettingIsGroup(Handle:Setting);
native bool:ConfigSettingIsArray(Handle:Setting);
native bool:ConfigSettingIsList(Handle:Setting);

Returns whether Setting is a group, array and list respectively.

PHP Code:


		
			
native bool:ConfigSettingIsAggregate(Handle:Setting);
native bool:ConfigSettingIsScalar(Handle:Setting);
native bool:ConfigSettingIsNumber(Handle:Setting);

Returns whether Setting is aggregate (group, array or list), scalar (int/cell, float, bool or string) and a number (int/cell or float) respectively.

PHP Code:


		
			
native ConfigSettingSourceLine(Handle:Setting);

Returns the line in the configuration file where Setting has been parsed from.

Sourcecode repository

http://player.to/gitweb/index.cgi?p=sm-ext-config.git

Backup:
http://forums.alliedmods.net/showpos...5&postcount=34