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 endif
  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 print(ucl.to_format(table, 'ucl'))
  31 -- Output:
  32 --[[
  33 num = 100500;
  34 str = "value";
  35 null = null;
  36 func = "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
  61 The module `ucl` defines the following functions.
  62
  63 ### Function `ucl_object_push_lua(L, obj, allow_array)`
  64
  65 This is a `C` function to push `UCL` object as lua variable. This function
  66 converts `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`,
  70 this 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
  84 Back to [module description](#module-ucl).
  85
  86 ### Function `ucl.to_format(var, format)`
  87
  88 Converts 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
  96 If `var` contains function, they are called during output formatting and if
  97 they 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
 108 Example:
 109
 110 ~~~lua
 111 local table = {
 112   str = 'value',
 113   num = 100500,
 114   null = ucl.null,
 115   func = function ()
 116     return 'huh'
 117   end
 118
 119
 120 print(ucl.to_format(table, 'ucl'))
 121 -- Output:
 122 --[[
 123 num = 100500;
 124 str = "value";
 125 null = null;
 126 func = "huh";
 127 --]]
 128 ~~~
 129
 130 Back to [module description](#module-ucl).
 131
 132
 133 ## Methods
 134
 135 The module `ucl` defines the following methods.
 136
 137 ### Method `parser:parse_file(name)`
 138
 139 Parse 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
 149 Example:
 150
 151 ~~~lua
 152 local parser = ucl.parser()
 153 local res,err = parser:parse_file('/some/file.conf')
 154
 155 if not res then
 156         print('parser error: ' .. err)
 157 else
 158         -- Do something with object
 159 end
 160 ~~~
 161
 162 Back to [module description](#module-ucl).
 163
 164 ### Method `parser:parse_string(input)`
 165
 166 Parse 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
 176 Back to [module description](#module-ucl).
 177
 178 ### Method `parser:get_object()`
 179
 180 Get 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
 190 Back to [module description](#module-ucl).
 191
 192
 193 Back to [top](#).
 194