X-Git-Url: https://git.archive.openwrt.org/?a=blobdiff_plain;f=libs%2Fuvl%2Fluasrc%2Fuvl.lua;h=cc1d8b9d6dfe2d32d19c0bd1e949e30d1f49ce6a;hb=e124eec0e86584a52ca1559459f58a99c5a0847c;hp=aa3aeb361d170ee41aec29136365c277156c19fe;hpb=1d08361bea91c11ba2f82f3ab3004c067ebabc85;p=project%2Fluci.git

diff --git a/libs/uvl/luasrc/uvl.lua b/libs/uvl/luasrc/uvl.lua
index aa3aeb361..cc1d8b9d6 100644
--- a/libs/uvl/luasrc/uvl.lua
+++ b/libs/uvl/luasrc/uvl.lua
@@ -14,6 +14,11 @@ $Id$
 
 ]]--
 
+
+--- UVL - UCI Validation Layer
+-- @class	module
+-- @cstyle	instance
+
 module( "luci.uvl", package.seeall )
 
 require("luci.fs")
@@ -24,16 +29,29 @@ require("luci.uvl.datatypes")
 require("luci.uvl.validation")
 require("luci.uvl.dependencies")
 
+
 TYPE_SECTION  = 0x01
 TYPE_VARIABLE = 0x02
 TYPE_ENUM     = 0x03
 
+--- Boolean; default true;
+-- treat sections found in config but not in scheme as error
 STRICT_UNKNOWN_SECTIONS    = true
+
+--- Boolean; default true;
+-- treat options found in config but not in scheme as error
 STRICT_UNKNOWN_OPTIONS     = true
+
+--- Boolean; default true;
+-- treat failed external validators as error
 STRICT_EXTERNAL_VALIDATORS = true
 
+--- Boolean; default true;
+-- treat list values stored as options like errors
+STRICT_LIST_TYPE           = true
+
 
-local default_schemedir = "/etc/scheme"
+local default_schemedir = "/lib/uci/schema"
 
 local function _assert( condition, fmt, ... )
 	if not condition then
@@ -43,6 +61,12 @@ local function _assert( condition, fmt, ... )
 	end
 end
 
+
+--- Object constructor
+-- @class			function
+-- @name			UVL
+-- @param schemedir	Path to the scheme directory (optional)
+-- @return			Instance object
 UVL = luci.util.class()
 
 function UVL.__init__( self, schemedir )
@@ -50,23 +74,104 @@ function UVL.__init__( self, schemedir )
 	self.packages	= { }
 	self.beenthere  = { }
 	self.uci		= luci.model.uci
+	self.dep		= luci.uvl.dependencies
 	self.log        = luci.uvl.loghelper
 	self.datatypes  = luci.uvl.datatypes
 end
 
 
+--- Parse given scheme and return the scheme tree.
+-- @param scheme	Name of the scheme to parse
+-- @return			Table containing the parsed scheme or nil on error
+-- @return			String containing the reason for errors (if any)
+function UVL.get_scheme( self, scheme )
+	if not self.packages[scheme] then
+		local ok, err = pcall( self.read_scheme, self, scheme )
+		if not ok then
+			return nil, self.log.scheme_error( scheme, err )
+		end
+	end
+	return self.packages[scheme], nil
+end
+
+--- Return a table containing the dependencies of specified section or option.
+-- @param config	Name of the configuration or parsed scheme object
+-- @param section	Type of the section
+-- @param option	Name of the option (optional)
+-- @return			Table containing the dependencies or nil on error
+-- @return			String containing the reason for errors (if any)
+function UVL.get_dependencies( self, config, section, option )
+	config = ( type(config) == "string" and self:get_scheme(config) or config )
+
+	local deps = { }
+	local dt
+
+	if not config.sections[section] then return deps end
+
+	if option and config.variables[section][option] then
+		dt = config.variables[section][option].depends
+	else
+		dt = config.sections[section].depends
+	end
+
+	if dt then
+		for _, d in ipairs(dt) do
+			local sdeps = { }
+			for k, v in pairs(d) do
+				local r = self.dep._parse_reference( k )
+				if r then
+					sdeps[r] = v
+				else
+					return nil,
+						'Ambiguous dependency reference "%s" for object "%s" given'
+							%{ k, self.log.id( config.name, section, option ) }
+				end
+			end
+			table.insert( deps, sdeps )
+		end
+	end
+	return deps
+end
+
+--- Validate given configuration, section or option.
+-- @param config	Name of the configuration to validate
+-- @param section	Name of the section to validate (optional)
+-- @param option	Name of the option to validate (optional)
+-- @return			Boolean indicating whether the given config validates
+-- @return			String containing the reason for errors (if any)
+function UVL.validate( self, config, section, option )
+	if config and section and option then
+		return self:validate_option( config, section, option )
+	elseif config and section then
+		return self:validate_section( config, section )
+	elseif config then
+		return self:validate_config( config )
+	end
+end
+
 --- Validate given configuration.
 -- @param config	Name of the configuration to validate
--- @param scheme	Scheme to validate against (optional)
--- @return			Boolean indicating weather the given config validates
+-- @return			Boolean indicating whether the given config validates
 -- @return			String containing the reason for errors (if any)
-function UVL.validate( self, config )
+function UVL.validate_config( self, config )
+
+	if not self.packages[config] then
+		local ok, err = pcall( self.read_scheme, self, config )
+		if not ok then
+			return false, self.log.scheme_error( config, err )
+		end
+	end
+
 	self.uci.load_config( config )
 	self.beenthere = { }
 
 	local co = self.uci.get_all( config )
 	local sc = { }
 
+	if not co then
+		return false, 'Unable to load configuration "%s"' % config
+	end
+
 	local function _uci_foreach( type, func )
 		local ok, err
 		for k, v in pairs(co) do
@@ -97,8 +202,8 @@ function UVL.validate( self, config )
 		for k, v in pairs(co) do
 			if not self.beenthere[config..'.'..k] then
 				return false, self.log.config_error( config,
-					"Section '" .. config .. '.' .. co[k]['.type'] ..
-					"' not found in scheme" )
+					'Section "%s" not found in scheme'
+						% self.log.id( config, co[k]['.type'] ) )
 			end
 		end
 	end
@@ -108,56 +213,94 @@ function UVL.validate( self, config )
 
 		if s.required and sc[k] == 0 then
 			return false, self.log.config_error( config,
-				'Required section "' .. k .. '" not found in config' )
+				'Required section "%s" not found in config' % k )
 		elseif s.unique and sc[k] > 1 then
 			return false, self.log.config_error( config,
-				'Unique section "' .. k .. '" occurs multiple times in config' )
+				'Unique section "%s" occurs multiple times in config' % k )
 		end
 	end
 
 	return true, nil
 end
 
+--- Validate given config section.
+-- @param config	Name of the configuration to validate
+-- @param section	Name of the section to validate
+-- @return			Boolean indicating whether the given config validates
+-- @return			String containing the reason for errors (if any)
 function UVL.validate_section( self, config, section )
+
+	if not self.packages[config] then
+		local ok, err = pcall( self.read_scheme, self, config )
+		if not ok then
+			return false, self.log.scheme_error( config, err )
+		end
+	end
+
 	self.uci.load_config( config )
 	self.beenthere = { }
 
 	local co = self.uci.get_all( config )
+
+	if not co then
+		return false, 'Unable to load configuration "%s"' % config
+	end
+
 	if co[section] then
 		return self:_validate_section( luci.uvl.section(
 			self, co, co[section]['.type'], config, section
 		) )
 	else
-		return false, "Section '" .. config .. '.' .. section ..
-			"' not found in config. Nothing to do."
+		return false, 'Section "%s" not found in config. Nothing to do.'
+			% self.log.id( config, section )
 	end
 end
 
+--- Validate given config option.
+-- @param config	Name of the configuration to validate
+-- @param section	Name of the section to validate
+-- @param option	Name of the option to validate
+-- @return			Boolean indicating whether the given config validates
+-- @return			String containing the reason for errors (if any)
 function UVL.validate_option( self, config, section, option )
+
+	if not self.packages[config] then
+		local ok, err = pcall( self.read_scheme, self, config )
+		if not ok then
+			return false, self.log.scheme_error( config, err )
+		end
+	end
+
 	self.uci.load_config( config )
 	self.beenthere = { }
 
 	local co = self.uci.get_all( config )
+
+	if not co then
+		return false, 'Unable to load configuration "%s"' % config
+	end
+
 	if co[section] and co[section][option] then
 		return self:_validate_option( luci.uvl.option(
 			self, co, co[section]['.type'], config, section, option
 		) )
 	else
-		return false, "Option '" ..
-			config .. '.' .. section .. '.' .. option ..
-			"' not found in config. Nothing to do."
+		return false, 'Option "%s" not found in config. Nothing to do.'
+			% self.log.id( config, section, option )
 	end
 end
 
---- Validate given section of given configuration.
--- @param config	Name of the configuration to validate
--- @param section	Key of the section to validate
--- @param scheme	Scheme to validate against
--- @return			Boolean indicating weather the given config validates
--- @return			String containing the reason for errors (if any)
+
 function UVL._validate_section( self, section )
 
 	if section:values() then
+		if section:section().named == true and
+		   section:values()['.anonymous'] == true
+		then
+			return false, self.log.section_error( section,
+				'The section of type "%s" is stored anonymously in config but must be named'
+					% section:sid() )
+		end
 
 		for _, v in ipairs(section:variables()) do
 			local ok, err = self:_validate_option( v )
@@ -173,7 +316,7 @@ function UVL._validate_section( self, section )
 			return false, err
 		end
 	else
-		print( "Error, scheme section '" .. section:sid() .. "' not found in data" )
+		return false, 'Option "%s" not found in config' % section:sid()
 	end
 
 	if STRICT_UNKNOWN_OPTIONS and not section:section().dynamic then
@@ -181,8 +324,8 @@ function UVL._validate_section( self, section )
 			if k:sub(1,1) ~= "." and not self.beenthere[
 				section:cid() .. '.' .. k
 			] then
-				return false, "Option '" .. section:sid() .. '.' .. k ..
-					"' not found in scheme"
+				return false, 'Option "%s" not found in scheme'
+					% self.log.id( section:sid(), k )
 			end
 		end
 	end
@@ -190,53 +333,49 @@ function UVL._validate_section( self, section )
 	return true, nil
 end
 
---- Validate given option within section of given configuration.
--- @param config	Name of the configuration to validate
--- @param section	Key of the section to validate
--- @param option	Name of the option to validate
--- @param scheme	Scheme to validate against
--- @return			Boolean indicating weather the given config validates
--- @return			String containing the reason for errors (if any)
 function UVL._validate_option( self, option, nodeps )
 
-	if not option:option() and
-	   not ( option:section() and option:section().dynamic )
-	then
-		return false, "Option '" .. option:cid() ..
-			"' not found in scheme"
-	end
+	local item = option:option()
+	local val  = option:value()
 
-	if option:option() then
-		if option:option().required and not option:value() then
-			return false, "Mandatory variable '" .. option:cid() ..
-				"' doesn't have a value"
+	if not item and not ( option:section() and option:section().dynamic ) then
+		return false, 'Option "%s" not found in scheme' % option:cid()
+
+	elseif item then
+		if item.required and not val then
+			return false, 'Mandatory variable "%s" does not have a value'
+				% option:cid()
 		end
 
-		if option:option().type == "enum" and option:value() then
-			if not option:option().values or
-			   not option:option().values[option:value()]
-			then
-				return false, "Value '" .. ( option:value() or '<nil>' ) ..
-					"' of given option '" .. option:cid() ..
-					"' is not defined in enum { " ..
-					table.concat(luci.util.keys(option:option().values),", ") ..
-					" }"
+		if ( item.type == "reference" or item.type == "enum" ) and val then
+			if not item.values or not item.values[val] then
+				return false,
+					'Value "%s" of given option "%s" is not defined in %s { %s }'
+						%{ val or '<nil>', option:cid(), item.type,
+						   table.concat( luci.util.keys(item.values), ", " ) }
+			end
+		elseif item.type == "list" and val then
+			if type(val) ~= "table" and STRICT_LIST_TYPE then
+				return false,
+					'Option "%s" is defined as list but stored as plain value'
+						% option:cid()
 			end
 		end
 
-		if option:option().datatype and option:value() then
-			if self.datatypes[option:option().datatype] then
-				if not self.datatypes[option:option().datatype](
-					option:value()
-				) then
-					return false, "Value '" .. ( option:value() or '<nil>' ) ..
-						"' of given option '" .. option:cid() ..
-						"' doesn't validate as datatype '" ..
-						option:option().datatype .. "'"
+		if item.datatype and val then
+			if self.datatypes[item.datatype] then
+				val = ( type(val) == "table" and val or { val } )
+				for i, v in ipairs(val) do
+					if not self.datatypes[item.datatype]( v ) then
+						return false,
+							'Value%s "%s" of given option "%s" does not validate as datatype "%s"'
+								%{ ( #val>1 and ' #' .. i or '' ), v,
+								   option:cid(), item.datatype }
+					end
 				end
 			else
-				return false, "Unknown datatype '" ..
-					option:option().datatype .. "' encountered"
+				return false, 'Unknown datatype "%s" encountered'
+					% item.datatype
 			end
 		end
 
@@ -253,22 +392,28 @@ function UVL._validate_option( self, option, nodeps )
 	return true, nil
 end
 
---- Find all parts of given scheme and construct validation tree
+--- Find all parts of given scheme and construct validation tree.
+-- This is normally done on demand, so you don't have to call this function
+-- by yourself.
 -- @param scheme	Name of the scheme to parse
--- @return			Parsed scheme
 function UVL.read_scheme( self, scheme )
 	local schemes = { }
+	local files = luci.fs.glob(self.schemedir .. '/*/' .. scheme)
 
-	for i, file in ipairs( luci.fs.glob(self.schemedir .. '/*/' .. scheme) ) do
-		_assert( luci.fs.access(file), "Can't access file '%s'", file )
+	if files then
+		for i, file in ipairs( files ) do
+			_assert( luci.fs.access(file), "Can't access file '%s'", file )
 
-		self.uci.set_confdir( luci.fs.dirname(file) )
-		self.uci.load( luci.fs.basename(file) )
+			self.uci.set_confdir( luci.fs.dirname(file) )
+			self.uci.load( luci.fs.basename(file) )
 
-		table.insert( schemes, self.uci.get_all( luci.fs.basename(file) ) )
-	end
+			table.insert( schemes, self.uci.get_all( luci.fs.basename(file) ) )
+		end
 
-	return self:_read_scheme_parts( scheme, schemes )
+		return self:_read_scheme_parts( scheme, schemes )
+	else
+		error( 'Can not find scheme "%s" in "%s"' %{ scheme, self.schemedir } )
+	end
 end
 
 -- Process all given parts and construct validation tree
@@ -278,15 +423,15 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 	local function _id( c, t )
 		if c == TYPE_SECTION then
 			return string.format(
-				"section '%s.%s'",
+				'section "%s.%s"',
 					scheme, t.name or '?' )
 		elseif c == TYPE_VARIABLE then
 			return string.format(
-				"variable '%s.%s.%s'",
+				'variable "%s.%s.%s"',
 					scheme, t.section or '?.?', t.name or '?' )
 		elseif c == TYPE_ENUM then
 			return string.format(
-				"enum '%s.%s.%s'",
+				'enum "%s.%s.%s"',
 					scheme, t.variable or '?.?.?', t.value or '?' )
 		end
 	end
@@ -294,7 +439,7 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 	-- helper function to check for required fields
 	local function _req( c, t, r )
 		for i, v in ipairs(r) do
-			_assert( t[v], "Missing required field '%s' in %s", v, _id(c, t) )
+			_assert( t[v], 'Missing required field "%s" in %s', v, _id(c, t) )
 		end
 	end
 
@@ -312,7 +457,7 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 		local r = luci.util.split( t[k], "." )
 		r[1] = ( #r[1] > 0 and r[1] or scheme )
 
-		_assert( #r == c, "Malformed %s reference in %s", k, _id(c, t) )
+		_assert( #r == c, 'Malformed %s reference in %s', k, _id(c, t) )
 
 		return r
 	end
@@ -333,6 +478,7 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 
 				self.packages[r[1]] =
 					self.packages[r[1]] or {
+						["name"]      = r[1];
 						["sections"]  = { };
 						["variables"] = { };
 					}
@@ -345,14 +491,16 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 
 				for k, v2 in pairs(v) do
 					if k ~= "name" and k ~= "package" and k:sub(1,1) ~= "." then
-						if k:match("^depends") then
+						if k == "depends" then
 							s["depends"] = _assert(
 								self:_read_dependency( v2, s["depends"] ),
-								"Section '%s' in scheme '%s' has malformed " ..
-								"dependency specification in '%s'",
+								'Section "%s" in scheme "%s" has malformed ' ..
+								'dependency specification in "%s"',
 								v.name or '<nil>', scheme or '<nil>', k
 							)
-						elseif k == "dynamic" or k == "unique" or k == "required" then
+						elseif k == "dynamic" or k == "unique" or
+						       k == "required" or k == "named"
+						then
 							s[k] = _bool(v2)
 						else
 							s[k] = v2
@@ -363,6 +511,7 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 				s.dynamic  = s.dynamic  or false
 				s.unique   = s.unique   or false
 				s.required = s.required or false
+				s.named    = s.named    or false
 			end
 		end
 	end
@@ -377,11 +526,11 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 				local r = _ref( TYPE_VARIABLE, v )
 
 				local p = _assert( self.packages[r[1]],
-					"Variable '%s' in scheme '%s' references unknown package '%s'",
+					'Variable "%s" in scheme "%s" references unknown package "%s"',
 					v.name, scheme, r[1] )
 
 				local s = _assert( p.variables[r[2]],
-					"Variable '%s' in scheme '%s' references unknown section '%s'",
+					'Variable "%s" in scheme "%s" references unknown section "%s"',
 					v.name, scheme, r[2] )
 
 				s[v.name] = s[v.name] or { }
@@ -390,23 +539,33 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 
 				for k, v2 in pairs(v) do
 					if k ~= "name" and k ~= "section" and k:sub(1,1) ~= "." then
-						if k:match("^depends") then
+						if k == "depends" then
 							t["depends"] = _assert(
 								self:_read_dependency( v2, t["depends"] ),
 								'Invalid reference "%s" in "%s.%s.%s"',
 								v2, v.name, scheme, k
 							)
-						elseif k:match("^validator") then
+						elseif k == "validator" then
 							t["validators"] = _assert(
 								self:_read_validator( v2, t["validators"] ),
-								"Variable '%s' in scheme '%s' has malformed " ..
-								"validator specification in '%s'",
+								'Variable "%s" in scheme "%s" has malformed ' ..
+								'validator specification in "%s"',
 								v.name, scheme, k
 							)
+						elseif k == "valueof" then
+							local values, err = self:_read_reference( v2 )
+
+							_assert( values,
+								'Variable "%s" in scheme "%s" has invalid ' ..
+								'reference specification:\n%s',
+									v.name, scheme, err )
+
+							t.type   = "reference"
+							t.values = values
 						elseif k == "required" then
 							t[k] = _bool(v2)
 						else
-							t[k] = v2
+							t[k] = t[k] or v2
 						end
 					end
 				end
@@ -426,23 +585,22 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 				_req( TYPE_ENUM, v, { "value", "variable" } )
 
 				local r = _ref( TYPE_ENUM, v )
-
 				local p = _assert( self.packages[r[1]],
-					"Enum '%s' in scheme '%s' references unknown package '%s'",
+					'Enum "%s" in scheme "%s" references unknown package "%s"',
 					v.value, scheme, r[1] )
 
 				local s = _assert( p.variables[r[2]],
-					"Enum '%s' in scheme '%s' references unknown section '%s'",
+					'Enum "%s" in scheme "%s" references unknown section "%s"',
 					v.value, scheme, r[2] )
 
 				local t = _assert( s[r[3]],
-					"Enum '%s' in scheme '%s', section '%s' references " ..
-					"unknown variable '%s'",
+					'Enum "%s" in scheme "%s", section "%s" references ' ..
+					'unknown variable "%s"',
 					v.value, scheme, r[2], r[3] )
 
 				_assert( t.type == "enum",
-					"Enum '%s' in scheme '%s', section '%s' references " ..
-					"variable '%s' with non enum type '%s'",
+					'Enum "%s" in scheme "%s", section "%s" references ' ..
+					'variable "%s" with non enum type "%s"',
 					v.value, scheme, r[2], r[3], t.type )
 
 				if not t.values then
@@ -453,8 +611,8 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 
 				if v.default then
 					_assert( not t.default,
-						"Enum '%s' in scheme '%s', section '%s' redeclares " ..
-						"the default value of variable '%s'",
+						'Enum "%s" in scheme "%s", section "%s" redeclares ' ..
+						'the default value of variable "%s"',
 						v.value, scheme, r[2], v.variable )
 
 					t.default = v.value
@@ -467,54 +625,102 @@ function UVL._read_scheme_parts( self, scheme, schemes )
 end
 
 -- Read a dependency specification
-function UVL._read_dependency( self, value, deps )
-	local parts     = luci.util.split( value, "%s*,%s*", nil, true )
-	local condition = { }
-
-	for i, val in ipairs(parts) do
-		local k, v = unpack(luci.util.split( val, "%s*=%s*", nil, true ))
-
-		if k and (
-			k:match("^%$?[a-zA-Z0-9_]+%.%$?[a-zA-Z0-9_]+%.%$?[a-zA-Z0-9_]+$") or
-			k:match("^%$?[a-zA-Z0-9_]+%.%$?[a-zA-Z0-9_]+$") or
-			k:match("^%$?[a-zA-Z0-9_]+$")
-		) then
-			condition[k] = v or true
-		else
-			return nil
-		end
-	end
+function UVL._read_dependency( self, values, deps )
+	local expr = "%$?[a-zA-Z0-9_]+"
+	if values then
+		values = ( type(values) == "table" and values or { values } )
+		for _, value in ipairs(values) do
+			local parts     = luci.util.split( value, "%s*,%s*", nil, true )
+			local condition = { }
+			for i, val in ipairs(parts) do
+				local k, v = unpack(luci.util.split(val, "%s*=%s*", nil, true))
+
+				if k and (
+					k:match("^"..expr.."%."..expr.."%."..expr.."$") or
+					k:match("^"..expr.."%."..expr.."$") or
+					k:match("^"..expr.."$")
+				) then
+					condition[k] = v or true
+				else
+					return nil
+				end
+			end
 
-	if not deps then
-		deps = { condition }
-	else
-		table.insert( deps, condition )
+			if not deps then
+				deps = { condition }
+			else
+				table.insert( deps, condition )
+			end
+		end
 	end
 
 	return deps
 end
 
 -- Read a validator specification
-function UVL._read_validator( self, value, validators )
-	if value then
-		local validator
-
-		if value:match("^exec:") then
-			validator = value:gsub("^exec:","")
-		elseif value:match("^lua:") then
-			validator = self:_resolve_function( (value:gsub("^lua:","") ) )
-		end
+function UVL._read_validator( self, values, validators )
+	if values then
+		values = ( type(values) == "table" and values or { values } )
+		for _, value in ipairs(values) do
+			local validator
+
+			if value:match("^exec:") then
+				validator = value:gsub("^exec:","")
+			elseif value:match("^lua:") then
+				validator = self:_resolve_function( (value:gsub("^lua:","") ) )
+			end
 
-		if validator then
-			if not validators then
-				validators = { validator }
+			if validator then
+				if not validators then
+					validators = { validator }
+				else
+					table.insert( validators, validator )
+				end
 			else
-				table.insert( validators, validator )
+				return nil
 			end
+		end
 
-			return validators
+		return validators
+	end
+end
+
+-- Read a reference specification (XXX: We should validate external configs too...)
+function UVL._read_reference( self, values )
+	local val = { }
+	values = ( type(values) == "table" and values or { values } )
+
+	for _, value in ipairs(values) do
+		local ref = luci.util.split(value, ".")
+
+		if #ref == 2 or #ref == 3 then
+			self.uci.load_config(ref[1])
+			local co = self.uci.get_all(ref[1])
+
+			if not co then
+				return nil, 'Can not load config "%s" for reference "%s"'
+					%{ ref[1], value }
+			end
+
+			for k, v in pairs(co) do
+				if v['.type'] == ref[2] then
+					if #ref == 2 then
+						if v['.anonymous'] == true then
+							return nil, 'Illegal reference "%s" to an anonymous section'
+								% value
+						end
+						table.insert( val, k )
+					elseif v[ref[3]] then
+						table.insert( val, v[ref[3]] )
+					end
+				end
+			end
+		else
+			return nil, 'Malformed reference "%s"' % value
 		end
 	end
+
+	return val, nil
 end
 
 -- Resolve given path
@@ -542,6 +748,20 @@ function UVL._resolve_function( self, value )
 end
 
 
+--- Object representation of a scheme/config section.
+-- @class	module
+-- @cstyle	instance
+-- @name	luci.uvl.section
+
+--- Section instance constructor.
+-- @class			function
+-- @name			section
+-- @param scheme	Scheme instance
+-- @param co		Configuration data
+-- @param st		Section type
+-- @param c			Configuration name
+-- @param s			Section name
+-- @return			Section instance
 section = luci.util.class()
 
 function section.__init__(self, scheme, co, st, c, s)
@@ -554,22 +774,32 @@ function section.__init__(self, scheme, co, st, c, s)
 	self.type     = luci.uvl.TYPE_SECTION
 end
 
+--- Get the config path of this section.
+-- @return	String containing the identifier
 function section.cid(self)
 	return ( self.cref[1] or '?' ) .. '.' .. ( self.cref[2] or '?' )
 end
 
+--- Get the scheme path of this section.
+-- @return	String containing the identifier
 function section.sid(self)
 	return ( self.sref[1] or '?' ) .. '.' .. ( self.sref[2] or '?' )
 end
 
+--- Get all configuration values within this section.
+-- @return	Table containing the values
 function section.values(self)
 	return self.csection
 end
 
+--- Get the associated section information in scheme.
+-- @return	Table containing the scheme properties
 function section.section(self)
 	return self.ssection
 end
 
+--- Get all option objects associated with this section.
+-- @return	Table containing all associated luci.uvl.option instances
 function section.variables(self)
 	local v = { }
 	if self.scheme.packages[self.sref[1]].variables[self.sref[2]] then
@@ -586,6 +816,21 @@ function section.variables(self)
 end
 
 
+--- Object representation of a scheme/config option.
+-- @class	module
+-- @cstyle	instance
+-- @name	luci.uvl.option
+
+--- Section instance constructor.
+-- @class			function
+-- @name			option
+-- @param scheme	Scheme instance
+-- @param co		Configuration data
+-- @param st		Section type
+-- @param c			Configuration name
+-- @param s			Section name
+-- @param o			Option name
+-- @return			Option instance
 option = luci.util.class()
 
 function option.__init__(self, scheme, co, st, c, s, o)
@@ -598,26 +843,36 @@ function option.__init__(self, scheme, co, st, c, s, o)
 	self.type    = luci.uvl.TYPE_OPTION
 end
 
+--- Get the config path of this option.
+-- @return	String containing the identifier
 function option.cid(self)
 	return ( self.cref[1] or '?' ) .. '.' ..
 		   ( self.cref[2] or '?' ) .. '.' ..
 		   ( self.cref[3] or '?' )
 end
 
+--- Get the scheme path of this option.
+-- @return	String containing the identifier
 function option.sid(self)
 	return ( self.sref[1] or '?' ) .. '.' ..
 		   ( self.sref[2] or '?' ) .. '.' ..
 		   ( self.sref[3] or '?' )
 end
 
+--- Get the value of this option.
+-- @return	The associated configuration value
 function option.value(self)
 	return self.coption
 end
 
+--- Get the associated option information in scheme.
+-- @return	Table containing the scheme properties
 function option.option(self)
 	return self.soption
 end
 
+--- Get the associated section information in scheme.
+-- @return	Table containing the scheme properties
 function option.section(self)
 	return self.scheme.packages[self.sref[1]].sections[self.sref[2]]
 end