Module ucl

This lua module allows to parse objects from strings and to store data into ucl objects. It uses libucl C library to parse and manipulate with ucl objects.

Example:

local ucl = require("ucl")

local parser = ucl.parser()
local res,err = parser:parse_string('{key=value}')

if not res then
	print('parser error: ' .. err)
else
	local obj = parser:get_object()
	local got = ucl.to_format(obj, 'json')
endif

local table = {
  str = 'value',
  num = 100500,
  null = ucl.null,
  func = function ()
    return 'huh'
  end


print(ucl.to_format(table, 'ucl'))
-- Output:
--[[
num = 100500;
str = "value";
null = null;
func = "huh";
--]]

Brief content:

Functions:

ucl_object_push_lua(L, obj, allow_array)

ucl.to_format(var, format)

Methods:

parser:parse_file(name)

parser:register_variable(name, value)

parser:register_variables(vars)

parser:parse_string(input)

parser:get_object()

parser:get_object_wrapped()

parser:validate(schema)

object:unwrap()

object:tostring(type)

object:validate(schema[, path[, ext_refs]])

Functions

The module ucl defines the following functions.

Function ucl_object_push_lua(L, obj, allow_array)

This is a C function to push UCL object as lua variable. This function converts obj to lua representation using the following conversions:

• scalar values are directly presented by lua objects
• userdata values are converted to lua function objects using LUA_REGISTRYINDEX, this can be used to pass functions from lua to c and vice-versa
• arrays are converted to lua tables with numeric indicies suitable for ipairs iterations
• objects are converted to lua tables with string indicies

Parameters:

• L {lua_State}: lua state pointer
• obj {ucl_object_t}: object to push
• allow_array {bool}: expand implicit arrays (should be true for all but partial arrays)

Returns:

• {int}: 1 if an object is pushed to lua

Back to module description.

Function ucl.to_format(var, format)

Converts lua variable var to the specified format. Formats supported are:

• json - fine printed json
• json-compact - compacted json
• config - fine printed configuration
• ucl - same as config
• yaml - embedded yaml

If var contains function, they are called during output formatting and if they return string value, then this value is used for output.

Parameters:

• var {variant}: any sort of lua variable (if userdata then metafield __to_ucl is searched for output)
• format {string}: any available format

Returns:

• {string}: string representation of var in the specific format.

Example:

local table = {
  str = 'value',
  num = 100500,
  null = ucl.null,
  func = function ()
    return 'huh'
  end


print(ucl.to_format(table, 'ucl'))
-- Output:
--[[
num = 100500;
str = "value";
null = null;
func = "huh";
--]]

Back to module description.

Methods

The module ucl defines the following methods.

Method parser:parse_file(name)

Parse UCL object from file.

Parameters:

• name {string}: filename to parse

Returns:

• {bool[, string]}: if res is true then file has been parsed successfully, otherwise an error string is also returned

Example:

local parser = ucl.parser()
local res,err = parser:parse_file('/some/file.conf')

if not res then
	print('parser error: ' .. err)
else
	-- Do something with object
end

Back to module description.

Method parser:register_variable(name, value)

Register parser variable

Parameters:

• name {string}: name of variable
• value {string}: value of variable

Returns:

• {bool}: success

Example:

local parser = ucl.parser()
local res = parser:register_variable('CONFDIR', '/etc/foo')

Back to module description.

Method parser:register_variables(vars)

Register parser variables

Parameters:

• vars {table}: names/values of variables

Returns:

• {bool}: success

Example:

local parser = ucl.parser()
local res = parser:register_variables({CONFDIR = '/etc/foo', VARDIR = '/var'})

Back to module description.

Method parser:parse_string(input)

Parse UCL object from file.

Parameters:

• input {string}: string to parse

Returns:

• {bool[, string]}: if res is true then file has been parsed successfully, otherwise an error string is also returned

Back to module description.

Method parser:get_object()

Get top object from parser and export it to lua representation.

Parameters:

No parameters

Returns:

• {variant or nil}: ucl object as lua native variable

Back to module description.

Method parser:get_object_wrapped()

Get top object from parser and export it to userdata object without unwrapping to lua.

Parameters:

No parameters

Returns:

• {ucl.object or nil}: ucl object wrapped variable

Back to module description.

Method parser:validate(schema)

Validates the top object in the parser against schema. Schema might be another object or a string that represents file to load schema from.

Parameters:

• schema {string/table}: input schema

Returns:

• {result,err}: two values: boolean result and the corresponding error

Back to module description.

Method object:unwrap()

Unwraps opaque ucl object to the native lua object (performing copying)

Parameters:

No parameters

Returns:

• {variant}: any lua object

Back to module description.

Method object:tostring(type)

Unwraps opaque ucl object to string (json by default). Optionally you can specify output format:

• json - fine printed json
• json-compact - compacted json
• config - fine printed configuration
• ucl - same as config
• yaml - embedded yaml

Parameters:

• type {string}: optional

Returns:

• {string}: string representation of the opaque ucl object

Back to module description.

Method object:validate(schema[, path[, ext_refs]])

Validates the given ucl object using schema object represented as another opaque ucl object. You can also specify path in the form #/path/def to specify the specific schema element to perform validation.

error, if ext_refs are also specified, then they are returned as opaque ucl object as {result,err,ext_refs}

Parameters:

• schema {ucl.object}: schema object
• path {string}: optional path for validation procedure

Returns:

• {result,err}: two values: boolean result and the corresponding

Back to module description.

Back to top.