summaryrefslogtreecommitdiffstats
path: root/aconf
diff options
context:
space:
mode:
authorKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2016-12-16 14:51:28 +0200
committerKaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>2016-12-18 23:02:07 +0200
commitc248dca6eeaa6994fc3ab663f431238266417241 (patch)
tree60fc868dcf8f3bcfc21a8d82265bc45420b2adaf /aconf
parent2cc92ad225ef0fd2756b44c9dc81c59fedbf2f20 (diff)
downloadaconf-c248dca6eeaa6994fc3ab663f431238266417241.tar.bz2
aconf-c248dca6eeaa6994fc3ab663f431238266417241.tar.xz
doc: section for field constructor parameters
Diffstat (limited to 'aconf')
-rw-r--r--aconf/model/config.ld3
-rw-r--r--aconf/model/field.lua70
-rw-r--r--aconf/model/init.lua85
-rw-r--r--aconf/model/model.lua5
-rw-r--r--aconf/model/net.lua4
-rw-r--r--aconf/model/root.lua12
6 files changed, 100 insertions, 79 deletions
diff --git a/aconf/model/config.ld b/aconf/model/config.ld
index 54c9473..f8976d6 100644
--- a/aconf/model/config.ld
+++ b/aconf/model/config.ld
@@ -1,6 +1,7 @@
--[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
See LICENSE file for license details
--]]
+new_type('fcons', 'Field constructors', false, 'Additional constructor parameters')
new_type('klass', 'Classes', false, 'Constructor parameters')
diff --git a/aconf/model/field.lua b/aconf/model/field.lua
index 70930d7..f1236aa 100644
--- a/aconf/model/field.lua
+++ b/aconf/model/field.lua
@@ -57,58 +57,6 @@ function M.conv_filter(filter)
end
-
---- 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.
--- @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)
@@ -316,8 +264,8 @@ function Primitive:validate(context, value)
end
---- string field, inherits @{Field}.
--- @klass String
+--- string field.
+-- @fcons String
M.String = class(Primitive)
function M.String:init(params)
@@ -372,8 +320,8 @@ function M.Integer:validate(context, value)
end
---- boolean field, inherits @{Field}.
--- @klass Boolean
+--- boolean field.
+-- @fcons Boolean
M.Boolean = class(Primitive)
function M.Boolean:init(params)
@@ -450,11 +398,11 @@ function M.TreeNode:validate_saved(context)
end
---- model field, inherits @{Field}. The value of this field is a
--- [model object](#Model_objects) 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
+--- model field. The value of this field is a [model
+-- object](#Model_objects) conforming to the specified model. A model
+-- field with default parameters is implicitly created when a model is
+-- used in lieu of a field.
+-- @fcons Model
-- @param model (<i>[&lt;Model&gt;](#new)</i>) model describing the
-- structure of the model objects
M.Model = class(M.TreeNode)
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 35dfc7b..aaf6ad0 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -206,11 +206,11 @@ end
M.Model = fld.Model
---- 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.
+--- collection field.
+-- @fcons Collection
+-- @param type (<i>[&lt;Field&gt;](#Field_constructors)</i> or
+-- <i>[&lt;Model&gt;](#new)</i>) field constructor, field instance, or
+-- model specifying the type of the members.
-- @tparam ?string ui_member user-friendly noun for a member of this
-- collection
M.Collection = class(fld.TreeNode)
@@ -251,14 +251,14 @@ end
--- list field, inherits @{Collection}. The value of this field is an
-- instance of @{node.List}.
--- @klass List
+-- @fcons List
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
+-- @fcons Set
M.Set = class(M.Collection)
function M.Set:init(params)
if not params.widget and isinstance(params.type, M.Reference) then
@@ -295,4 +295,75 @@ function M.trigger(phase, addr, func) store:trigger(phase, addr, func) end
function M.defer(addr) def_store:defer(addr) end
+--- Field constructor parameters. All field constructors accept one
+-- table argument containing field parameters as key&ndash;value
+-- pairs. The parameters listed below are valid for all
+-- subclasses. Subclasses may define additional parameters.
+-- @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
+
+--- back-end 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.
+-- @field be_mode (optional <i>**string**</i> or
+-- <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.
+-- @field choice (optional <i>**{primitive**</i> or
+-- <i>**{primitive,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.
+-- @field compute (optional <i><b>function(@{node.TreeNode})</b></i>
+-- or <i>**string**</i>)
+
+--- default value for the field.
+-- @tfield ?primitive default
+
+--- required field must be assigned a value if set. Defaults to false.
+-- @tfield ?boolean required
+
+--- function for storing the value of the field. 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.
+-- @field store (optional <i><b>function(@{node.TreeNode},
+-- primitive)</b></i> or <i>**string**</i>)
+
+--- user-friendly name for the field.
+-- @tfield ?string ui_name
+
+--- visibility of the field in the user interface. Defaults to true.
+-- @tfield ?boolean visible
+
+--- 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.
+-- @tfield ?string widget
+
+
return M
diff --git a/aconf/model/model.lua b/aconf/model/model.lua
index 7417115..3a28d90 100644
--- a/aconf/model/model.lua
+++ b/aconf/model/model.lua
@@ -70,8 +70,9 @@ end
--- 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;**.
+-- the value will determine its type. The value shall be a [field
+-- constructor](#Field_constructors), an instance of field, or another
+-- **&lt;Model&gt;**.
-- @param base (optional <i>**&lt;Model&gt;**</i>) base model
-- inherited by the new model.
-- @return <i>**&lt;Model&gt;**</i> new model
diff --git a/aconf/model/net.lua b/aconf/model/net.lua
index cc3a1e6..b48a57c 100644
--- a/aconf/model/net.lua
+++ b/aconf/model/net.lua
@@ -171,7 +171,7 @@ function M.IPv6Address:cidr2mask(cidr) return cidr end
--- IP address field, inherits @{String}. Accepts both IPv4 and IPv6
-- address values.
--- @klass net.IPAddress
+-- @fcons net.IPAddress
M.IPAddress = class(Union)
function M.IPAddress:init(params)
@@ -195,7 +195,7 @@ end
local domain_pattern = '[A-Za-z%d%.%-]+%.[A-Za-z][A-Za-z]+'
--- domain name field, inherits @{String}.
--- @klass net.DomainName
+-- @fcons 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/root.lua b/aconf/model/root.lua
index b60ce59..32b013d 100644
--- a/aconf/model/root.lua
+++ b/aconf/model/root.lua
@@ -1,5 +1,5 @@
--[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
See LICENSE file for license details
--]]
@@ -63,12 +63,12 @@ M.topology = setmetatable(
--- inject a new field to the root model.
-- @tparam string name name of the field
--- @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).
+-- @param field (<i>[&lt;Field&gt;](#Field_constructors)</i> or
+-- <i>[&lt;Model&gt;](#new)</i>) type of the field, specified by a
+-- field constructor or instance. Can also be specified by a model.
-- @tparam ?{[string]=any,...} params field parameters. Applicable
--- when field type is specified by a @{Field} subclass or
--- [&lt;Model&gt;](#new).
+-- when the type of the field is specified by a model or a field
+-- constructor.
function M.register(name, field, params)
if not params then params = {} end
params.create = true