3 This lua module allows to parse objects from strings and to store data into
4 ucl objects. It uses `libucl` C library to parse and manipulate with ucl objects.
9 local ucl = require("ucl")
11 local parser = ucl.parser()
12 local res,err = parser:parse_string('{key=value}')
15 print('parser error: ' .. err)
17 local obj = parser:get_object()
18 local got = ucl.to_format(obj, 'json')
31 print(ucl.to_format(table, 'ucl'))
45 > [`ucl_object_push_lua(L, obj, allow_array)`](#function-ucl_object_push_lual-obj-allow_array)
47 > [`ucl.to_format(var, format)`](#function-uclto_formatvar-format)
53 > [`parser:parse_file(name)`](#method-parserparse_filename)
55 > [`parser:parse_string(input)`](#method-parserparse_stringinput)
57 > [`parser:get_object()`](#method-parserget_object)
62 The module `ucl` defines the following functions.
64 ### Function `ucl_object_push_lua(L, obj, allow_array)`
66 This is a `C` function to push `UCL` object as lua variable. This function
67 converts `obj` to lua representation using the following conversions:
69 - *scalar* values are directly presented by lua objects
70 - *userdata* values are converted to lua function objects using `LUA_REGISTRYINDEX`,
71 this can be used to pass functions from lua to c and vice-versa
72 - *arrays* are converted to lua tables with numeric indicies suitable for `ipairs` iterations
73 - *objects* are converted to lua tables with string indicies
77 - `L {lua_State}`: lua state pointer
78 - `obj {ucl_object_t}`: object to push
79 - `allow_array {bool}`: expand implicit arrays (should be true for all but partial arrays)
83 - `{int}`: `1` if an object is pushed to lua
85 Back to [module description](#module-ucl).
87 ### Function `ucl.to_format(var, format)`
89 Converts lua variable `var` to the specified `format`. Formats supported are:
91 - `json` - fine printed json
92 - `json-compact` - compacted json
93 - `config` - fine printed configuration
94 - `ucl` - same as `config`
95 - `yaml` - embedded yaml
97 If `var` contains function, they are called during output formatting and if
98 they return string value, then this value is used for ouptut.
102 - `var {variant}`: any sort of lua variable (if userdata then metafield `__to_ucl` is searched for output)
103 - `format {string}`: any available format
107 - `{string}`: string representation of `var` in the specific `format`.
122 print(ucl.to_format(table, 'ucl'))
132 Back to [module description](#module-ucl).
137 The module `ucl` defines the following methods.
139 ### Method `parser:parse_file(name)`
141 Parse UCL object from file.
145 - `name {string}`: filename to parse
149 - `{bool[, string]}`: if res is `true` then file has been parsed successfully, otherwise an error string is also returned
154 local parser = ucl.parser()
155 local res,err = parser:parse_file('/some/file.conf')
158 print('parser error: ' .. err)
160 -- Do something with object
164 Back to [module description](#module-ucl).
166 ### Method `parser:parse_string(input)`
168 Parse UCL object from file.
172 - `input {string}`: string to parse
176 - `{bool[, string]}`: if res is `true` then file has been parsed successfully, otherwise an error string is also returned
178 Back to [module description](#module-ucl).
180 ### Method `parser:get_object()`
182 Get top object from parser and export it to lua representation.
190 - `{variant or nil}`: ucl object as lua native variable
192 Back to [module description](#module-ucl).