1## Module `ucl` 2 3This lua module allows to parse objects from strings and to store data into 4ucl objects. It uses `libucl` C library to parse and manipulate with ucl objects. 5 6Example: 7 8~~~lua 9local ucl = require("ucl") 10 11local parser = ucl.parser() 12local res,err = parser:parse_string('{key=value}') 13 14if not res then 15 print('parser error: ' .. err) 16else 17 local obj = parser:get_object() 18 local got = ucl.to_format(obj, 'json') 19end 20 21local table = { 22 str = 'value', 23 num = 100500, 24 null = ucl.null, 25 func = function () 26 return 'huh' 27 end 28} 29 30 31print(ucl.to_format(table, 'ucl')) 32-- Output: 33--[[ 34num = 100500; 35str = "value"; 36null = null; 37func = "huh"; 38--]] 39~~~ 40 41###Brief content: 42 43**Functions**: 44 45> [`ucl_object_push_lua(L, obj, allow_array)`](#function-ucl_object_push_lual-obj-allow_array) 46 47> [`ucl.to_format(var, format)`](#function-uclto_formatvar-format) 48 49 50 51**Methods**: 52 53> [`parser:parse_file(name)`](#method-parserparse_filename) 54 55> [`parser:parse_string(input)`](#method-parserparse_stringinput) 56 57> [`parser:get_object()`](#method-parserget_object) 58 59 60## Functions 61 62The module `ucl` defines the following functions. 63 64### Function `ucl_object_push_lua(L, obj, allow_array)` 65 66This is a `C` function to push `UCL` object as lua variable. This function 67converts `obj` to lua representation using the following conversions: 68 69- *scalar* values are directly presented by lua objects 70- *userdata* values are converted to lua function objects using `LUA_REGISTRYINDEX`, 71this can be used to pass functions from lua to c and vice-versa 72- *arrays* are converted to lua tables with numeric indices suitable for `ipairs` iterations 73- *objects* are converted to lua tables with string indices 74 75**Parameters:** 76 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) 80 81**Returns:** 82 83- `{int}`: `1` if an object is pushed to lua 84 85Back to [module description](#module-ucl). 86 87### Function `ucl.to_format(var, format)` 88 89Converts lua variable `var` to the specified `format`. Formats supported are: 90 91- `json` - fine printed json 92- `json-compact` - compacted json 93- `config` - fine printed configuration 94- `ucl` - same as `config` 95- `yaml` - embedded yaml 96 97If `var` contains function, they are called during output formatting and if 98they return string value, then this value is used for ouptut. 99 100**Parameters:** 101 102- `var {variant}`: any sort of lua variable (if userdata then metafield `__to_ucl` is searched for output) 103- `format {string}`: any available format 104 105**Returns:** 106 107- `{string}`: string representation of `var` in the specific `format`. 108 109Example: 110 111~~~lua 112local table = { 113 str = 'value', 114 num = 100500, 115 null = ucl.null, 116 func = function () 117 return 'huh' 118 end 119} 120 121 122print(ucl.to_format(table, 'ucl')) 123-- Output: 124--[[ 125num = 100500; 126str = "value"; 127null = null; 128func = "huh"; 129--]] 130~~~ 131 132Back to [module description](#module-ucl). 133 134 135## Methods 136 137The module `ucl` defines the following methods. 138 139### Method `parser:parse_file(name)` 140 141Parse UCL object from file. 142 143**Parameters:** 144 145- `name {string}`: filename to parse 146 147**Returns:** 148 149- `{bool[, string]}`: if res is `true` then file has been parsed successfully, otherwise an error string is also returned 150 151Example: 152 153~~~lua 154local parser = ucl.parser() 155local res,err = parser:parse_file('/some/file.conf') 156 157if not res then 158 print('parser error: ' .. err) 159else 160 -- Do something with object 161end 162~~~ 163 164Back to [module description](#module-ucl). 165 166### Method `parser:parse_string(input)` 167 168Parse UCL object from file. 169 170**Parameters:** 171 172- `input {string}`: string to parse 173 174**Returns:** 175 176- `{bool[, string]}`: if res is `true` then file has been parsed successfully, otherwise an error string is also returned 177 178Back to [module description](#module-ucl). 179 180### Method `parser:get_object()` 181 182Get top object from parser and export it to lua representation. 183 184**Parameters:** 185 186 nothing 187 188**Returns:** 189 190- `{variant or nil}`: ucl object as lua native variable 191 192Back to [module description](#module-ucl). 193 194 195Back to [top](#). 196 197