Class Documentation
Config |
1.0 |
ID_CONFIG |
Stable |
Files |
files/config.h |
March 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 1997-2001. 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);
Action(AC_Free, Config, NULL);
}
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:
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 |
Adds new entries to a Config object. |
If an attempt is made to get an unlisted field from a Config object,
it will search for a value that matches the requested field name from the
config file. Different sections can be referred to by placing the section
number in brackets at the end of the field name. For example, to get an
item named "mydata" in section two, the correct fieldname is "mydata(2)".
|
|
AddConfigEntry() |
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.
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. |
|
|
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. |
|
|
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.
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. |
|
|
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 AddConfigEntry() 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.
|
|