view release on metacpan or  search on metacpan

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

\- \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 should be 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
does not need to be NULL terminated)
.PP
Also there is a function to generate UCL object from a string performing
various parsing or conversion operations called
\f[C]ucl_object_fromstring_common\f[].
.SS ucl_object_fromstring_common
.IP
.nf
\f[C]
ucl_object_t\ *\ ucl_object_fromstring_common\ (const\ char\ *str,\ 
\ \ \ \ size_t\ len,\ enum\ ucl_string_flags\ flags)
\f[]
.fi
.PP
This function is used to convert a string \f[C]str\f[] of size
\f[C]len\f[] to a UCL object 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.
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
.IP \[bu] 2
\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
boolean
.IP \[bu] 2
\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
integer or float number
.IP \[bu] 2
\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)
.IP \[bu] 2
\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
.PP
If parsing operations fail then the resulting UCL object will be a
\f[C]UCL_STRING\f[].
A caller should always check the type of the returned object and release
it after using.
.SH ITERATION FUNCTIONS
.PP
Iteration are used to iterate over UCL compound types: arrays and
objects.
Moreover, iterations could be performed over the keys with multiple
values (implicit arrays).
There are two types of iterators API: old and unsafe one via
\f[C]ucl_iterate_object\f[] and the proposed interface of safe
iterators.
.SS ucl_iterate_object
.IP
.nf
\f[C]
const\ ucl_object_t*\ ucl_iterate_object\ (const\ ucl_object_t\ *obj,\ 
\ \ \ \ ucl_object_iter_t\ *iter,\ bool\ expand_values);
\f[]
.fi
.PP
This function accepts opaque iterator pointer \f[C]iter\f[].
In the first call this iterator \f[I]must\f[] be initialized to
\f[C]NULL\f[].
Iterator is changed by this function call.
\f[C]ucl_iterate_object\f[] returns the next UCL object in the compound
object \f[C]obj\f[] or \f[C]NULL\f[] if all objects have been iterated.
The reference count of the object returned is not increased, so a caller
should not unref the object or modify its content (e.g.
by inserting to another compound object).
The object \f[C]obj\f[] should not be changed during the iteration
process as well.
\f[C]expand_values\f[] flag speicifies whether
\f[C]ucl_iterate_object\f[] should expand keys with multiple values.
The general rule is that if you need to iterate through the
\f[I]object\f[] or \f[I]explicit array\f[], then you always need to set
this flag to \f[C]true\f[].
However, if you get some key in the object and want to extract all its
values then you should set \f[C]expand_values\f[] to \f[C]false\f[].
Mixing of iteration types is not permitted since the iterator is set
according to the iteration type and cannot be reused.
Here is an example of iteration over the objects using libucl API
(assuming that \f[C]top\f[] is \f[C]UCL_OBJECT\f[] in this example):
.IP
.nf
\f[C]
ucl_object_iter_t\ it\ =\ NULL,\ it_obj\ =\ NULL;
const\ ucl_object_t\ *cur,\ *tmp;

/*\ Iterate\ over\ the\ object\ */
while\ ((obj\ =\ ucl_iterate_object\ (top,\ &it,\ true)))\ {
\ \ \ \ printf\ ("key:\ \\"%s\\"\\n",\ ucl_object_key\ (obj));
\ \ \ \ /*\ Iterate\ over\ the\ values\ of\ a\ key\ */
\ \ \ \ while\ ((cur\ =\ ucl_iterate_object\ (obj,\ &it_obj,\ false)))\ {
\ \ \ \ \ \ \ \ printf\ ("value:\ \\"%s\\"\\n",\ 
\ \ \ \ \ \ \ \ \ \ \ \ ucl_object_tostring_forced\ (cur));
\ \ \ \ }
}
\f[]
.fi
.SS Safe iterators API
.PP
Safe iterators are defined to clarify iterating over UCL objects and
simplify flattening of UCL objects in non\-trivial cases.
For example, if there is an implicit array that contains another array
and a boolean value it is extremely unclear how to iterate over such an
object.
Safe iterators are desinged to define two sorts of iteration: