Parasol Framework Manual

Manages the reading and writing of configuration files.

The Config class is provided for reading text based key-values in a simple structured format. Although basic and lacking support for trees and types, they are reliable, easy to support and use minimal resources.

The following segment of a config file illustrates:

[Action]
ClassID  = 5800
Path = modules:action

[Animation]
ClassID  = 1000
Path = modules:animation

[Arrow]
ClassID  = 3200
Path = modules:arrow

Notice the text enclosed in square brackets, such as [Action]. These are referred to as 'groups', which are responsible for holding groups of key values expressed as strings. In the above example, keys are defined by the ClassID and Path identifiers.

The following source code illustrates how to open the classes.cfg file and read a key from it:

local cfg = obj.new('config', { path='config:classes.cfg' })
local err, str = cfg.mtReadValue('Action', 'Path')
print('The Action class is located at ' .. str)

Please note that internal string comparisons of group and key names are case sensitive by default. Use of camel-case is recommended as the default naming format.

Structure

The Config class consists of the following fields:

Access

Name

Type

Comment

Data APTR Reference to the raw data values.

This field points to a C++ type that contains all key-values for the config object. It is intended to be used only by system code that is included with the standard framework.

Flags CNF Optional flags may be set here.

Name	Description
CNF::AUTO_SAVE	When the configuration object is freed, automatically save the configuration data back to the original file source.
CNF::NEW	On initialisation, do not load any data from the referenced configuration file.
CNF::OPTIONAL_FILES	Files are optional (do not fail if a requested file does not exist).
CNF::STRIP_QUOTES	Removes quotes from key values that are quote-encapsulated.

GroupFilter STRING Set this field to enable group filtering.

When dealing with large configuration files, filtering out unrelated data may be useful. By setting the GroupFilter field, it is possible to filter out entire groups that don't match the criteria.

Group filters are created in CSV format, i.e. GroupA, GroupB, GroupC, ....

The filter can be reversed so that only the groups matching your criteria are filtered out. To do this, prefix the CSV list with the ! character.

To create a filter based on key names, refer to the KeyFilter field.

KeyFilter STRING Set this field to enable key filtering.

When dealing with large configuration files it may be useful to filter out groups of key-values that are not needed. The KeyFilter field allows simple filters to be defined that will perform this task for you. It is recommended that it is set prior to parsing new data for best performance, but can be set or changed at any time to apply a new filter.

Key filters are created in the format [Key] = [Data1], [Data2], .... For example:

Group = Sun, Light
Path = documents:
Name = Parasol

Filters can be inversed by prefixing the key with the ! character.

To create a filter based on group names, refer to the GroupFilter field.

Path STRING Set this field to the location of the source configuration file.

TotalGroups INT Returns the total number of groups in a config object.

TotalKeys INT The total number of key values loaded into the config object.

Actions

The following actions are currently supported:

Clear Clears all configuration data.

DataFeed Data can be added to a Config object through this action.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, INT Size)

Parameter	Description
Object	Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID.
Datatype	The type of data being sent.
Buffer	The data being sent to the target object.
Size	The size of the data in Buffer.

This action will accept configuration data in TEXT format. Any existing data that matches to the new group keys will be overwritten with new values.

Flush Diverts to SaveSettings().

SaveSettings Saves data to the file that the configuration data was loaded from.

ERR acSaveSettings(*Object)

This action will save the configuration data back to its original file source (assuming the Path remains unchanged).

SaveToObject Saves configuration data to an object, using standard config text format.

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

Methods

The following methods are currently supported:

DeleteGroup Deletes entire groups of configuration data.

ERR cfg::DeleteGroup(OBJECTPTR Object, CSTRING Group)

Parameter	Description
Group	The name of the group that will be deleted.

This method will delete an entire group of key-values from a config object if a matching group name is provided.

Error Codes

Okay	The group was deleted or does not exist.
NullArgs	Function call missing argument value(s)

DeleteKey Deletes single key entries.

ERR cfg::DeleteKey(OBJECTPTR Object, CSTRING Group, CSTRING Key)

Parameter	Description
Group	The name of the targeted group.
Key	The name of the targeted key.

This method deletes a single key from the Config object.

Error Codes

Okay	Operation successful.
Search	A search routine in this function failed.
NullArgs	Function call missing argument value(s)

GetGroupFromIndex Converts an index number into its matching group string.

ERR cfg::GetGroupFromIndex(OBJECTPTR Object, INT Index, CSTRING * Group)

Parameter	Description
Index	The group index that you want to identify.
Group	Points to the group string that matches the index number.

Use GetGroupFromIndex() to convert a group index number to its matching name.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
NoData	There is no data loaded into the config object.
OutOfRange	The index number is out of range of the available groups.

Merge Merges two config objects together.

ERR cfg::Merge(OBJECTPTR Object, OBJECTPTR Source)

Parameter	Description
Source	The Config object to be merged.

The Merge() method is used to merge configuration data from one config object provided as a source, into the target object. Existing data in the target will be overwritten by the source in cases where there matching set of group keys.

Error Codes

Okay	Operation successful.
AccessObject	The source configuration object could not be accessed.
NullArgs	Function call missing argument value(s)

MergeFile Merges a configuration file into existing configuration data.

ERR cfg::MergeFile(OBJECTPTR Object, CSTRING Path)

Parameter	Description
Path	The location of the configuration file that you want to merge.

The MergeFile() method is used to pull configuration data from a file and merge it into the target config object. The path to the configuration file is all that is required. Existing data in the target will be overwritten by the source in cases where there matching set of group keys.

Error Codes

Okay	Operation successful.
File	Failed to load the source file.
NullArgs	Function call missing argument value(s)

ReadValue Reads a key-value string.

ERR cfg::ReadValue(OBJECTPTR Object, CSTRING Group, CSTRING Key, CSTRING * Data)

Parameter	Description
Group	The name of a group to examine for a key. If `NULL`, all groups are scanned.
Key	The name of a key to retrieve (case sensitive).
Data	The key value will be stored in this parameter on returning.

This function retrieves key values in their original string format. On success, the resulting string remains valid only for as long as the client has exclusive access to the config object. The pointer can also be invalidated if more information is written to the config object. For this reason, consider copying the result if it will be used extensively.

If the Group parameter is set to NULL, the scan routine will treat all of the config data as a one dimensional array. If the Key parameter is set to NULL then the first key in the requested group is returned. If both parameters are NULL then the first known key value will be returned.

Error Codes

Okay	Operation successful.
Search	The requested configuration entry does not exist.
NullArgs	Function call missing argument value(s)

Set Sets keys in existing config groups (aborts if the group does not exist).

ERR cfg::Set(OBJECTPTR Object, CSTRING Group, CSTRING Key, CSTRING Data)

Parameter	Description
Group	The name of the group. Wildcards are supported.
Key	The name of the key.
Data	The data that will be added to the given group/key.

This method is identical to WriteValue() except it will abort if the name of the referred group does not exist in the config object. The error code ERR::Search is returned if this is the case. Please refer to WriteValue() for further information on the behaviour of this function.

Error Codes

Okay	Operation successful.
Search	The referred group does not exist.
NullArgs	Function call missing argument value(s)

SortByKey Sorts config data using a sequence of sort instructions.

ERR cfg::SortByKey(OBJECTPTR Object, CSTRING Key, INT Descending)

Parameter	Description
Key	The name of the key to sort on.
Descending	Set to true if a descending sort is required.

The SortByKey() method sorts the groups of a config object by key values (the named key value should be present in every group).

Error Codes

Okay	Operation successful.
NoData	No data is available for use.

WriteValue Adds new entries to config objects.

ERR cfg::WriteValue(OBJECTPTR Object, CSTRING Group, CSTRING Key, CSTRING Data)

Parameter	Description
Group	The name of the group.
Key	The name of the key.
Data	The data that will be added to the given group/key.

Use the WriteValue() method to add or update information in a config object. A Group name, Key name, and Data value are required. If the Group and Key arguments match an existing entry in the config object, the data of that entry will be replaced with the new Data value.

The Group string may refer to an index if the hash # character is used to precede a target index number.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
AllocMemory	The additional memory required for the new entry could not be allocated.
NullArgs	Function call missing argument value(s)

Config Class

Structure

Actions

Methods

CNF Type