From cc8acc5fa708b9f24369d71b5e982a0314ca64d7 Mon Sep 17 00:00:00 2001 From: Kaarle Ritvanen Date: Fri, 9 Dec 2016 19:50:10 +0200 Subject: doc: describe functionality used in the network module --- aconf/model/init.lua | 81 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 13 deletions(-) (limited to 'aconf/model/init.lua') 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 ([<Model>](#new)) 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 -- [<Field>](#Overview_of_field_classes)) primitive field @@ -307,7 +337,17 @@ function M.Mixed:save(context, value) end +--- install pre or post–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 **string** or +-- **function(string)**) --- 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 -- **{[string]=string,...}**) --- 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 **{primitive** or --- **{primitive,string},...}**) +-- **{primitive,string[,'be_value'=string][,'enabled'=boolean]},...}**) --- 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 function(@{node.TreeNode}) +-- and the ongoing transaction as arguments. If defined as a string, a +-- method with the given name is invoked. +-- @field compute (optional +-- function(@{node.TreeNode},[<Transaction>](#Transaction_objects)) -- or **string**) --- 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 -- cgit v1.2.3