Initial documentation for clod

1 files changed, 119 insertions, 1 deletions

diff --git a/lib/clod.lua b/lib/clod.lua
index 952796c..2416a80 100644
--- a/lib/clod.lua
+++ b/lib/clod.lua
@@ -5,6 +5,33 @@
 -- Copyright 2012 Daniel Silverstone <dsilvers@digital-scurf.org>
 --
 
+---
+-- 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.
+--
+-- @module clod
+
+---
+-- 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.
+--
+-- @function parse
+-- @tparam string conf The configuration file content
+-- @tparam string confname The name of the configuration file
+-- @tparam boolean migrate_lists Whether to migrate list format during parse.
+-- @treturn clodfile or nil
+-- @treturn string Error message if failed to parse provided source.
+
 local type = type
 local getinfo = debug.getinfo
 local pcall = pcall
@@ -35,6 +62,25 @@ local function gen_settings(tab, prefix)
    return ret
 end
 
+---
+-- 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`.
+--
+-- @type settings
+
+---
+-- 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.
+--
+-- @function __index
+-- @tparam string subkey The (sub)key to retrieve.
+-- @treturn string-or-number-or-boolean The value of that key (or nil if not found)
+
 function settings_mt:__index(subkey)
    local meta = metadata[self]
    local confmeta = metadata[meta.conf]
@@ -98,6 +144,18 @@ local function calculate_wild_key(confmeta, prefix)
    return keystr
 end
 
+---
+-- 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.
+--
+-- @function __newindex
+-- @tparam string subkey The (sub)key to set to the given value
+-- @tparam string-or-number-or-boolean value The value to set
+
 function settings_mt:__newindex(subkey, value)
    local meta = metadata[self]
    local confmeta = metadata[meta.conf]
@@ -198,9 +256,29 @@ function settings_mt:__newindex(subkey, value)
    end
 end
 
+
+---
+-- 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.
+--
+-- @type clodfile
+
 -- Methods for clod instances
 local methods = {}
-
+---
+-- 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.
+--
+-- @function serialise
+-- @treturn string The serialised `clodfile`
 function methods:serialise()
    local entries = metadata[self].entries
    local retstr = {}
@@ -234,6 +312,20 @@ function methods:serialise()
    return tconcat(retstr, "\n")
 end
 
+---
+-- 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
+--
+-- @tparam[opt] string prefix The optional prefix to restrict iteration to.
+-- @treturn function The iterator function
+-- @treturn state The iterator function's state
+-- @treturn nil The nil context needed to start iteration
+
 function methods:each(prefix)
    if prefix then
       prefix = "^" .. prefix:gsub("%.", "%%.")
@@ -252,6 +344,16 @@ function methods:each(prefix)
    return iterator, metadata[self], nil
 end
 
+---
+-- 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.
+--
+-- @function get_list
+-- @tparam string prefix The prefix (name) of the key to retrieve.
+-- @treturn table The ordered set of values (ordered by input file ordering)
 function methods:get_list(prefix)
    local ret = {}
    local map = {}
@@ -266,6 +368,17 @@ function methods:get_list(prefix)
    return ret
 end
 
+---
+-- 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.
+--
+-- @function set_list
+-- @tparam string prefix The key prefix for the list
+-- @tparam table list The list of values to set.
 function methods:set_list(prefix, list)
    -- This algorithm isn't perfect, but it'll do in the face of
    -- lazy apps devs who don't look after keys/value pairs themselves
@@ -284,6 +397,11 @@ function methods:set_list(prefix, list)
    end
 end
 
+---
+-- The settings in this `clodfile` instance.
+--
+-- @field settings
+
 -- Metamethods for clod instances
 function clod_mt:__index(key)
    if key == "settings" then