summaryrefslogtreecommitdiffstats
path: root/aconf/model/init.lua
diff options
context:
space:
mode:
authorKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2016-12-09 19:50:10 +0200
committerKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2016-12-19 22:40:51 +0200
commitcc8acc5fa708b9f24369d71b5e982a0314ca64d7 (patch)
tree4bbbe8eb323a8bf725f11c4081e9940779f2d43d /aconf/model/init.lua
parent88a2ee4783d15c74f735f26c48b621b5e848d334 (diff)
downloadaconf-cc8acc5fa708b9f24369d71b5e982a0314ca64d7.tar.bz2
aconf-cc8acc5fa708b9f24369d71b5e982a0314ca64d7.tar.xz
doc: describe functionality used in the network module
Diffstat (limited to 'aconf/model/init.lua')
-rw-r--r--aconf/model/init.lua81
1 files changed, 68 insertions, 13 deletions
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 02bbb83..9a84b54 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -23,6 +23,8 @@ local Field = fld.Field
M.Boolean = fld.Boolean
--- integer field.
-- @fclass Integer
+-- @tparam ?int max maximum allowed value
+-- @tparam ?int min minimum allowed value
M.Integer = fld.Integer
M.Number = fld.Number
--- string field.
@@ -76,6 +78,31 @@ local update = util.update
local stringy = require('stringy')
+--- reference field. The value of this field refers to another node in
+-- the data model. Reading the value of this field generally yields
+-- the referred @{node.TreeNode} instance or primitive value. If the
+-- reference is a @{node.Set} member, reading yields the relative path
+-- of the referred node. The value can be set by assigning the
+-- reference a @{node.TreeNode} instance or a data model path. The
+-- path can be absolute or relative to the scope of the reference. If
+-- a *compute* function is provided, the return value is supposed to
+-- be a relative path.
+-- @fclass Reference
+-- @tparam ?{[string]=primitive,...} filter limit the reference to
+-- [model objects](#Model_objects), the fields of which have specific
+-- values. The keys of the table define the fields, and the
+-- corresponding values define required field values. If a value is a
+-- table, the field can have any of the value given in the table to
+-- make the object eligible.
+-- @tparam ?string on_delete specify behavior when the referenced node
+-- is deleted. If set to *set-null*, the value of the reference is
+-- cleared. If set to *cascade*, the parent model of this reference is
+-- deleted. The default mode is *restrict*, which prevents the
+-- deletion of the referenced node.
+-- @tparam ?string scope limit the nodes that can be referenced to a
+-- subtree defined by this path. The path can be absolute or relative
+-- to the reference field. By default, the scope is the entire data
+-- model.
M.Reference = class(Field)
function M.Reference:init(params)
@@ -214,12 +241,15 @@ end
-- field with default parameters is implicitly created when a model is
-- used in lieu of a field.
-- @fclass Model
+-- @tparam ?boolean create specifies whether the model is created
+-- automatically with the parent object, defaults to false
-- @param model (<i>[&lt;Model&gt;](#new)</i>) model describing the
-- structure of the model objects
M.Model = fld.Model
---- collection field.
+--- collection field. The value of this field is an instance of
+-- @{node.Collection}.
-- @fclass Collection
-- @param key (optional
-- <i>[&lt;Field&gt;](#Overview_of_field_classes)</i>) primitive field
@@ -307,7 +337,17 @@ function M.Mixed:save(context, value)
end
+--- install pre or post&ndash;commit hook, which is called whenever
+-- the specified back-end subtree is affected.
+-- @tparam string phase *pre* or *post*
+-- @tparam string addr back-end address specifying the scope
+-- @tparam function() func hook function
function M.trigger(phase, addr, func) store:trigger(phase, addr, func) end
+
+--- defer committing a transaction affecting the specified back-end
+-- subtree until the client socket has been closed. This is mainly
+-- used with network configuration.
+-- @tparam string addr back-end address specifying the scope
function M.defer(addr) def_store:defer(addr) end
@@ -319,12 +359,16 @@ function M.defer(addr) def_store:defer(addr) end
-- @section Field
--- 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.
--- @tfield ?string addr
+-- absolute address or relative to the parent's address. Can also be
+-- defined as a function which receives the field's absolute path in
+-- the data model as an argument and returns either absolute or
+-- relative back-end 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.
+-- @field addr (optional <i>**string**</i> or
+-- <i>**function(string)**</i>)
--- back-end mode. Controls how the Augeas back-end will map addresses
-- to Augeas paths. By default, each component of a back-end address
@@ -344,16 +388,21 @@ function M.defer(addr) def_store:defer(addr) end
-- <i>**{[string]=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.
+-- table specifying the value used by the data model and a
+-- user-friendly value. The table may contain additional
+-- choice-specific parameters. *be\_value* specifies the choice's
+-- value in the back-end if different from the data model. *enabled*
+-- specifies whether the choice is available for the user, defaulting
+-- to true.
-- @field choice (optional <i>**{primitive**</i> or
--- <i>**{primitive,string},...}**</i>)
+-- <i>**{primitive,string[,'be_value'=string][,'enabled'=boolean]},...}**</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.
--- @field compute (optional <i><b>function(@{node.TreeNode})</b></i>
+-- and the ongoing transaction as arguments. If defined as a string, a
+-- method with the given name is invoked.
+-- @field compute (optional
+-- <i><b>function(@{node.TreeNode},[&lt;Transaction&gt;](#Transaction_objects))</b></i>
-- or <i>**string**</i>)
--- indicates this field is relevant only when other fields of the
@@ -368,6 +417,12 @@ function M.defer(addr) def_store:defer(addr) end
--- default value for the field.
-- @tfield ?primitive default
+--- specifies whether the field shall be hidden in tabular user
+-- interface layout. By default, only leaf objects are shown.
+-- @tfield ?boolean detail specifies whether the field shall be hidden
+-- in tabular user interface layout. By default, only leaf objects are
+-- shown.
+
--- boolean or function specifying whether the value of the field can
-- be changed. If defined as a function, the return value determines
-- the behavior. The function gets a reference to the field's parent