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.
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. | |||||||||||
| |||||||||||||
| 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. 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 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 Group = Sun, Light Path = documents: Name = Parasol Filters can be inversed by prefixing the key with the 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. | |||||||||||
The following actions are currently supported:
| Name | Comment | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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, LONG Size)
This action will accept configuration data in | ||||||||||||
| 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)
| ||||||||||||
The following methods are currently supported:
| Name | Comment | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| DeleteGroup | Deletes entire groups of configuration data. | ||||||||||||||||
ERR cfg::DeleteGroup(OBJECTPTR Object, CSTRING Group)
This method will delete an entire group of key-values from a config object if a matching group name is provided. Error Codes
| |||||||||||||||||
| DeleteKey | Deletes single key entries. | ||||||||||||||||
ERR cfg::DeleteKey(OBJECTPTR Object, CSTRING Group, CSTRING Key)
This method deletes a single key from the Config object. Error Codes
| |||||||||||||||||
| GetGroupFromIndex | Converts an index number into its matching group string. | ||||||||||||||||
ERR cfg::GetGroupFromIndex(OBJECTPTR Object, LONG Index, CSTRING * Group)
Use GetGroupFromIndex() to convert a group index number to its matching name. Error Codes
| |||||||||||||||||
| Merge | Merges two config objects together. | ||||||||||||||||
ERR cfg::Merge(OBJECTPTR Object, OBJECTPTR Source)
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
| |||||||||||||||||
| MergeFile | Merges a configuration file into existing configuration data. | ||||||||||||||||
ERR cfg::MergeFile(OBJECTPTR Object, CSTRING Path)
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
| |||||||||||||||||
| ReadValue | Reads a key-value string. | ||||||||||||||||
ERR cfg::ReadValue(OBJECTPTR Object, CSTRING Group, CSTRING Key, CSTRING * Data)
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 Error Codes
| |||||||||||||||||
| 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)
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 Error Codes
| |||||||||||||||||
| SortByKey | Sorts config data using a sequence of sort instructions. | ||||||||||||||||
ERR cfg::SortByKey(OBJECTPTR Object, CSTRING Key, LONG Descending)
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
| |||||||||||||||||
| WriteValue | Adds new entries to config objects. | ||||||||||||||||
ERR cfg::WriteValue(OBJECTPTR Object, CSTRING Group, CSTRING Key, CSTRING Data)
Use the WriteValue() method to add or update information in a config object. A The Error Codes
| |||||||||||||||||
Flags for the Config class.
| 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. |
Class Info | |
|---|---|
| ID | ID_CONFIG |
| Category | Data |
| Include | modules/config.h |
| Version | 1 |