From 1f3c05d453a39ee6b8962d59f804af27ff2fa571 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Tue, 14 Jul 2015 14:19:23 +0100 Subject: Initial documentation for clod --- lib/clod.lua | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 1 deletion(-) 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 -- +--- +-- 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 -- cgit v1.2.1