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.
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.
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 | |
| add | Adds a key/value pairs to the INI file. |
| addSection | Adds an empty section to the configuration file. |
| clearMain | Clears the main section. |
| get | Retreives the value associated with a key. |
| getCategory | Retreives keys and values given under a certain category. |
| getCategoryKeys | Get the keys filed under a given category. |
| getDictionary | Retreives keys and values given under a certain category. |
| getKeys | Retreives the value associated with a key. |
| getMultiple | Retreives the value associated with a key. |
| getOne | Retreives the value associated with a key. |
| getSections | Enumerates the sections that are declared in the file managed by this object. |
| read | Read the ini file. |
| remove | Remove a key from the configuration file.. |
| removeCategory | Remove a whole category from the configuration file.. |
| removeSection | Removes a whole section from the configuration file. |
| set | Sets the value of a certain key key. |
| write | Write the INI file. |
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.
Adds an empty section to the configuration file.
ConfParser.addSection( section )
| section | The name of the section to be added. |
| Return | True 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.
Clears the main section.
ConfParser.clearMain()
Removes all the entries from the main section. Of course, the section itself is not removed.
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. |
| Return | The 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.
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. |
| Return | A 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.
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. |
| Return | All 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.
Retreives keys and values given under a certain category.
ConfParser.getDictionary( [section] )
| section | If given, the section from which to extract the dictionary. |
| Return | A 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.
Retreives the value associated with a key.
ConfParser.getKeys( [section] )
| section | An optional section on which to operate. |
| Return | All 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.
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. |
| Return | All 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.
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. |
| Return | The 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.
Enumerates the sections that are declared in the file managed by this object.
ConfParser.getSections()
| Return | All 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 the ini file.
ConfParser.read( [stream] )
| stream | An optional input stream from where to read the file. | ||
| Raise |
|
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 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. |
| Return | True 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.
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.
Removes a whole section from the configuration file.
ConfParser.removeSection( section )
| section | The name of the section to be removed. |
| Return | True 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.
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 the INI file.
ConfParser.write( [stream] )
| stream | An optional output stream on which to write the configuration file. | ||
| Raise |
|
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.