summaryrefslogtreecommitdiffstats
path: root/aconf
diff options
context:
space:
mode:
authorKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2015-04-03 10:40:28 +0300
committerKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2015-04-10 18:17:00 +0300
commita92dc45aee3f599926c77294328db38c5b2544eb (patch)
tree0f31580b868245cabe733864f9d99901730c3279 /aconf
parent3baaf91de453d35b095881478be8d88b3fc2b97a (diff)
downloadaconf-a92dc45aee3f599926c77294328db38c5b2544eb.tar.bz2
aconf-a92dc45aee3f599926c77294328db38c5b2544eb.tar.xz
docs: describe functionality used in the dnsmasq modulev0.5.0
Diffstat (limited to 'aconf')
-rw-r--r--aconf/model/field.lua62
-rw-r--r--aconf/model/init.lua18
-rw-r--r--aconf/model/model.lua28
-rw-r--r--aconf/model/net.lua6
-rw-r--r--aconf/model/node.lua24
-rw-r--r--aconf/model/root.lua9
-rw-r--r--aconf/model/service.lua6
-rw-r--r--aconf/model/set.lua13
8 files changed, 128 insertions, 38 deletions
diff --git a/aconf/model/field.lua b/aconf/model/field.lua
index 1b44931..daaa9f4 100644
--- a/aconf/model/field.lua
+++ b/aconf/model/field.lua
@@ -69,27 +69,46 @@ end
-- 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
+-- @param be_mode (optional <i>**string**</i> or
+-- <i>**{[string]=string,...}**</i>) 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.
+-- @param choice (optional <i>**{primitive**</i> or
+-- <i>**{primitive,string},...}**</i>) 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.
+-- @param compute (optional <i><b>function(@{node.TreeNode})</b></i>
+-- or <i>**string**</i>) function for computing the value of the field
+-- when not provided by the back-end. The function gets a reference to
+-- the field's parent as an argument. If defined as a string, a method
+-- with the given name is invoked.
+-- @tparam ?primitive default default value for the field
-- @tparam ?boolean required field must be assigned a value if set,
-- defaults to false
+-- @param store (optional <i><b>function(@{node.TreeNode},
+-- primitive)</b></i> or <i>**string**</i>) if this parameter is
+-- defined, the value of the field is not stored according to the
+-- field's back-end address. Rather, the provided function is invoked
+-- with a reference to the parent and the field value. If defined as a
+-- string, a method with the given name is invoked.
-- @tparam ?string ui_name user-friendly name for the field.
+-- @tparam ?boolean visible the field is visible in the user interface
+-- if set, defaults to true
+-- @tparam ?string widget widget for rendering the field in the user
+-- interface. The default widget for non-leaf objects is *link*, which
+-- is a hyperlink to a detailed view to the object. The *inline*
+-- widget renders a non-leaf object embedded in the parent's view.
M.Field = class(M.Member)
function M.Field:init(params)
@@ -431,6 +450,13 @@ function M.TreeNode:validate_saved(context)
end
+--- model field, inherits @{Field}. The value of this field is a <a
+-- href="#Model_objects">model object</a> conforming to the specified
+-- model. A model field with default parameters is implicitly created
+-- when a model is used in lieu of a @{Field}.
+-- @klass Model
+-- @param model (<i>[&lt;Model&gt;](#new)</i>) model describing the
+-- structure of the model objects
M.Model = class(M.TreeNode)
function M.Model:init(params)
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 667da2f..6c78b8f 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -231,6 +231,13 @@ function M.Collection:auto_ui_name(name)
return super(self, M.Collection):auto_ui_name(name)
end
+--- collection field, inherits @{Field}.
+-- @klass Collection
+-- @param type (<i>@{Field}</i> or <i>[&lt;Model&gt;](#new)</i>)
+-- subclass of @{Field}, instance of such, or
+-- [**&lt;Model&gt;**](#new) specifying the type of the members.
+-- @tparam ?string ui_member user-friendly noun for a member of this
+-- collection
function M.Collection:load(context, options)
if not self.iparams.field then
self.iparams.field = to_field(self.type)
@@ -242,17 +249,16 @@ function M.Collection:load(context, options)
end
---- 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.
+--- list field, inherits @{Collection}. The value of this field is an
+-- instance of @{node.List}.
-- @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
+--- set field, inherits @{Collection}. The value of this field is an
+-- instance of @{node.Set}.
+-- @klass Set
M.Set = class(M.Collection)
function M.Set:init(params)
if not params.widget and isinstance(params.type, M.Reference) then
diff --git a/aconf/model/model.lua b/aconf/model/model.lua
index 3ffd4d3..20e2551 100644
--- a/aconf/model/model.lua
+++ b/aconf/model/model.lua
@@ -67,13 +67,15 @@ function M.Action:meta(context)
end
---- 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
+--- create a new model, representing a data model with a pre-defined
+-- structure. The model's fields can be defined 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 another **&lt;Model&gt;**.
+-- @function new
+-- @param base (optional <i>**&lt;Model&gt;**</i>) base model
+-- inherited by the new model.
+-- @return <i>**&lt;Model&gt;**</i> new model
function M.new(base)
if not base then base = M.Model end
@@ -106,6 +108,9 @@ function M.new(base)
return res
end
+--- Model objects. Each of these represents an actual model
+-- object in the data model, in the context of a specific transaction.
+-- @section Model
M.Model = M.new(node.TreeNode)
function M.Model:init(context)
@@ -243,6 +248,15 @@ function M.Model:init(context)
for _, f in ipairs(_members(Model)) do tload(f.name) end
end
+--- fetch an object in the context of the model object's transaction.
+-- @function Model:fetch
+-- @tparam string path path of the object to fetch. A path relative to
+-- the model object's own path may be used.
+-- @return (<i>**primitive**</i> or <i>@{node.TreeNode}</i>) fetched
+-- object. An instance of @{node.TreeNode} represents a non-leaf
+-- object in the data model, in the context of a specific
+-- transaction. Model objects themselves are a special case of such
+-- objects.
function M.Model:fetch(path, create)
return getmetatable(self).fetch(path, create)
end
diff --git a/aconf/model/net.lua b/aconf/model/net.lua
index 6de00f0..8ca7921 100644
--- a/aconf/model/net.lua
+++ b/aconf/model/net.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
@@ -168,6 +169,9 @@ function M.IPv6Address:mask2cidr(mask) return mask end
function M.IPv6Address:cidr2mask(cidr) return cidr end
+--- IP address field, inherits @{Field}. Accepts both IPv4 and IPv6
+-- address values.
+-- @klass net.IPAddress
M.IPAddress = class(Union)
function M.IPAddress:init(params)
@@ -190,6 +194,8 @@ end
local domain_pattern = '[A-Za-z%d%.%-]+%.[A-Za-z][A-Za-z]+'
+--- domain name field, inherits @{String}.
+-- @klass net.DomainName
M.DomainName = class(String)
function M.DomainName:init(params)
super(self, M.DomainName):init(update(params, {pattern=domain_pattern}))
diff --git a/aconf/model/node.lua b/aconf/model/node.lua
index a9854ce..c1d53e9 100644
--- a/aconf/model/node.lua
+++ b/aconf/model/node.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')
@@ -62,6 +63,16 @@ function M.BoundMember:init(parent, name, field)
end
+--- non-leaf object. An instance of this class represents
+-- a non-leaf object in the data model, in the context of a specific
+-- transaction. These instances appear as Lua tables, such that their
+-- children may be read and written by using their relative path name
+-- as the key. If the child is of complex type, it is possible to
+-- assign a structure of Lua tables as the value. This results in
+-- replacing the entire subtree with the provided sturcture. Providing
+-- a string in lieu of a complex value is handled by interpreting the
+-- string as a path and copying the subtree it refers to.
+-- @klass node.TreeNode
M.TreeNode = class()
local function equal_tns(tn1, tn2)
@@ -362,6 +373,12 @@ function M.Collection:init(context, params)
end
+--- list object, inherits @{node.TreeNode}. An instance of this class
+-- represents a list object in the data model, in the context of a
+-- specific transaction. 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 node.List
M.List = class(M.Collection)
local function _ipairs(mt, i)
@@ -430,6 +447,13 @@ function M.List:init(context, params)
end
end
+ --- inserts a member to a list or set
+ -- @function node.insert
+ -- @tparam node.List list list or set
+ -- @param v value to be inserted
+ -- @tparam ?int i index. By default, the element is inserted at the
+ -- end of the list. This parameter is not applicable when inserting
+ -- to a @{node.Set} instance.
function mt.insert(v, i)
assert(v ~= nil)
diff --git a/aconf/model/root.lua b/aconf/model/root.lua
index eef48ec..b60ce59 100644
--- a/aconf/model/root.lua
+++ b/aconf/model/root.lua
@@ -63,11 +63,12 @@ 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.
+-- @param field (<i>@{Field}</i> or <i>[&lt;Model&gt;](#new)</i>) type
+-- of the field, specified by a subclass of @{Field} or an instance of
+-- such. Can also be specified by a [&lt;Model&gt;](#new).
-- @tparam ?{[string]=any,...} params field parameters. Applicable
--- when field type is specified by a class (not an instance).
+-- when field type is specified by a @{Field} subclass or
+-- [&lt;Model&gt;](#new).
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 9ce3685..8016c16 100644
--- a/aconf/model/service.lua
+++ b/aconf/model/service.lua
@@ -14,9 +14,9 @@ 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 (<i>[&lt;Model&gt;](#new)</i>) 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()
diff --git a/aconf/model/set.lua b/aconf/model/set.lua
index 897e1bf..dd28a2e 100644
--- a/aconf/model/set.lua
+++ b/aconf/model/set.lua
@@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen
See LICENSE file for license details
--]]
+--- @module aconf.model
local M = {}
local TreeNode = require('aconf.model.field').TreeNode
@@ -12,6 +13,13 @@ local pth = require('aconf.path')
local util = require('aconf.util')
+--- set object, inherits @{node.List}. An instance of this class represents
+-- a set object in the data model, in the context of a specific
+-- transaction. A set is an unordered collection of primitive
+-- values. Members can be inserted to the set using
+-- @{node.insert}. Members can be removed by assigning the nil value
+-- to the key to be removed.
+-- @klass node.Set
M.Set = object.class(require('aconf.model.node').List)
function M.Set:init(context, params)
@@ -48,6 +56,11 @@ function M.Set:init(context, params)
mt.save(i, nil)
end
+ --- determines if the given set contains the given value.
+ -- @function node.contains
+ -- @tparam node.Set set set
+ -- @tparam primitive v value
+ -- @treturn boolean true if the set contains the value
function mt.contains(v) return find(v) and true or false end
local insert = mt.insert