Configuration Language Organised (by) Dots

Contents

• Functions
• Class settings
• Class clodfile

Modules

• clod

Topics

• README

Module clod

Clod - Configuration Language Organised (by) Dots

Clod is a simple key/value configuration language (where the keys form a heirarchy based on dotted names) whose implementation aims to provide a way to have a program alter a configuration file in a way identical to how a human might have done so.

This then allows configuration files to be kept in revision control and have the diffs make sense.

Functions

parse (conf, confname, migrate_lists)

Parse clod configuration file Parsing a clod file constructs a clodfile instance which represents the content provided.

Class settings

settings:__index (subkey)	Read configuration settings out of a clodfile
settings:__newindex (subkey, value)	Set / Change / Unset an entry in a clodfile This function sets, changes or removes an entry from a clodfile.

Class clodfile

clodfile:serialise ()	Serialise a clodfile into a string In the reverse of clod.parse this method re-serialises a clodfile into a string which represents the input clod source with the various changes made to it.
methods:each ([prefix])	Iterate the clodfile key/value pairs Use the :each method to iterate a clodfile.
clodfile:get_list (prefix)	Retrieve a list of values in a prefix Since clod can store lists, this function can be used to retrieve a named list.
clodfile:set_list (prefix, list)	Set a list of values into a clodfile instance.
clodfile:locate (key)	Get the location of a given setting Find where a given key is defined in the clod source.
clodfile.settings	The settings in this clodfile instance.

Functions

parse (conf, confname, migrate_lists)

Parse clod configuration file

Parsing a clod file constructs a clodfile instance which represents the content provided. All the arguments to this function only have use during the parse phase. If migrate_lists is used then any real table values encountered during the parse will be converted into clod list assignments. Otherwise an error will be raised.

Parameters:

• conf string The configuration file content
• confname string The name of the configuration file
• migrate_lists boolean Whether to migrate list format during parse.

Returns:

1. clodfile or nil
2. string Error message if failed to parse provided source.

Class settings

settings:__index (subkey)

Read configuration settings out of a clodfile If the given key is a prefix of other keys then a new clodfile instance is returned which works with that subset of the keys in the clodfile indexed.

Parameters:

• subkey string The (sub)key to retrieve.

Returns:

string-or-number-or-boolean The value of that key (or nil if not found)

settings:__newindex (subkey, value)

Set / Change / Unset an entry in a clodfile

This function sets, changes or removes an entry from a clodfile. in doing this, the clodfile attempts to make edits which a human might match. It attempts to place new values near similarly named old values and when removing values it tries to clean up whitespace etc appropriately.

Parameters:

• subkey string The (sub)key to set to the given value
• value string-or-number-or-boolean The value to set

Class clodfile

clodfile:serialise ()

Serialise a clodfile into a string

In the reverse of clod.parse this method re-serialises a clodfile into a string which represents the input clod source with the various changes made to it. In an ideal world, the output of serialising an unmodified clodfile should be byte-for-byte the same as the input source.

Returns:

string The serialised clodfile

methods:each ([prefix])

Iterate the clodfile key/value pairs

Use the :each method to iterate a clodfile. The usage form is:

 for key, value in clodfile:each(pfx) do
    -- Do something with key and value
 end

Parameters:

• prefix string The optional prefix to restrict iteration to. (optional)

Returns:

1. function The iterator function
2. state The iterator function’s state
3. nil The nil context needed to start iteration

clodfile:get_list (prefix)

Retrieve a list of values in a prefix

Since clod can store lists, this function can be used to retrieve a named list. The values are returned in the order in which they are set into the list by the source which was parsed to create the clodfile instance.

Parameters:

• prefix string The prefix (name) of the key to retrieve.

Returns:

table The ordered set of values (ordered by input file ordering)

clodfile:set_list (prefix, list)

Set a list of values into a clodfile instance.

This is a helper method for applications which manipulate lists of settings using clod. Writing a list this way will correctly add, change, and remove entries as needed. Note, that reordering a list will result in slightly odd deltas when reserialised.

Parameters:

• prefix string The key prefix for the list
• list table The list of values to set.

clodfile:locate (key)

Get the location of a given setting

Find where a given key is defined in the clod source. Note that if you have added a new key, or removed an old key, since loading then you may not be able to retrieve data for those entries.

Also, note that this function will always return the original line number of an entry, which is not necessarily where the entry would be in a new serialisation if changes have been made.

Parameters:

• key string The name of the key to locate

Returns:

1. number-or-false The line number that key is defined on, or nil.
2. string The reason for the nil return

clodfile.settings

The settings in this clodfile instance.

• settings