From a92dc45aee3f599926c77294328db38c5b2544eb Mon Sep 17 00:00:00 2001 From: Kaarle Ritvanen Date: Fri, 3 Apr 2015 10:40:28 +0300 Subject: docs: describe functionality used in the dnsmasq module --- aconf/model/field.lua | 62 +++++++++++++++++++++++++++++++++++-------------- aconf/model/init.lua | 18 +++++++++----- aconf/model/model.lua | 28 ++++++++++++++++------ aconf/model/net.lua | 6 +++++ aconf/model/node.lua | 24 +++++++++++++++++++ aconf/model/root.lua | 9 +++---- aconf/model/service.lua | 6 ++--- aconf/model/set.lua | 13 +++++++++++ 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 **string** or +-- **{[string]=string,...}**) 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 **{primitive** or +-- **{primitive,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. +-- @param compute (optional function(@{node.TreeNode}) +-- or **string**) 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 function(@{node.TreeNode}, +-- primitive) or **string**) 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 model object 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 ([<Model>](#new)) 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 (@{Field} or [<Model>](#new)) +-- subclass of @{Field}, instance of such, or +-- [**<Model>**](#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–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–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 **<Model>**. +-- @function new +-- @param base (optional **<Model>**) base model +-- inherited by the new model. +-- @return **<Model>** 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 (**primitive** or @{node.TreeNode}) 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 (@{Field} or [<Model>](#new)) type +-- of the field, specified by a subclass of @{Field} or an instance of +-- such. Can also be specified by a [<Model>](#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 +-- [<Model>](#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 ([<Model>](#new)) 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 -- cgit v1.2.3