Class Documentation

Name:Config
Version:1.0
ID:ID_CONFIG
Status:Stable
Category:Files
Include:files/config.h
Date:March 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1997-2001. All rights reserved.
Short:  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:

GetUnlistedField  Adds new entries to 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.

Methods

The Config class implements the following methods:

AddConfigEntry  Adds new entries to Config objects.
DeleteConfigEntry  Deletes single configuration entries.
DeleteConfigSection  Deletes entire sections of configuration data.
ReadConfig  Reads one selected string from a configuration file.
ReadConfigInt  Reads configuration entries in integer format.

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.
Action:GetUnlistedField
Short: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)".

 

Method:AddConfigEntry()
Short:Adds new entries to Config objects.
Arguments:
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.

Result
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.

 

Method:DeleteConfigEntry()
Short:Deletes single configuration entries.
Arguments:
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.

Result
ERR_Okay  Entry deleted successfully.
ERR_Args  Invalid arguments were specified.
ERR_GetField  The Entries field could not be retrieved.

 

Method:DeleteConfigSection()
Short:Deletes entire sections of configuration data.
Arguments:
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.

Result
ERR_Okay  The section was deleted.
ERR_Args  Invalid arguments were specified.
ERR_GetField  The Entries field could not be retrieved.

 

Method:ReadConfig()
Short:Reads one selected string from a configuration file.
Arguments:
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.

Result
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.

 

Method:ReadConfigInt()
Short:Reads configuration entries in integer format.
Arguments:
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.

Result
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:

TypeDescription
STRING Section  The name of the section
STRING ItemThe name of the item.
STRING DataThe 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:

  1. Group = Sun, Light
  2. Location = athene:
  3. 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:

  1. !Group = Sun, Light
  2. !Location = athene:
  3. !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:

  1. Program, Application, Game
  2. 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:

  1. !Program, Application, Game
  2. !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.