diff options
| -rw-r--r-- | aconf/model/field.lua | 7 | ||||
| -rw-r--r-- | aconf/model/init.lua | 81 | ||||
| -rw-r--r-- | aconf/model/model.lua | 14 | ||||
| -rw-r--r-- | aconf/model/net.lua | 15 | ||||
| -rw-r--r-- | aconf/model/node.lua | 26 | ||||
| -rw-r--r-- | aconf/path.lua | 16 | ||||
| -rw-r--r-- | aconf/transaction/init.lua | 11 |
7 files changed, 148 insertions, 22 deletions
diff --git a/aconf/model/field.lua b/aconf/model/field.lua index cd849e2..414cd62 100644 --- a/aconf/model/field.lua +++ b/aconf/model/field.lua @@ -3,7 +3,12 @@ Copyright (c) 2012-2016 Kaarle Ritvanen See LICENSE file for license details --]] ---- Alpine Configurator data model. +--- Alpine Configurator (aconf) data model. This module is imported by +-- all aconf modules. The aconf modules are installed to +-- */usr/share/aconf/aconf/modules* and imported automatically from +-- there. On import, the module may return an initialization function, +-- which receives a [transaction object](#Transaction_objects) as an +-- argument. -- @module aconf.model local M = {} diff --git a/aconf/model/init.lua b/aconf/model/init.lua index 02bbb83..9a84b54 100644 --- a/aconf/model/init.lua +++ b/aconf/model/init.lua @@ -23,6 +23,8 @@ local Field = fld.Field M.Boolean = fld.Boolean --- integer field. -- @fclass Integer +-- @tparam ?int max maximum allowed value +-- @tparam ?int min minimum allowed value M.Integer = fld.Integer M.Number = fld.Number --- string field. @@ -76,6 +78,31 @@ local update = util.update local stringy = require('stringy') +--- reference field. The value of this field refers to another node in +-- the data model. Reading the value of this field generally yields +-- the referred @{node.TreeNode} instance or primitive value. If the +-- reference is a @{node.Set} member, reading yields the relative path +-- of the referred node. The value can be set by assigning the +-- reference a @{node.TreeNode} instance or a data model path. The +-- path can be absolute or relative to the scope of the reference. If +-- a *compute* function is provided, the return value is supposed to +-- be a relative path. +-- @fclass Reference +-- @tparam ?{[string]=primitive,...} filter limit the reference to +-- [model objects](#Model_objects), the fields of which have specific +-- values. The keys of the table define the fields, and the +-- corresponding values define required field values. If a value is a +-- table, the field can have any of the value given in the table to +-- make the object eligible. +-- @tparam ?string on_delete specify behavior when the referenced node +-- is deleted. If set to *set-null*, the value of the reference is +-- cleared. If set to *cascade*, the parent model of this reference is +-- deleted. The default mode is *restrict*, which prevents the +-- deletion of the referenced node. +-- @tparam ?string scope limit the nodes that can be referenced to a +-- subtree defined by this path. The path can be absolute or relative +-- to the reference field. By default, the scope is the entire data +-- model. M.Reference = class(Field) function M.Reference:init(params) @@ -214,12 +241,15 @@ end -- field with default parameters is implicitly created when a model is -- used in lieu of a field. -- @fclass Model +-- @tparam ?boolean create specifies whether the model is created +-- automatically with the parent object, defaults to false -- @param model (<i>[<Model>](#new)</i>) model describing the -- structure of the model objects M.Model = fld.Model ---- collection field. +--- collection field. The value of this field is an instance of +-- @{node.Collection}. -- @fclass Collection -- @param key (optional -- <i>[<Field>](#Overview_of_field_classes)</i>) primitive field @@ -307,7 +337,17 @@ function M.Mixed:save(context, value) end +--- install pre or post–commit hook, which is called whenever +-- the specified back-end subtree is affected. +-- @tparam string phase *pre* or *post* +-- @tparam string addr back-end address specifying the scope +-- @tparam function() func hook function function M.trigger(phase, addr, func) store:trigger(phase, addr, func) end + +--- defer committing a transaction affecting the specified back-end +-- subtree until the client socket has been closed. This is mainly +-- used with network configuration. +-- @tparam string addr back-end address specifying the scope function M.defer(addr) def_store:defer(addr) end @@ -319,12 +359,16 @@ function M.defer(addr) def_store:defer(addr) end -- @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 +-- absolute address or relative to the parent's address. Can also be +-- defined as a function which receives the field's absolute path in +-- the data model as an argument and returns either absolute or +-- relative back-end 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. +-- @field addr (optional <i>**string**</i> or +-- <i>**function(string)**</i>) --- back-end mode. Controls how the Augeas back-end will map addresses -- to Augeas paths. By default, each component of a back-end address @@ -344,16 +388,21 @@ function M.defer(addr) def_store:defer(addr) end -- <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. +-- table specifying the value used by the data model and a +-- user-friendly value. The table may contain additional +-- choice-specific parameters. *be\_value* specifies the choice's +-- value in the back-end if different from the data model. *enabled* +-- specifies whether the choice is available for the user, defaulting +-- to true. -- @field choice (optional <i>**{primitive**</i> or --- <i>**{primitive,string},...}**</i>) +-- <i>**{primitive,string[,'be_value'=string][,'enabled'=boolean]},...}**</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> +-- and the ongoing transaction as arguments. If defined as a string, a +-- method with the given name is invoked. +-- @field compute (optional +-- <i><b>function(@{node.TreeNode},[<Transaction>](#Transaction_objects))</b></i> -- or <i>**string**</i>) --- indicates this field is relevant only when other fields of the @@ -368,6 +417,12 @@ function M.defer(addr) def_store:defer(addr) end --- default value for the field. -- @tfield ?primitive default +--- specifies whether the field shall be hidden in tabular user +-- interface layout. By default, only leaf objects are shown. +-- @tfield ?boolean detail specifies whether the field shall be hidden +-- in tabular user interface layout. By default, only leaf objects are +-- shown. + --- 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 diff --git a/aconf/model/model.lua b/aconf/model/model.lua index ba6d004..8c62535 100644 --- a/aconf/model/model.lua +++ b/aconf/model/model.lua @@ -72,10 +72,12 @@ end -- 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 -- class](#Overview_of_field_classes), an instance of field, or --- another **<Model>**. +-- another **<Model>**. The model's behavior can be customized +-- by overriding some of its [methods](#Model_objects). -- @param base (optional <i>**<Model>**</i>) base model -- inherited by the new model. --- @return <i>**<Model>**</i> new model +-- @return <i>**<Model>**</i> new model, subclass of +-- @{node.TreeNode} function M.new(base) if not base then base = M.Model end @@ -185,6 +187,10 @@ function M.Model:init(context) if self.is_removable then function mt.removable() + --- determine whether this model object can be removed from + -- the data model. + -- @function is_removable + -- @treturn boolean true if the object is removable return mt.has_permission('delete') and self:is_removable() end end @@ -238,6 +244,10 @@ function M.Model:init(context) if self:match(f.condition or {}) then f:validate_saved() elseif f:_editable() then f:_save() end end + --- check the validity of the model. This method may raise an + -- error or change the values of the model's fields. By default, + -- this method is not implemented. + -- @function validate if self.validate then self:validate() end end diff --git a/aconf/model/net.lua b/aconf/model/net.lua index 40ddd36..57eb3ea 100644 --- a/aconf/model/net.lua +++ b/aconf/model/net.lua @@ -74,6 +74,14 @@ function BaseIPAddress:encode(context, value) end +--- IPv4 address field, inherits @{String}. +-- @fclass net.IPv4Address +-- @tparam boolean cidr if set to true, the field accepts a network +-- address in CIDR notation +-- @tparam string mask_addr if set, the network address is decomposed +-- into address and netmask in the back-end. This parameter specifies +-- the back-end address where the netmask is stored in dotted-quad +-- format. M.IPv4Address = class(BaseIPAddress) function M.IPv4Address:init(params) @@ -122,6 +130,13 @@ function M.IPv4Address:cidr2mask(cidr) end +--- IPv6 address field, inherits @{String}. +-- @fclass net.IPv6Address +-- @tparam boolean cidr if set to true, the field accepts a network +-- address +-- @tparam string mask_addr if set, the network address is decomposed +-- into address and netmask parts in the back-end. This parameter +-- specifies the back-end address where the netmask length is stored. M.IPv6Address = class(BaseIPAddress) function M.IPv6Address:init(params) diff --git a/aconf/model/node.lua b/aconf/model/node.lua index 7296446..70aa4fc 100644 --- a/aconf/model/node.lua +++ b/aconf/model/node.lua @@ -43,6 +43,10 @@ function M.BoundMember:init(parent, name, field) self.addr = pth.to_absolute(self.addr, pmt.addr) end + --- get parent object of an object. + -- @function node.parent + -- @tparam node.TreeNode node object + -- @treturn node.TreeNode parent object local context = { txn=pmt.txn, privileged=pmt.privileged, @@ -71,7 +75,9 @@ end -- 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. +-- string as a path and copying the subtree it refers to. Comparison +-- of these instances with the == operator returns true if the +-- instances represent the same object. -- @klass node.TreeNode M.TreeNode = class() @@ -83,7 +89,13 @@ function M.TreeNode:init(context, params) local mt = getmetatable(self) update(mt, context) + --- get the name of the object, i.e. the last component of its + -- absolute path. + -- @function node.name + -- @tparam node.TreeNode node object + -- @treturn string name mt.name = pth.name(mt.path) + mt.__eq = equal_tns mt.__pairs = M.pairs @@ -260,6 +272,12 @@ function M.TreeNode:init(context, params) end +--- collection object, inherits @{node.TreeNode}. An instance of this class +-- represents a collection object in the data model, in the context of +-- a specific transaction. The path of a collection member is that of +-- the collection augmented by the respective key. The size of the +-- collection can be queried using the # operator. +-- @klass node.Collection M.Collection = class(M.TreeNode) function M.Collection:init(context, params) @@ -362,9 +380,9 @@ 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 +--- list object, inherits @{node.Collection}. 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 diff --git a/aconf/path.lua b/aconf/path.lua index 4e289f5..8091a35 100644 --- a/aconf/path.lua +++ b/aconf/path.lua @@ -1,8 +1,9 @@ --[[ -Copyright (c) 2012-2015 Kaarle Ritvanen +Copyright (c) 2012-2016 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} local map = require('aconf.util').map @@ -26,12 +27,25 @@ function M.escape(comp) end +--- joins a number of already escaped path components into a single +--- path. +-- @function path.rawjoin +-- @tparam string p1 path component +-- @tparam ?string p2 path component +-- @tparam ?string ... path component +-- @treturn string path function M.rawjoin(p1, p2, ...) if not p2 then return p1 end if not M.is_absolute(p2) then p2 = '/'..p2 end return M.rawjoin((p1 == '/' and '' or p1)..p2, ...) end +--- appends a number of additional components to a path. The appended +-- components are escaped first. +-- @function path.join +-- @tparam string parent path +-- @tparam ?string ... path component +-- @treturn string path function M.join(parent, ...) local args = map(function(c) return M.escape(c) end, {...}) if parent > '' then table.insert(args, 1, parent) end diff --git a/aconf/transaction/init.lua b/aconf/transaction/init.lua index 2aabec5..5c71ce8 100644 --- a/aconf/transaction/init.lua +++ b/aconf/transaction/init.lua @@ -1,8 +1,10 @@ --[[ -Copyright (c) 2012-2015 Kaarle Ritvanen +Copyright (c) 2012-2016 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model + local ErrorDict = require('aconf.error').ErrorDict local root = require('aconf.model.root') @@ -15,6 +17,9 @@ local util = require('aconf.util') local copy = util.copy +--- Transaction objects. These objects represent and ongoing +-- transaction. +-- @section ModelTransaction local ModelTransaction = object.class( require('aconf.transaction.base').Transaction ) @@ -38,6 +43,10 @@ function ModelTransaction:check() if not self.backend then error('Transaction already committed') end end +--- fetch an object. +-- @function get +-- @tparam string path object path +-- @treturn primitive|node.TreeNode object function ModelTransaction:get(path) self:check() return super(self, ModelTransaction):get(path) |