path: root/aconf
diff options
authorKaarle Ritvanen <>2015-04-02 16:34:13 +0300
committerKaarle Ritvanen <>2015-04-03 00:45:53 +0300
commit3baaf91de453d35b095881478be8d88b3fc2b97a (patch)
treedbeeedc851f0d8130907574ef8506904c5c44570 /aconf
parentc7bce46f22ff9c41e3598d42400368d3c733316c (diff)
initial developer documentation
descriptions for all functions and classes used by the openssh module
Diffstat (limited to 'aconf')
7 files changed, 81 insertions, 1 deletions
diff --git a/aconf/model/config.ld b/aconf/model/config.ld
new file mode 100644
index 0000000..54c9473
--- /dev/null
+++ b/aconf/model/config.ld
@@ -0,0 +1,6 @@
+Copyright (c) 2012-2015 Kaarle Ritvanen
+See LICENSE file for license details
+new_type('klass', 'Classes', false, 'Constructor parameters')
diff --git a/aconf/model/field.lua b/aconf/model/field.lua
index 6e4607f..1b44931 100644
--- a/aconf/model/field.lua
+++ b/aconf/model/field.lua
@@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local M = {}
local err = require('aconf.error')
@@ -56,6 +57,39 @@ function M.conv_filter(filter)
+--- base class for fields. The constructor accepts a table argument
+-- containing field parameters as key&ndash;value pairs. The parameters
+-- listed below are valid for all subclasses. Subclasses may define
+-- additional parameters.
+-- @klass Field
+-- @tparam ?string addr back-end address for the field. This can be an
+-- absolute address or relative to the parent's address. The top-level
+-- component of a back-end address specifies the back-end. The
+-- interpretation of the remaining components is specific to the
+-- back-end. If not specified, the address is formed by appending the
+-- field's name to the address of the parent.
+-- @tparam ?|nil|string|{[string]=string,...} be_mode controls how the
+-- Augeas back-end will map addresses to Augeas paths. By default,
+-- each component of a back-end address is directly mapped to an
+-- Augeas path component. This parameter is an exception table
+-- applicable to the subtree defined by the field's address. Each key
+-- is a relative address pattern, and the corresponding value is a
+-- directive applied to matching address components. The *enumerate*
+-- directive indicates there can be several Augeas nodes matching the
+-- path and the next component is to be interpreted as an index for
+-- such nodes. The *parent-value* directive is applicable only to
+-- primitive fields and instructs the back-end not to append the last
+-- address component at all, causing the parent node's value to be
+-- accessed. If the *be\_mode* parameter is defined as a string, it is
+-- assumed to be a directive applicable to the field's own address.
+-- @tparam nil|{any|{any,string},...} choice array of allowed
+-- values. Each value may be a primitive value or a tuple specifying
+-- the value used by the data model and a user-friendly value.
+-- @tparam ?any default default value for the field
+-- @tparam ?boolean required field must be assigned a value if set,
+-- defaults to false
+-- @tparam ?string ui_name user-friendly name for the field.
M.Field = class(M.Member)
function M.Field:init(params)
@@ -263,6 +297,8 @@ function Primitive:validate(context, value)
+--- string field, inherits @{Field}.
+-- @klass String
M.String = class(Primitive)
function M.String:init(params)
@@ -317,6 +353,8 @@ function M.Integer:validate(context, value)
+--- boolean field, inherits @{Field}.
+-- @klass Boolean
M.Boolean = class(Primitive)
function M.Boolean:init(params)
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 437cb93..667da2f 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local M = {}
M.error = require('aconf.error')
@@ -241,6 +242,13 @@ function M.Collection:load(context, options)
+--- list field, inherits @{Field}. A list is an ordered collection of
+--- members. The path of a list member is that of the list augmented
+--- by the index of the member.
+-- @klass List
+-- @tparam Field|Model type subclass of @{Field}, instance of such, or
+-- subclass of Model specifying the type of the members.
+-- @tparam ?string ui_member user-friendly noun for a list member.
M.List = class(M.Collection)
function M.List:init(params) super(self, M.List):init(params, node.List) end
diff --git a/aconf/model/model.lua b/aconf/model/model.lua
index a1780c9..3ffd4d3 100644
--- a/aconf/model/model.lua
+++ b/aconf/model/model.lua
@@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local M = {}
local raise = require('aconf.error').raise
@@ -66,6 +67,13 @@ function M.Action:meta(context)
+--- create a new model. The model's fields can be defined after its
+-- creation by assigning it key&ndash;value pairs. The key will be the
+-- name of the field and the value will determine its type. The value
+-- shall be a subclass of @{Field}, an instance of such, or a subclass
+-- of Model.
+-- @tparam ?Model base base model inherited by the new model
+-- @treturn Model new model
if not base then base = M.Model end
diff --git a/aconf/model/permission.lua b/aconf/model/permission.lua
index f7f5be1..8ddd144 100644
--- a/aconf/model/permission.lua
+++ b/aconf/model/permission.lua
@@ -1,8 +1,9 @@
-Copyright (c) 2012-2014 Kaarle Ritvanen
+Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local M = {}
local node = require('aconf.model.node')
@@ -15,6 +16,9 @@ function M.define(path, ...)
+--- create default permissions (read, create, modify, delete) for a given path.
+-- @function permission.defaults
+-- @tparam string path path to create the permissions for
function M.defaults(path)
M.define(path, 'read', 'create', 'modify', 'delete')
for _, action in ipairs(node.meta(start_txn():fetch(path)).actions or {}) do
diff --git a/aconf/model/root.lua b/aconf/model/root.lua
index 3f95b0e..eef48ec 100644
--- a/aconf/model/root.lua
+++ b/aconf/model/root.lua
@@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local M = {}
local model = require('aconf.model.model')
@@ -60,6 +61,13 @@ M.topology = setmetatable(
+--- inject a new field to the root model.
+-- @tparam string name name of the field
+-- @tparam Field|Model field type of the field, specified by a
+-- subclass of @{Field} or an instance of such. Can also be specified
+-- by a subclass of Model.
+-- @tparam ?{[string]=any,...} params field parameters. Applicable
+-- when field type is specified by a class (not an instance).
function M.register(name, field, params)
if not params then params = {} end
params.create = true
diff --git a/aconf/model/service.lua b/aconf/model/service.lua
index 2d129fa..9ce3685 100644
--- a/aconf/model/service.lua
+++ b/aconf/model/service.lua
@@ -3,12 +3,20 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
+--- @module aconf.model
local fld = require('aconf.model.field')
local new = require('aconf.model.model').new
local super = require('aconf.object').super
local pth = require('aconf.path')
local store = require('aconf.persistence')
+--- create a model corresponding to an OpenRC service.
+-- @function service
+-- @tparam string name name of the service
+-- @treturn Model new model, which has two pre-defined boolean fields,
+-- *enabled* and *status*, for controlling the service's lifecycle and
+-- inspecting its current status.
return function(name)
local res = new()