From c248dca6eeaa6994fc3ab663f431238266417241 Mon Sep 17 00:00:00 2001 From: Kaarle Ritvanen Date: Fri, 16 Dec 2016 14:51:28 +0200 Subject: doc: section for field constructor parameters --- aconf/model/config.ld | 3 +- aconf/model/field.lua | 70 ++++++------------------------------------ aconf/model/init.lua | 85 ++++++++++++++++++++++++++++++++++++++++++++++----- aconf/model/model.lua | 5 +-- aconf/model/net.lua | 4 +-- aconf/model/root.lua | 12 ++++---- 6 files changed, 100 insertions(+), 79 deletions(-) (limited to 'aconf') 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–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 **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) @@ -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 ([<Model>](#new)) 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 (@{Field} or [<Model>](#new)) --- subclass of @{Field}, instance of such, or --- [**<Model>**](#new) specifying the type of the members. +--- collection field. +-- @fcons Collection +-- @param type ([<Field>](#Field_constructors) or +-- [<Model>](#new)) 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–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 **string** or +-- **{[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. +-- @field choice (optional **{primitive** or +-- **{primitive,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. +-- @field compute (optional function(@{node.TreeNode}) +-- or **string**) + +--- 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 function(@{node.TreeNode}, +-- primitive) or **string**) + +--- 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–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>**. +-- the value will determine its type. The value shall be a [field +-- constructor](#Field_constructors), 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 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 (@{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). +-- @param field ([<Field>](#Field_constructors) or +-- [<Model>](#new)) 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 --- [<Model>](#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 -- cgit v1.2.3