2.3.1Class ConfParser

Interface to configuration files.

Class ConfParser( [filename],[encoding] )
filename The name of the ini file to be parsed, if it exists.
encoding An optional non default encoding which is used for that file.

The constructor of this class allows to set up a filename for the configuration file that is going to be read and/or written. If the name is not given, ConfParser.read and ConfParser.write methods will require a valid Falcon Stream, otherwise, if the stream is not provided, the given file will be opened or written as needed.

Adding, setting or removing keys

The most direct way to add a new key in an ini configuration file is to use the ConfParser.add method.

If the key had not any previous value, a new key is added. If a specified section was not previously present it is added.

If one or more entries with the same key was already present, the entry will be physically placed as the last one, and if queried at a later moment, the value will be returned as the last value of the value arrays associated with the given key.

The value parameter may also be an array of strings, in which case all the values contained in the array will be added, one after another as specified for the single value case. If the caller wants to be sure that only the values in the given value or value array are set, it should call the ConfParser.remove method before calling ConfParser.add.

To set a single value, eventually getting rid of other previously existing values, use the set method: ConfParser.set, which sets a key/value pair in the main section, or if section parameter is given and not nil, in the specified section. Using this method, any previous value or value set associated with the given key is removed. If the key had not any previous value, a new key is added. If a specified section was not previously present, it is added. If the given key was already present in a parsed configuration file, it's position and the comments that were eventually associated with the key are left unchanged.

To remove completely a key, use the ConfParser.remove method. To remove completely a section, use the removeSection( section ) method. This method can't be used to remove the main section; in fact, even if empty, that section always exists. To clear every key in that, use the clearMain() method.

Categorized keys

Categories are separated from the keys by dots "."; a complete categorized key may contain any amount of dots, or in other words, the categories can have an arbitrary depth.

The getCategoryKeys method returns a list of all the keys belonging to a certain category. Categories are separated from the keys by dots "."; a complete categorized key may contain any amount of dots, or in other words, the categories can have an arbitrary depth.

The category (first) parameter of this method may indicate the first level category only, or it can be arbitrarily deep. Only the keys in deeper categories will be returned.

For example; if the configuration file contains the following entries:


   Key.cat1 = 1
   Key.cat1.k1 = 101
   Key.cat1.k2 = 102
   Key.cat1.k3 = 103
   Key.cat1.subcat1.k1 = 105
   Key.cat1.subcat1.k2 = 106

if the category parameter is set to "Key", all the entries will be returned. If it's set to "cat1", the first entry won't be returned, as it's considered a key cat1 in category Key. If category is set to "key.cat1.subcat1", the last two entries will be returned.

The strings in the returned array represent the complete key name, including the complete categorization. In this way it is directly possible to retrieve the value of a given key, or to alter their values, by simply iterating on the returned array, like in the following example:


   category = "Key.cat1.subcat1"
   trimming = [len(category)+1:]

   keys = parser.getCategoryKeys( category )
   printl( "Keys in category ", category, ": " )
   for key in keys
      printl( key[ trimming ], "=", parser.get( key ) )
   end

The result will be:


   Keys in category Key.cat1.subcat1:
   k1=105
   k2=106

If the category cannot be found, or if it doesn't contain any entry, or if a section parameter is provided but the given section cannot be found, this method returns an empty array. It is necessary to ascertain that the requested values are present (of if not, that their missing actually means that the category is "empty") by other means.

Other than just enumerating categorized keys, that can then be read with the ordinary get() or getOne() methods, a whole category tree can be imported with the method getCategory().

For example, consider the same configuration structure we have used before. If the category parameter of getCategory() is set to "Key", all the entries will be returned. If it's set to "cat1", the first entry won't be returned, as it's consider a key cat1 in category Key. If category is set to "key.cat1.subcat1", the last two entries will be returned.

The strings returned in the dictionary keys are the complete key, including the category part. It is possible to obtain a dictionary where the keys are already stripped of their category part by adding an asterisk at the end of the first parameter.

For example:


   category = "Key.cat1"
   valueDict = parser.getCategory( category+"*" )

   printl( "Keys in category ", category, ": " )
   for key, value in valueDict
      printl( key, "=", value )
   end

The result will be:


   Keys in category Key.cat1:
   k1=101
   k2=102
   k3=103
   subcat1.k1=105
   subcat1.k2=106

If a key has multiple values, it's value element will be set to an array containing all the values.

Methods
addAdds a key/value pairs to the INI file.
addSectionAdds an empty section to the configuration file.
clearMainClears the main section.
getRetreives the value associated with a key.
getCategoryRetreives keys and values given under a certain category.
getCategoryKeysGet the keys filed under a given category.
getDictionaryRetreives keys and values given under a certain category.
getKeysRetreives the value associated with a key.
getMultipleRetreives the value associated with a key.
getOneRetreives the value associated with a key.
getSectionsEnumerates the sections that are declared in the file managed by this object.
readRead the ini file.
removeRemove a key from the configuration file..
removeCategoryRemove a whole category from the configuration file..
removeSectionRemoves a whole section from the configuration file.
setSets the value of a certain key key.
writeWrite the INI file.

Methods

add

Adds a key/value pairs to the INI file.

ConfParser.add( key, value, [section] )
key The key to which add the given value.
value The value, or value array, to be added.
section If provided, the section where to add the entry

This function adds a key/value pair to the main section, or if section parameter is given and not nil, to the specified section.

If the key is already present, a multiple value is set.

addSection

Adds an empty section to the configuration file.

ConfParser.addSection( section )
section The name of the section to be added.
ReturnTrue if the key is removed, false if the given key is not found.

Adds an empty section to the configuration file, if it was not already present. If a section with the given name is present, nothing is done.

clearMain

Clears the main section.

ConfParser.clearMain()

Removes all the entries from the main section. Of course, the section itself is not removed.

get

Retreives the value associated with a key.

ConfParser.get( key, [section] )
key The key of which the value is to be read.
section If provided, the section where the key is found.
ReturnThe value (or values) of associated to the key, or nil if not found.

The method retrieves the value associated with a given key. If section parameter is not provided, or if it's nil, the key is searched in the main section, else it is searched in the given section.

If the section does not exist, or if the key is not present in the given section, the method returns nil. If the key exist but has no value associated with it, an empty string is returned. If there is only one instance of the key, a single string containing the value is returned. If multiple entries for the given key are found, all the values are returned as strings in an array. The caller should verify the if the returned value is a string or an array using typeOf() function. Alternatively, it is possible to use ConfParser.getOne to be sure to retrieve only strings.

Categorized keys can be retrieved with this method by providing their full name.

getCategory

Retreives keys and values given under a certain category.

ConfParser.getCategory( category, [section] )
category The category of which the values are required
section If provided, the section where the category is defined.
ReturnA dictionary containing a pair of key-values in the given category.

This method returns a dictionary of key-value pairs containing all the keys and values in a certain category.

See the "Categorized keys" section in ConfParser.

getCategoryKeys

Get the keys filed under a given category.

ConfParser.getCategoryKeys( category, [section] )
category The category of which the key list is required
section If provided, the section where the category is defined.
ReturnAll the keys listed in the given category.

This method returns a list of all the keys belonging to a certain category.

See the "Categorized keys" section in ConfParser.

getDictionary

Retreives keys and values given under a certain category.

ConfParser.getDictionary( [section] )
section If given, the section from which to extract the dictionary.
ReturnA dictionary containing a pair of key-values in the given section.

This method retrieves all the pairs of key and values in the main section, or if a non-nil section parameter is provided, from the given section. If the requested section cannot be found, or if it doesn't contain any entry, an empty dictionary is returned. If a key has multiple values, its element is set to an array containing all the values.

getKeys

Retreives the value associated with a key.

ConfParser.getKeys( [section] )
section An optional section on which to operate.
ReturnAll the keys listed in the given section, or in the main part.

This method returns an array of strings containing all the keys in the main section, or if a section parameter is given and not nil, it returns all the keys in the given section.

If the given section exists but it doesn't contain any key, an empty array is returned. If the section doesn't exist, the method returns nil.

getMultiple

Retreives the value associated with a key.

ConfParser.getMultiple( key, [section] )
key The key of which the value is to be read.
section If provided, the section where the key is found.
ReturnAll the values of associated to the key, or nil if not found.

This method is equivalent to ConfParser.get method, except for the fact that an array of values is always returned even if only one key is found. If there is no entry in the configuration file coresponding to the given key, nil is returned.

getOne

Retreives the value associated with a key.

ConfParser.getOne( key, [section] )
key The key of which the value is to be read.
section If provided, the section where the key is found.
ReturnThe value (or values) of associated to the key, or nil if not found.

This method is equivalent to the ConfParser.get method, except for the fact that if more than one value has been given for the determined key in the configuration file, only the last one among them is returned.

getSections

Enumerates the sections that are declared in the file managed by this object.

ConfParser.getSections()
ReturnAll the values of associated to the key, or nil if not found.

If the object doesn't declare any section, the method returns an empty array.

read

Read the ini file.

ConfParser.read( [stream] )
stream An optional input stream from where to read the file.
Raise
IoError on read error.

Parses a configuration file and prepares the object data that may be retrieved with other methods. The read method may be provided with an opened and readable Falcon stream. If not, the file name provided to the ConfParser constructor will be opened and read. In case the name has not been given in the constructor, the method raises an error. The method may also raise ParseError, IoError or ParamError, with the "message" field set to a relevant explanation.

remove

Remove a key from the configuration file..

ConfParser.remove( key, [section] )
key The key to be removed.
section If provided, the section where to remove the entry.
ReturnTrue if the key is removed, false if the given key is not found.

Remove all the instances of a given key from the main section, or if section parameter is given and not nil, from the specified section.

The method returns true if the section (when provided) and keys were found, and false if nothing has actually been deleted.

removeCategory

Remove a whole category from the configuration file..

ConfParser.removeCategory( category, [section] )
category The category to be removed.
section If provided, the section where to remove the entry.

This method removes all the entries that would be returned by getCategory if provided with the same parameters. The function silently returns doing nothing if given category, or given section, cannot be found.

removeSection

Removes a whole section from the configuration file.

ConfParser.removeSection( section )
section The name of the section to be removed.
ReturnTrue if the section is removed, false if the given section is not found.

This method removes the given section from the configuration file. All the keys contained in the section, comments below the section declaration and the section declaration itself are removed. The function returns true if the given section can be found, and false otherwise.

set

Sets the value of a certain key key.

ConfParser.set( key, value, [section] )
key The key to which add the given value.
value The value, or value array, to be added.
section If provided, the section where to add the entry

Sets a key/value pair in the main section, or if section parameter is given and not nil, in the specified section.

write

Write the INI file.

ConfParser.write( [stream] )
stream An optional output stream on which to write the configuration file.
Raise
IoError on write error.

Writes the content of a modified or entirely generated configuration file on the given stream, that must be a valid Falcon stream opened for output. If a stream is not given, then the file name provided to the ConfParser constructor is opened for writing. In case the name has not been given in the constructor, the method raises an error.

Made with http://www.falconpl.org