diff options
Diffstat (limited to 'contrib/libucl/doc/libucl.3')
| -rw-r--r-- | contrib/libucl/doc/libucl.3 | 155 |
1 files changed, 79 insertions, 76 deletions
diff --git a/contrib/libucl/doc/libucl.3 b/contrib/libucl/doc/libucl.3 index 0d4fb60..a185d1a 100644 --- a/contrib/libucl/doc/libucl.3 +++ b/contrib/libucl/doc/libucl.3 @@ -6,11 +6,11 @@ \f[B]ucl_parser_add_string\f[], \f[B]ucl_parser_add_file\f[], \f[B]ucl_parser_get_object\f[], \f[B]ucl_parser_get_error\f[], \f[B]ucl_parser_free\f[], \f[B]ucl_pubkey_add\f[], -\f[B]ucl_parser_set_filevars\f[] - universal configuration library +\f[B]ucl_parser_set_filevars\f[] \- universal configuration library parser and utility functions .SH LIBRARY .PP -UCL library (libucl, -lucl) +UCL library (libucl, \-lucl) .SH SYNOPSIS .PP \f[C]#include\ <ucl.h>\f[] @@ -32,12 +32,12 @@ In future, this limitation can be removed. Convert \f[C]ucl\f[] objects to some textual or binary representation. Currently, libucl supports the following exports: .IP \[bu] 2 -\f[C]JSON\f[] - valid json format (can possibly loose some original +\f[C]JSON\f[] \- valid json format (can possibly loose some original data, such as implicit arrays) .IP \[bu] 2 -\f[C]Config\f[] - human-readable configuration format (losseless) +\f[C]Config\f[] \- human\-readable configuration format (losseless) .IP \[bu] 2 -\f[C]YAML\f[] - embedded yaml format (has the same limitations as +\f[C]YAML\f[] \- embedded yaml format (has the same limitations as \f[C]json\f[] output) .SS Conversion functions .PP @@ -57,7 +57,7 @@ as implicit array or implicit consolidation). .SS Validation functions .PP Validation functions are used to validate some object \f[C]obj\f[] using -json-schema compatible object \f[C]schema\f[]. +json\-schema compatible object \f[C]schema\f[]. Both input and schema must be UCL objects to perform validation. .SS Utility functions .PP @@ -76,13 +76,13 @@ struct\ ucl_parser*\ ucl_parser_new\ (int\ flags); .PP Creates new parser with the specified flags: .IP \[bu] 2 -\f[C]UCL_PARSER_KEY_LOWERCASE\f[] - lowercase keys parsed +\f[C]UCL_PARSER_KEY_LOWERCASE\f[] \- lowercase keys parsed .IP \[bu] 2 -\f[C]UCL_PARSER_ZEROCOPY\f[] - try to use zero-copy mode when reading -files (in zero-copy mode text chunk being parsed without copying strings -so it should exist till any object parsed is used) +\f[C]UCL_PARSER_ZEROCOPY\f[] \- try to use zero\-copy mode when reading +files (in zero\-copy mode text chunk being parsed without copying +strings so it should exist till any object parsed is used) .IP \[bu] 2 -\f[C]UCL_PARSER_NO_TIME\f[] - treat time values as strings without +\f[C]UCL_PARSER_NO_TIME\f[] \- treat time values as strings without parsing them as floats .SS ucl_parser_register_macro .IP @@ -161,7 +161,7 @@ bool\ ucl_parser_add_string\ (struct\ ucl_parser\ *parser,\ .PP This function acts exactly like \f[C]ucl_parser_add_chunk\f[] does but if \f[C]len\f[] argument is zero, then the string \f[C]data\f[] must be -zero-terminated and the actual length is calculated up to \f[C]\\0\f[] +zero\-terminated and the actual length is calculated up to \f[C]\\0\f[] character. .SS ucl_parser_add_file .IP @@ -229,7 +229,7 @@ bool\ ucl_pubkey_add\ (struct\ ucl_parser\ *parser,\ This function adds a public key from text blob \f[C]key\f[] of length \f[C]len\f[] to the \f[C]parser\f[] object. This public key should be in the \f[C]PEM\f[] format and can be used by -\f[C].includes\f[] macro for checking signatures of files included. +\f[C]\&.includes\f[] macro for checking signatures of files included. \f[C]Openssl\f[] support should be enabled to make this function working. If a key cannot be added (e.g. @@ -247,25 +247,26 @@ bool\ ucl_parser_set_filevars\ (struct\ ucl_parser\ *parser,\ Add the standard file variables to the \f[C]parser\f[] based on the \f[C]filename\f[] specified: .IP \[bu] 2 -\f[C]$FILENAME\f[] - a filename of \f[C]ucl\f[] input +\f[C]$FILENAME\f[] \- a filename of \f[C]ucl\f[] input .IP \[bu] 2 -\f[C]$CURDIR\f[] - a current directory of the input +\f[C]$CURDIR\f[] \- a current directory of the input .PP -For example, if a \f[C]filename\f[] param is \f[C]../something.conf\f[] -then the variables will have the following values: +For example, if a \f[C]filename\f[] param is +\f[C]\&../something.conf\f[] then the variables will have the following +values: .IP \[bu] 2 -\f[C]$FILENAME\f[] - "../something.conf" +\f[C]$FILENAME\f[] \- "../something.conf" .IP \[bu] 2 -\f[C]$CURDIR\f[] - ".." +\f[C]$CURDIR\f[] \- ".." .PP if \f[C]need_expand\f[] parameter is \f[C]true\f[] then all relative paths are expanded using \f[C]realpath\f[] call. -In this example if \f[C]..\f[] is \f[C]/etc/dir\f[] then variables will -have these values: +In this example if \f[C]\&..\f[] is \f[C]/etc/dir\f[] then variables +will have these values: .IP \[bu] 2 -\f[C]$FILENAME\f[] - "/etc/something.conf" +\f[C]$FILENAME\f[] \- "/etc/something.conf" .IP \[bu] 2 -\f[C]$CURDIR\f[] - "/etc" +\f[C]$CURDIR\f[] \- "/etc" .SS Parser usage example .PP The following example loads, parses and extracts \f[C]ucl\f[] object @@ -283,7 +284,7 @@ FILE\ *in; in\ =\ stdin; parser\ =\ ucl_parser_new\ (0); while\ (!feof\ (in)\ &&\ r\ <\ (int)sizeof\ (inbuf))\ { -\ \ \ \ r\ +=\ fread\ (inbuf\ +\ r,\ 1,\ sizeof\ (inbuf)\ -\ r,\ in); +\ \ \ \ r\ +=\ fread\ (inbuf\ +\ r,\ 1,\ sizeof\ (inbuf)\ \-\ r,\ in); } ucl_parser_add_chunk\ (parser,\ inbuf,\ r); fclose\ (in); @@ -309,20 +310,20 @@ return\ ret; .PP Libucl can transform UCL objects to a number of tectual formats: .IP \[bu] 2 -configuration (\f[C]UCL_EMIT_CONFIG\f[]) - nginx like human readable +configuration (\f[C]UCL_EMIT_CONFIG\f[]) \- nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys .IP \[bu] 2 -compact json: \f[C]UCL_EMIT_JSON_COMPACT\f[] - single line valid json +compact json: \f[C]UCL_EMIT_JSON_COMPACT\f[] \- single line valid json without spaces .IP \[bu] 2 -formatted json: \f[C]UCL_EMIT_JSON\f[] - pretty formatted JSON with +formatted json: \f[C]UCL_EMIT_JSON\f[] \- pretty formatted JSON with newlines and spaces .IP \[bu] 2 -compact yaml: \f[C]UCL_EMIT_YAML\f[] - compact YAML output +compact yaml: \f[C]UCL_EMIT_YAML\f[] \- compact YAML output .PP Moreover, libucl API allows to select a custom set of emitting functions -allowing efficent and zero-copy output of libucl objects. +allowing efficent and zero\-copy output of libucl objects. Libucl uses the following structure to support this feature: .IP .nf @@ -344,17 +345,17 @@ struct\ ucl_emitter_functions\ { .PP This structure defines the following callbacks: .IP \[bu] 2 -\f[C]ucl_emitter_append_character\f[] - a function that is called to +\f[C]ucl_emitter_append_character\f[] \- a function that is called to append \f[C]nchars\f[] characters equal to \f[C]c\f[] .IP \[bu] 2 -\f[C]ucl_emitter_append_len\f[] - used to append a string of length +\f[C]ucl_emitter_append_len\f[] \- used to append a string of length \f[C]len\f[] starting from pointer \f[C]str\f[] .IP \[bu] 2 -\f[C]ucl_emitter_append_int\f[] - this function applies to integer +\f[C]ucl_emitter_append_int\f[] \- this function applies to integer numbers .IP \[bu] 2 -\f[C]ucl_emitter_append_double\f[] - this function is intended to output -floating point variable +\f[C]ucl_emitter_append_double\f[] \- this function is intended to +output floating point variable .PP The set of these functions could be used to output text formats of \f[C]UCL\f[] objects to different structures or streams. @@ -364,7 +365,7 @@ Libucl provides the following functions for emitting UCL objects: .IP .nf \f[C] -unsigned\ char\ *ucl_object_emit\ (ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type); +unsigned\ char\ *ucl_object_emit\ (const\ ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type); \f[] .fi .PP @@ -376,7 +377,7 @@ The caller should free the returned string after using. .IP .nf \f[C] -bool\ ucl_object_emit_full\ (ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type, +bool\ ucl_object_emit_full\ (const\ ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type, \ \ \ \ \ \ \ \ struct\ ucl_emitter_functions\ *emitter); \f[] .fi @@ -400,26 +401,26 @@ cannot be converted then some reasonable default is returned (NULL for strings and 0 for numbers) .PP Also there is a single \f[C]ucl_object_tostring_forced\f[] function that -converts any UCL object (including compound types - arrays and objects) +converts any UCL object (including compound types \- arrays and objects) to a string representation. For compound and numeric types this function performs emitting to a compact json format actually. .PP Here is a list of all conversion functions: .IP \[bu] 2 -\f[C]ucl_object_toint\f[] - returns \f[C]int64_t\f[] of UCL object +\f[C]ucl_object_toint\f[] \- returns \f[C]int64_t\f[] of UCL object .IP \[bu] 2 -\f[C]ucl_object_todouble\f[] - returns \f[C]double\f[] of UCL object +\f[C]ucl_object_todouble\f[] \- returns \f[C]double\f[] of UCL object .IP \[bu] 2 -\f[C]ucl_object_toboolean\f[] - returns \f[C]bool\f[] of UCL object +\f[C]ucl_object_toboolean\f[] \- returns \f[C]bool\f[] of UCL object .IP \[bu] 2 -\f[C]ucl_object_tostring\f[] - returns \f[C]const\ char\ *\f[] of UCL +\f[C]ucl_object_tostring\f[] \- returns \f[C]const\ char\ *\f[] of UCL object (this string is NULL terminated) .IP \[bu] 2 -\f[C]ucl_object_tolstring\f[] - returns \f[C]const\ char\ *\f[] and +\f[C]ucl_object_tolstring\f[] \- returns \f[C]const\ char\ *\f[] and \f[C]size_t\f[] len of UCL object (string can be not NULL terminated) .IP \[bu] 2 -\f[C]ucl_object_tostring_forced\f[] - returns string representation of +\f[C]ucl_object_tostring_forced\f[] \- returns string representation of any UCL object .PP Strings returned by these pointers are associated with the UCL object @@ -448,26 +449,28 @@ ucl_object_t\ *\ ucl_object_typed_new\ (unsigned\ int\ type) \f[] .fi .PP -Create an object of a specified type: - \f[C]UCL_OBJECT\f[] - UCL object -- key/value pairs - \f[C]UCL_ARRAY\f[] - UCL array - \f[C]UCL_INT\f[] - -integer number - \f[C]UCL_FLOAT\f[] - floating point number - -\f[C]UCL_STRING\f[] - NULL terminated string - \f[C]UCL_BOOLEAN\f[] - -boolean value - \f[C]UCL_TIME\f[] - time value (floating point number of -seconds) - \f[C]UCL_USERDATA\f[] - opaque userdata pointer (may be used -in macros) - \f[C]UCL_NULL\f[] - null value +Create an object of a specified type: \- \f[C]UCL_OBJECT\f[] \- UCL +object \- key/value pairs \- \f[C]UCL_ARRAY\f[] \- UCL array \- +\f[C]UCL_INT\f[] \- integer number \- \f[C]UCL_FLOAT\f[] \- floating +point number \- \f[C]UCL_STRING\f[] \- NULL terminated string \- +\f[C]UCL_BOOLEAN\f[] \- boolean value \- \f[C]UCL_TIME\f[] \- time value +(floating point number of seconds) \- \f[C]UCL_USERDATA\f[] \- opaque +userdata pointer (may be used in macros) \- \f[C]UCL_NULL\f[] \- null +value .PP This object should be released by caller. .SS Primitive objects generation .PP Libucl provides the functions similar to inverse conversion functions -called with the specific C type: - \f[C]ucl_object_fromint\f[] - -converts \f[C]int64_t\f[] to UCL object - \f[C]ucl_object_fromdouble\f[] -- converts \f[C]double\f[] to UCL object - -\f[C]ucl_object_fromboolean\f[] - converts \f[C]bool\f[] to UCL object - -\f[C]ucl_object_fromstring\f[] - converts \f[C]const\ char\ *\f[] to UCL -object (this string is NULL terminated) - -\f[C]ucl_object_fromlstring\f[] - converts \f[C]const\ char\ *\f[] and -\f[C]size_t\f[] len to UCL object (string can be not NULL terminated) +called with the specific C type: \- \f[C]ucl_object_fromint\f[] \- +converts \f[C]int64_t\f[] to UCL object \- +\f[C]ucl_object_fromdouble\f[] \- converts \f[C]double\f[] to UCL object +\- \f[C]ucl_object_fromboolean\f[] \- converts \f[C]bool\f[] to UCL +object \- \f[C]ucl_object_fromstring\f[] \- converts +\f[C]const\ char\ *\f[] to UCL object (this string is NULL terminated) +\- \f[C]ucl_object_fromlstring\f[] \- converts \f[C]const\ char\ *\f[] +and \f[C]size_t\f[] len to UCL object (string can be not NULL +terminated) .PP Also there is a function to generate UCL object from a string performing various parsing or conversion operations called @@ -484,35 +487,35 @@ ucl_object_t\ *\ ucl_object_fromstring_common\ (const\ char\ *str,\ This function is used to convert a string \f[C]str\f[] of size \f[C]len\f[] to an UCL objects applying \f[C]flags\f[] conversions. If \f[C]len\f[] is equal to zero then a \f[C]str\f[] is assumed as -NULL-terminated. +NULL\-terminated. This function supports the following flags (a set of flags can be specified using logical \f[C]OR\f[] operation): .IP \[bu] 2 -\f[C]UCL_STRING_ESCAPE\f[] - perform JSON escape +\f[C]UCL_STRING_ESCAPE\f[] \- perform JSON escape .IP \[bu] 2 -\f[C]UCL_STRING_TRIM\f[] - trim leading and trailing whitespaces +\f[C]UCL_STRING_TRIM\f[] \- trim leading and trailing whitespaces .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_BOOLEAN\f[] - parse passed string and detect +\f[C]UCL_STRING_PARSE_BOOLEAN\f[] \- parse passed string and detect boolean .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_INT\f[] - parse passed string and detect integer +\f[C]UCL_STRING_PARSE_INT\f[] \- parse passed string and detect integer number .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_DOUBLE\f[] - parse passed string and detect +\f[C]UCL_STRING_PARSE_DOUBLE\f[] \- parse passed string and detect integer or float number .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_TIME\f[] - parse time values as floating point +\f[C]UCL_STRING_PARSE_TIME\f[] \- parse time values as floating point numbers .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_NUMBER\f[] - parse passed string and detect number -(both float, integer and time types) +\f[C]UCL_STRING_PARSE_NUMBER\f[] \- parse passed string and detect +number (both float, integer and time types) .IP \[bu] 2 -\f[C]UCL_STRING_PARSE\f[] - parse passed string (and detect booleans, +\f[C]UCL_STRING_PARSE\f[] \- parse passed string (and detect booleans, numbers and time values) .IP \[bu] 2 -\f[C]UCL_STRING_PARSE_BYTES\f[] - assume that numeric multipliers are in -bytes notation, for example \f[C]10k\f[] means \f[C]10*1024\f[] and not -\f[C]10*1000\f[] as assumed without this flag +\f[C]UCL_STRING_PARSE_BYTES\f[] \- assume that numeric multipliers are +in bytes notation, for example \f[C]10k\f[] means \f[C]10*1024\f[] and +not \f[C]10*1000\f[] as assumed without this flag .PP If parsing operations fail then the resulting UCL object will be a \f[C]UCL_STRING\f[]. @@ -530,7 +533,7 @@ is a function \f[C]ucl_iterate_object\f[]. .IP .nf \f[C] -ucl_object_t*\ ucl_iterate_object\ (ucl_object_t\ *obj,\ +const\ ucl_object_t*\ ucl_iterate_object\ (const\ ucl_object_t\ *obj,\ \ \ \ \ ucl_object_iter_t\ *iter,\ bool\ expand_values); \f[] .fi @@ -561,7 +564,7 @@ Here is an example of iteration over the objects using libucl API .nf \f[C] ucl_object_iter_t\ it\ =\ NULL,\ it_obj\ =\ NULL; -ucl_object_t\ *cur,\ *tmp; +const\ ucl_object_t\ *cur,\ *tmp; /*\ Iterate\ over\ the\ object\ */ while\ ((obj\ =\ ucl_iterate_object\ (top,\ &it,\ true)))\ { @@ -584,13 +587,13 @@ This function is defined as following: .IP .nf \f[C] -bool\ ucl_object_validate\ (ucl_object_t\ *schema, -\ \ \ \ ucl_object_t\ *obj,\ struct\ ucl_schema_error\ *err); +bool\ ucl_object_validate\ (const\ ucl_object_t\ *schema, +\ \ \ \ const\ ucl_object_t\ *obj,\ struct\ ucl_schema_error\ *err); \f[] .fi .PP This function uses ucl object \f[C]schema\f[], that must be valid in -terms of \f[C]json-schema\f[] draft v4, to validate input object +terms of \f[C]json\-schema\f[] draft v4, to validate input object \f[C]obj\f[]. If this function returns \f[C]true\f[] then validation procedure has been succeed. |
