view release on metacpan or  search on metacpan

libucl-0.8.1/doc/libucl.3  view on Meta::CPAN

\f[C]Config\f[] \- human\-readable configuration format (lossless)
.IP \[bu] 2
\f[C]YAML\f[] \- embedded yaml format (has the same limitations as
\f[C]json\f[] output)
.SS Conversion functions
.PP
Help to convert \f[C]ucl\f[] objects to C types.
These functions are used to convert \f[C]ucl_object_t\f[] to C primitive
types, such as numbers, strings or boolean values.
.SS Generation functions
.PP
Allow creation of \f[C]ucl\f[] objects from C types and creating of
complex \f[C]ucl\f[] objects, such as hashes or arrays from primitive
\f[C]ucl\f[] objects, such as numbers or strings.
.SS Iteration functions
.PP
Iterate over \f[C]ucl\f[] complex objects or over a chain of values, for
example when a key in an object has multiple values (that can be treated
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[].
Both input and schema must be UCL objects to perform validation.
.SS Utility functions
.PP
Provide basic utilities to manage \f[C]ucl\f[] objects: creating,
removing, retaining and releasing reference count and so on.
.SH PARSER FUNCTIONS
.PP
Parser functions operates with \f[C]struct\ ucl_parser\f[].
.SS ucl_parser_new
.IP
.nf
\f[C]
struct\ ucl_parser*\ ucl_parser_new\ (int\ flags);
\f[]
.fi
.PP
Creates new parser with the specified flags:
.IP \[bu] 2
\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)
.IP \[bu] 2
\f[C]UCL_PARSER_NO_TIME\f[] \- treat time values as strings without
parsing them as floats
.SS ucl_parser_register_macro
.IP
.nf
\f[C]
void\ ucl_parser_register_macro\ (struct\ ucl_parser\ *parser,
\ \ \ \ const\ char\ *macro,\ ucl_macro_handler\ handler,\ void*\ ud);
\f[]
.fi
.PP
Register new macro with name .\f[C]macro\f[] parsed by handler
\f[C]handler\f[] that accepts opaque data pointer \f[C]ud\f[].
Macro handler should be of the following type:
.IP
.nf
\f[C]
bool\ (*ucl_macro_handler)\ (const\ unsigned\ char\ *data,
\ \ \ \ size_t\ len,\ void*\ ud);`
\f[]
.fi
.PP
Handler function accepts macro text \f[C]data\f[] of length \f[C]len\f[]
and the opaque pointer \f[C]ud\f[].
If macro is parsed successfully the handler should return \f[C]true\f[].
\f[C]false\f[] indicates parsing failure and the parser can be
terminated.
.SS ucl_parser_register_variable
.IP
.nf
\f[C]
void\ ucl_parser_register_variable\ (struct\ ucl_parser\ *parser,
\ \ \ \ const\ char\ *var,\ const\ char\ *value);
\f[]
.fi
.PP
Register new variable $\f[C]var\f[] that should be replaced by the
parser to the \f[C]value\f[] string.
.SS ucl_parser_add_chunk
.IP
.nf
\f[C]
bool\ ucl_parser_add_chunk\ (struct\ ucl_parser\ *parser,\ 
\ \ \ \ const\ unsigned\ char\ *data,\ size_t\ len);
\f[]
.fi
.PP
Add new text chunk with \f[C]data\f[] of length \f[C]len\f[] to the
parser.
At the moment, \f[C]libucl\f[] parser is not a streamlined parser and
chunk \f[I]must\f[] contain the \f[I]valid\f[] ucl object.
For example, this object should be valid:
.IP
.nf
\f[C]
{\ "var":\ "value"\ }
\f[]
.fi
.PP
while this one won\[aq]t be parsed correctly:
.IP
.nf
\f[C]
{\ "var":\ 
\f[]
.fi
.PP
This limitation may possible be removed in future.
.SS ucl_parser_add_string
.IP
.nf
\f[C]
bool\ ucl_parser_add_string\ (struct\ ucl_parser\ *parser,\ 
\ \ \ \ const\ char\ *data,\ size_t\ len);