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