Class Documentation
Config |
1.0 |
ID_CONFIG |
Stable |
Data |
data/config.h |
January 2004 |
Rocklyte Systems |
Rocklyte Systems (c) 1997-2004. All rights reserved. |
Manages the reading and writing of configuration files. |
Description
The Config class is used by programs that need to read text based
data in a pre-arranged format. The advantage of text based files for data
manipulation is that you can edit the data in a standard text editor, then
easily read the information back in for processing. Config files are very
useful for setting up preference systems for your programs, reading startup
details, or for loading user data. The following segment of a config file
is taken from the "system:config/classes.cfg" file:
[Action]
ClassID = 5800
Location = classes:commands/action
[Animation]
ClassID = 1000
Location = classes:gui/animation
[Arrow]
ClassID = 3200
Location = classes:gui/arrow
Notice the text enclosed in square brackets, such as [Action]. These are
referred to as "Sections", which are responsible for holding groups
of Items. An "Item" is defined as a variable that contains string or
integer information. In the above example, items are defined by the ClassID
and Location identifers.
So how do you read a config file? The following source code illustrates
how to open the classes.cfg file and read an item from it:
struct mtReadConfig read;
OBJECTPTR config;
if (CreateObject(ID_CONFIG, NULL, &config, NULL,
FID_Location|TSTRING, "system:config/classes.cfg",
TAGEND) IS ERR_Okay) {
read.Section = "Action";
read.Item = "Location";
Action(MT_ReadConfig, config, &read);
DPrintF("Program:","The Action class is located at %s.", read.Data);
acFree(config);
}
You can also search through Config files using your own routines. The
following example illustrates:
struct ConfigEntry *entries;
LONG amtentries, i;
if (GetFields(Config, FID_AmtEntries|TLONG, &amtentries,
FID_Entries|TPTR, &entries) IS ERR_Okay) {
for (i=0; i < amtentries; i++) {
DPrintF("Demo:","Section: %s, Item: %s, Data: %s", entries[i].Section,
entries[i].Item, entries[i].Data);
}
}
Actions
The Config class supports the following actions:
Clear | Clears all configuration data. |
GetUnlistedField | Retrieves data from a config object. |
SaveToObject | Saves configuration data in text format. |
SetUnlistedField | Allows new entries to be added to a config object via the unlisted field mechanism. |
Sort | Sorts config sections into alphabetical order. |
Methods
The Config class implements the following methods:
Structure
The Config object consists of the following public fields:
AmtEntries | Reflects the total number of entries loaded into a Config object. |
Entries | Holds the data for Config objects. |
ItemFilter | Set this field to enable item filtering. |
Location | Set this field to the location of the configuration text file. |
SectionFilter | Set this field to enable section filtering. |
TotalSections | Tells you the total amount of sections in an initalised Config object. |
GetUnlistedField |
Retrieves data from a config object. |
The unlisted field mechanism is used to retrieve items and data from
specific indexes within config objects. Retrieval can be acheived in a
variety of ways. The simplest method is to refer to the item name when
retrieving data, for instance "myitem". To pull an item from a specific
section, use the format "myitem(section)", where the section is a number
referring to a section index that you want to retrieve.
You can directly refer to any item in the config object using indexes, if
you wish to treat the object as a one-dimensional array. To do this, use
the "index(value)" string format, where value refers to the index that you
wish to lookup. If you would like to retrieve the name of the item rather
than the pull the data from an index, use the string format
"item(value)".
|
|
SetUnlistedField |
Allows new entries to be added to a config object via the unlisted field mechanism. |
The unlisted field mechanism can be used to add new entries to a config
object. The field data will be added under the "Variables" section
with an item name identified by the Field parameter and a data value determined
by the Value parameter. If you need to determine the section under which
the item is added (something other than "Variables"), you can
combine the section and item names into the Field parameter by using a
dot character. For example, "Internet.IPAddress".
|
|
DeleteConfigEntry() |
Deletes single configuration entries. |
LONG Index | The number of the entry that you want to delete. |
|
This method deletes single entries from Config objects. You need to know
the index number of the entry that you want to delete before calling this
function. If you don't know the index number, you can determine it by
searching the array referred to by the Entries
field.
ERR_Okay | Entry deleted successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_GetField | The Entries field could not be retrieved. |
|
|
DeleteConfigSection() |
Deletes entire sections of configuration data. |
STRING Section | The name of the section that you want to delete. |
|
This method is used to delete entire sections of information from Config
objects. Simply specify the name of the section that you want to delete and
it will be removed.
ERR_Okay | The section was deleted. |
ERR_Args | Invalid arguments were specified. |
ERR_GetField | The Entries field could not be retrieved. |
|
|
GetConfigSectionFromIndex() |
GetSectionFromIndex |
Converts an index number into its matching section string. |
LONG Index | The section index that you want to identify. |
STRING Result | Points to the section string that matches the index number. |
|
Use the GetConfigSectionFromIndex method when you know the index number of
a section and wish to learn its name. You only need to supply this method
with the Index number and it will return a reference to the correct section
string in the Result parameter.
ERR_Okay | The section was identified successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_OutOfRange | The index number is out of range of the available sections. |
ERR_NoData | There is no data loaded into the config object. |
|
|
MergeConfig() |
Merges two config objects together. |
OBJECTID Config | The ID of the config object to be merged. |
|
The MergeConfig method is used to merge configuration data from one
config object into the object that this method is called on. You need to
provide the unique object id of the config object providing the source data.
When performing the merge, existing data will be overwritten by the source
in cases where there is a duplication of section and item lines.
ERR_Okay | The merge was successful. |
ERR_Args | Invalid arguments were specified. |
ERR_AccessObject | The source configuration object could not be accessed. |
|
|
MergeConfigFile() |
MergeFile |
Merges a foreign configuration file into existing configuration data. |
STRING Location | The location of the configuration file that you want to merge. |
|
The MergeConfigFile method is used to pull configuration data from
a file and merge it into your config object. You need to provide the
location of the configuration file only. When performing the merge, existing
data will be overwritten by the source file in cases where there is a
duplication of section and item lines.
ERR_Okay | The merge was successful. |
ERR_Args | Invalid arguments were specified. |
ERR_File | Failed to load the source file. |
|
|
ReadConfig() |
Reads one selected string from a configuration file. |
STRING Section | A string specifying the section that you want to look at. |
STRING Item | The specific item that contains the string you want to retrieve. |
STRING Data | The result string will be stored in this parameter on returning. |
|
This function allows you to retrieve the data of a specific item from
a config object. All you need to specify is the Section that you are
interested in and the Item that contains the data to be retrieved.
If the entry is found then the Data parameter is updated with a direct
string pointer to the information. This pointer remains valid only for as
long as you have exclusive access to the config object. The pointer can
also be invalidated if your add more information to the config object. For
this reason you may need to consider copying the Data string if you wish to
use it extensively.
If the Section parameter is set to NULL then the scan routine will treat
the config data as a single large section. If the Item parameter is set to
NULL then the first item in the requested section is returned. If the
both parameters are NULL then the first entry in the configuration data
will be returned.
ERR_Okay | Data read successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_Search | The requested configuration entry does not exist. |
ERR_GetField | The Entries field could not be retrieved. |
|
|
ReadConfigInt() |
Reads configuration entries in integer format. |
STRING Section | The name of the section that the integer will be retrieved from. |
STRING Item | The specific item that contains the integer you want to retrieve. |
LONG Integer | This result argument will be set to the integer value read from the configuration data. |
|
This function is almost identical to ReadConfig(), but it will return a
converted integer rather than a string. If the string cannot be converted
to an integer, a fail code will be returned and the Integer argument set
to zero.
ERR_Okay | The integer was read successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_Failed | The requested configuration entry could not be read. |
|
|
SetConfig() |
Sets items in existing config sections (aborts if the section doesn't already exist). |
STRING Section | The name of the section. |
STRING Item | The name of the item. |
STRING Data | The data that will be added to the given section/item. |
|
This method is identical to WriteConfig except it will abort if the name
of the referred section does not exist in the config object. The error code
ERR_Search is returned if this is the case. Please refer to WriteConfig
for further information on the behaviour of this function.
ERR_Okay | The information was successfully entered to the Config object. |
ERR_Args | Invalid arguments were specified. |
ERR_Search | The referred section does not exist. |
ERR_AllocMemory | The additional memory required for the new entry could not be allocated. |
ERR_GetField | The Entries field could not be retrieved. |
|
|
WriteConfig() |
Adds new entries to config objects. |
STRING Section | The name of the section. |
STRING Item | The name of the item. |
STRING Data | The data that will be added to the given section/item. |
|
If you need to add new information to a Config object, you can do so by
making a call to this method. You are required to specify the Section name,
Item name, and the actual data to be placed in the entry. If the Section and
Item arguments match an existing entry in the Config object, the data of that
entry will be replaced with the new Data that you have supplied.
The Section string may refer to an index if you use a # character, followed
by the index number that you are interested in writing.
ERR_Okay | The information was successfully entered to the Config object. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | The additional memory required for the new entry could not be allocated. |
ERR_GetField | The Entries field could not be retrieved. |
|
|
Field: | AmtEntries |
Short: | Reflects the total number of entries loaded into a Config object. |
Type: | LONG |
Status: | Read |
This field reflects the total number of entries that are loaded into a
Config object. It is readable only after initialisation.
|
|
Field: | Entries |
Short: | Holds the data for Config objects. |
Type: | struct ConfigEntry * |
Status: | Get |
This field points to an array of configuration entries. Each entry holds a
string of data for every item and array that is found in the file during
the initialisation process. You can search the list directly as an
alternative to using the ReadConfig() method.
The ConfigEntry structure is arranged as follows:
STRING Section | The name of the section |
STRING Item | The name of the item. |
STRING Data | The actual data of the configuration entry. |
This field is not writeable, but you can add new configuration entries with
the WriteConfig() method.
|
|
Field: | ItemFilter |
Short: | Set this field to enable item filtering. |
Type: | STRING |
Status: | Get/Set |
When dealing with large configuration files, filtering out unrelated data
can be a very useful exercise. By setting the ItemFilter field, you can
filter out entire sections by setting criteria for each configuration
entry.
Item filters are created in the following format:
[Item] = [Data1], [Data2], ...
Here are some examples:
- Group = Sun, Light
- Location = athene:
- Name = Rocklyte Systems
You can also 'reverse' the filter so that only the items matching your
specifications are filtered out. To do this, use the exclamation character, as
in the following examples:
- !Group = Sun, Light
- !Location = athene:
- !Name = Rocklyte Systems
If you want to create a filter based on section names, refer to the
SectionFilter field.
|
|
Field: | Location |
Synonyms: | Src |
Short: | Set this field to the location of the configuration text file. |
Type: | STRING |
Status: | Get/Set |
To load a configuration file, you will need to set the Location field
so that the config object knows where to load the file from.
You can also find out where a config object got its information from by
reading this field.
|
|
Field: | SectionFilter |
Short: | Set this field to enable section filtering. |
Type: | STRING |
Status: | Get/Set |
When dealing with large configuration files, filtering out unrelated data
can be a very useful exercise. By setting the SectionFilter field, you can
filter out entire sections if they don't match your criteria.
Section filters are created in the following format:
[Section1], [Section2], [Section3], ...
Here are some examples:
- Program, Application, Game
- Apple, Banana
You can also reverse the filter so that only the sections matching your
criteria are filtered out. To do this, use the exclamation character, as
in the following examples:
- !Program, Application, Game
- !Apple, Banana
If you need to create a filter based on item names, refer to the
ItemFilter field.
|
|
Field: | TotalSections |
Short: | Tells you the total amount of sections in an initalised Config object. |
Type: | LONG |
Status: | Get |
If you need to know the total number of sections (item groups) in a Config
object, read this field.
|
|