contrib/libucl/doc/lua_api.md

   1 ## Module `ucl`
   2
   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.
   5
   6 Example:
   7
   8 ~~~lua
   9 local ucl = require("ucl")
  10
  11 local parser = ucl.parser()
  12 local res,err = parser:parse_string('{key=value}')
  13
  14 if not res then
  15         print('parser error: ' .. err)
  16 else
  17         local obj = parser:get_object()
  18         local got = ucl.to_format(obj, 'json')
  19 end
  20
  21 local table = {
  22   str = 'value',
  23   num = 100500,
  24   null = ucl.null,
  25   func = function ()
  26     return 'huh'
  27   end
  28 }
  29
  30
  31 print(ucl.to_format(table, 'ucl'))
  32 -- Output:
  33 --[[
  34 num = 100500;
  35 str = "value";
  36 null = null;
  37 func = "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
  62 The module `ucl` defines the following functions.
  63
  64 ### Function `ucl_object_push_lua(L, obj, allow_array)`
  65
  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:
  68
  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
  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
  85 Back to [module description](#module-ucl).
  86
  87 ### Function `ucl.to_format(var, format)`
  88
  89 Converts 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
  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.
  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
 109 Example:
 110
 111 ~~~lua
 112 local table = {
 113   str = 'value',
 114   num = 100500,
 115   null = ucl.null,
 116   func = function ()
 117     return 'huh'
 118   end
 119 }
 120
 121
 122 print(ucl.to_format(table, 'ucl'))
 123 -- Output:
 124 --[[
 125 num = 100500;
 126 str = "value";
 127 null = null;
 128 func = "huh";
 129 --]]
 130 ~~~
 131
 132 Back to [module description](#module-ucl).
 133
 134
 135 ## Methods
 136
 137 The module `ucl` defines the following methods.
 138
 139 ### Method `parser:parse_file(name)`
 140
 141 Parse 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
 151 Example:
 152
 153 ~~~lua
 154 local parser = ucl.parser()
 155 local res,err = parser:parse_file('/some/file.conf')
 156
 157 if not res then
 158         print('parser error: ' .. err)
 159 else
 160         -- Do something with object
 161 end
 162 ~~~
 163
 164 Back to [module description](#module-ucl).
 165
 166 ### Method `parser:parse_string(input)`
 167
 168 Parse 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
 178 Back to [module description](#module-ucl).
 179
 180 ### Method `parser:get_object()`
 181
 182 Get 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
 192 Back to [module description](#module-ucl).
 193
 194
 195 Back to [top](#).
 196