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 (for a clod file)

The settings class encapsulates the actual values represented by a clodfile instance. Instances can have a prefix, in which case they represent a subset of the content of the clodfile.

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:

Class clodfile

Clod File - Settings representation and re-serialisation

These objects can be queried for values and also have values added, changed, and removed. Where clod gets interesting is that the clodfile instance can also be used to re-serialise the configuration file in a way which hopefully resembles human edits.

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
generated by LDoc 1.4.3 Last updated 1477548769