summaryrefslogtreecommitdiffstats
path: root/aconf
diff options
context:
space:
mode:
Diffstat (limited to 'aconf')
-rw-r--r--aconf/model/config.ld2
-rw-r--r--aconf/model/field.lua36
-rw-r--r--aconf/model/init.lua55
-rw-r--r--aconf/model/model.lua4
-rw-r--r--aconf/model/net.lua7
-rw-r--r--aconf/model/root.lua6
-rw-r--r--aconf/object.lua8
7 files changed, 89 insertions, 29 deletions
diff --git a/aconf/model/config.ld b/aconf/model/config.ld
index f8976d6..8882f39 100644
--- a/aconf/model/config.ld
+++ b/aconf/model/config.ld
@@ -3,5 +3,5 @@ Copyright (c) 2012-2016 Kaarle Ritvanen
See LICENSE file for license details
--]]
-new_type('fcons', 'Field constructors', false, 'Additional constructor parameters')
+new_type('fclass', 'Field classes', false, 'Additional constructor parameters')
new_type('klass', 'Classes', false, 'Constructor parameters')
diff --git a/aconf/model/field.lua b/aconf/model/field.lua
index f1236aa..cd849e2 100644
--- a/aconf/model/field.lua
+++ b/aconf/model/field.lua
@@ -3,7 +3,8 @@ Copyright (c) 2012-2016 Kaarle Ritvanen
See LICENSE file for license details
--]]
---- @module aconf.model
+--- Alpine Configurator data model.
+-- @module aconf.model
local M = {}
local err = require('aconf.error')
@@ -57,6 +58,14 @@ function M.conv_filter(filter)
end
+--- Overview of field classes. In the Alpine Configurator object
+-- system, classes are instantiated by invoking the Lua table
+-- representing the class as the constructor. There are a number of
+-- [pre-defined field classes](#Field_classes). More field classes may
+-- be defined by extending them using @{object.class} and overriding
+-- the appropriate methods described in this section. All field class
+-- constructors accept one [argument](#Field_constructor_parameters).
+-- @section Field
M.Field = class(M.Member)
function M.Field:init(params)
@@ -185,6 +194,13 @@ function M.Field:_load(context)
if value ~= nil then return self:decode(context, value) end
end
+--- transform the value's back-end representation to data model
+-- representation. The default implementation is the identity
+-- transformation.
+-- @function decode
+-- @param context transaction context
+-- @tparam primitive value back-end representation
+-- @treturn primitive data model representation
function M.Field:decode(context, value) return value end
function M.Field:_validate(context, value)
@@ -236,6 +252,13 @@ function M.Field:_save(context, value)
context.txn:set(context.addr, value)
end
+--- transform the value's data model representation to back-end
+-- representation. The default implementation is the identity
+-- transformation.
+-- @function encode
+-- @param context transaction context
+-- @tparam primitive value data model representation
+-- @treturn primitive back-end representation
function M.Field:encode(context, value) return value end
function M.Field:validate_saved(context)
@@ -264,8 +287,6 @@ function Primitive:validate(context, value)
end
---- string field.
--- @fcons String
M.String = class(Primitive)
function M.String:init(params)
@@ -320,8 +341,6 @@ function M.Integer:validate(context, value)
end
---- boolean field.
--- @fcons Boolean
M.Boolean = class(Primitive)
function M.Boolean:init(params)
@@ -398,13 +417,6 @@ function M.TreeNode:validate_saved(context)
end
---- 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)
function M.Model:init(params)
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index aaf6ad0..02bbb83 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -18,9 +18,15 @@ M.Range = combination.Range
local fld = require('aconf.model.field')
local Field = fld.Field
+--- boolean field.
+-- @fclass Boolean
M.Boolean = fld.Boolean
+--- integer field.
+-- @fclass Integer
M.Integer = fld.Integer
M.Number = fld.Number
+--- string field.
+-- @fclass String
M.String = fld.String
local model = require('aconf.model.model')
@@ -203,14 +209,24 @@ function M.Reference:deleted(context, addr)
end
+--- 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.
+-- @fclass Model
+-- @param model (<i>[&lt;Model&gt;](#new)</i>) model describing the
+-- structure of the model objects
M.Model = fld.Model
--- 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.
+-- @fclass Collection
+-- @param key (optional
+-- <i>[&lt;Field&gt;](#Overview_of_field_classes)</i>) primitive field
+-- class or instance used to validate the collection keys.
+-- @param type (<i>[&lt;Field&gt;](#Overview_of_field_classes)</i> or
+-- <i>[&lt;Model&gt;](#new)</i>) field class, 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 +267,14 @@ end
--- list field, inherits @{Collection}. The value of this field is an
-- instance of @{node.List}.
--- @fcons List
+-- @fclass 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}.
--- @fcons Set
+-- @fclass Set
M.Set = class(M.Collection)
function M.Set:init(params)
if not params.widget and isinstance(params.type, M.Reference) then
@@ -297,8 +313,9 @@ 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.
+-- pairs. The parameters listed below are valid for all field
+-- classes. Depending on the class, there may be additional
+-- parameters.
-- @section Field
--- back-end address for the field. This can be an
@@ -339,9 +356,31 @@ function M.defer(addr) def_store:defer(addr) end
-- @field compute (optional <i><b>function(@{node.TreeNode})</b></i>
-- or <i>**string**</i>)
+--- indicates this field is relevant only when other fields of the
+-- model have specific values. The keys of the table define the
+-- condition fields, and the corresponding values define required
+-- field values. If a value is a table, the condition field can have
+-- any of the value given in the table for this field to be considered
+-- relevant.
+-- @field condition (optional <i>**{[string]=string**</i> or
+-- <i>**{string,...},...}**</i>)
+
--- default value for the field.
-- @tfield ?primitive default
+--- 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
+-- as an argument. If defined as a string, a method with the given
+-- name is invoked. When this parameter is not defined, the behavior
+-- depends on the other parameters as follows: If *visible* is set to
+-- false, the field is not editable. Otherwise, if *store* is defined
+-- or *compute* is not, the field is editable. Otherwise, if the
+-- *compute* function yields a value, the field is not
+-- editable. Otherwise, the field is editable.
+-- @field editable (optional <i>**boolean**</i>,
+-- <i><b>function(@{node.TreeNode})</b></i> or <i>**string**</i>)
+
--- required field must be assigned a value if set. Defaults to false.
-- @tfield ?boolean required
diff --git a/aconf/model/model.lua b/aconf/model/model.lua
index 3a28d90..ba6d004 100644
--- a/aconf/model/model.lua
+++ b/aconf/model/model.lua
@@ -71,8 +71,8 @@ end
-- 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 [field
--- constructor](#Field_constructors), an instance of field, or another
--- **&lt;Model&gt;**.
+-- class](#Overview_of_field_classes), 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 b48a57c..40ddd36 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.
--- @fcons net.IPAddress
+-- @fclass net.IPAddress
M.IPAddress = class(Union)
function M.IPAddress:init(params)
@@ -184,6 +184,9 @@ function M.IPAddress:init(params)
end
+--- TCP or UDP port field, inherits @{Integer}. The value can be
+-- between 0 and 65535.
+-- @fclass net.Port
M.Port = class(fld.Integer)
function M.Port:validate(context, value)
@@ -195,7 +198,7 @@ end
local domain_pattern = '[A-Za-z%d%.%-]+%.[A-Za-z][A-Za-z]+'
--- domain name field, inherits @{String}.
--- @fcons net.DomainName
+-- @fclass 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 32b013d..301e493 100644
--- a/aconf/model/root.lua
+++ b/aconf/model/root.lua
@@ -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>[&lt;Field&gt;](#Field_constructors)</i> or
+-- @param field (<i>[&lt;Field&gt;](#Overview_of_field_classes)</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.
+-- field class or instance. Can also be specified by a model.
-- @tparam ?{[string]=any,...} params field parameters. Applicable
-- when the type of the field is specified by a model or a field
--- constructor.
+-- class.
function M.register(name, field, params)
if not params then params = {} end
params.create = true
diff --git a/aconf/object.lua b/aconf/object.lua
index dca59f6..910cf46 100644
--- a/aconf/object.lua
+++ b/aconf/object.lua
@@ -1,10 +1,16 @@
--[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
See LICENSE file for license details
--]]
+--- @module aconf.model
local M = {}
+--- create a new class.
+-- @function object.class
+-- @param base (optional <i>**&lt;Class&gt;**</i>) base class
+-- inherited by the new class.
+-- @return <i>**&lt;Class&gt;**</i> new class
function M.class(base)
local cls = {}