From 88a2ee4783d15c74f735f26c48b621b5e848d334 Mon Sep 17 00:00:00 2001 From: Kaarle Ritvanen Date: Fri, 9 Dec 2016 17:38:08 +0200 Subject: doc: describe functionality used in the dns-zone module --- aconf/model/config.ld | 2 +- aconf/model/field.lua | 36 ++++++++++++++++++++++----------- aconf/model/init.lua | 55 +++++++++++++++++++++++++++++++++++++++++++-------- aconf/model/model.lua | 4 ++-- aconf/model/net.lua | 7 +++++-- aconf/model/root.lua | 6 +++--- aconf/object.lua | 8 +++++++- 7 files changed, 89 insertions(+), 29 deletions(-) (limited to 'aconf') 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 ([<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 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 ([<Model>](#new)) model describing the +-- structure of the model objects M.Model = fld.Model --- collection field. --- @fcons Collection --- @param type ([<Field>](#Field_constructors) or --- [<Model>](#new)) field constructor, field instance, or --- model specifying the type of the members. +-- @fclass Collection +-- @param key (optional +-- [<Field>](#Overview_of_field_classes)) primitive field +-- class or instance used to validate the collection keys. +-- @param type ([<Field>](#Overview_of_field_classes) or +-- [<Model>](#new)) 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–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 function(@{node.TreeNode}) -- or **string**) +--- 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 **{[string]=string** or +-- **{string,...},...}**) + --- 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 **boolean**, +-- function(@{node.TreeNode}) or **string**) + --- 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–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 --- **<Model>**. +-- class](#Overview_of_field_classes), an instance of field, or +-- another **<Model>**. -- @param base (optional **<Model>**) base model -- inherited by the new model. -- @return **<Model>** 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 ([<Field>](#Field_constructors) or +-- @param field ([<Field>](#Overview_of_field_classes) or -- [<Model>](#new)) 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 **<Class>**) base class +-- inherited by the new class. +-- @return **<Class>** new class function M.class(base) local cls = {} -- cgit v1.2.3