view release on metacpan or  search on metacpan

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

while\ (!feof\ (in)\ &&\ r\ <\ (int)sizeof\ (inbuf))\ {
\ \ \ \ r\ +=\ fread\ (inbuf\ +\ r,\ 1,\ sizeof\ (inbuf)\ \-\ r,\ in);
}
ucl_parser_add_chunk\ (parser,\ inbuf,\ r);
fclose\ (in);

if\ (ucl_parser_get_error\ (parser))\ {
\ \ \ \ printf\ ("Error\ occurred:\ %s\\n",\ ucl_parser_get_error\ (parser));
\ \ \ \ ret\ =\ 1;
}
else\ {
\ \ \ \ obj\ =\ ucl_parser_get_object\ (parser);
}

if\ (parser\ !=\ NULL)\ {
\ \ \ \ ucl_parser_free\ (parser);
}
if\ (obj\ !=\ NULL)\ {
\ \ \ \ ucl_object_unref\ (obj);
}
return\ ret;
\f[]
.fi
.SH EMITTING FUNCTIONS
.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 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
without spaces
.IP \[bu] 2
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
.PP
Moreover, libucl API allows to select a custom set of emitting functions
allowing efficient and zero\-copy output of libucl objects.
Libucl uses the following structure to support this feature:
.IP
.nf
\f[C]
struct\ ucl_emitter_functions\ {
\ \ \ \ /**\ Append\ a\ single\ character\ */
\ \ \ \ int\ (*ucl_emitter_append_character)\ (unsigned\ char\ c,\ size_t\ nchars,\ void\ *ud);
\ \ \ \ /**\ Append\ a\ string\ of\ a\ specified\ length\ */
\ \ \ \ int\ (*ucl_emitter_append_len)\ (unsigned\ const\ char\ *str,\ size_t\ len,\ void\ *ud);
\ \ \ \ /**\ Append\ a\ 64\ bit\ integer\ */
\ \ \ \ int\ (*ucl_emitter_append_int)\ (int64_t\ elt,\ void\ *ud);
\ \ \ \ /**\ Append\ floating\ point\ element\ */
\ \ \ \ int\ (*ucl_emitter_append_double)\ (double\ elt,\ void\ *ud);
\ \ \ \ /**\ Opaque\ userdata\ pointer\ */
\ \ \ \ void\ *ud;
};
\f[]
.fi
.PP
This structure defines the following callbacks:
.IP \[bu] 2
\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]len\f[] starting from pointer \f[C]str\f[]
.IP \[bu] 2
\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
.PP
The set of these functions could be used to output text formats of
\f[C]UCL\f[] objects to different structures or streams.
.PP
Libucl provides the following functions for emitting UCL objects:
.SS ucl_object_emit
.IP
.nf
\f[C]
unsigned\ char\ *ucl_object_emit\ (const\ ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type);
\f[]
.fi
.PP
Allocate a string that is suitable to fit the underlying UCL object
\f[C]obj\f[] and fill it with the textual representation of the object
\f[C]obj\f[] according to style \f[C]emit_type\f[].
The caller should free the returned string after using.
.SS ucl_object_emit_full
.IP
.nf
\f[C]
bool\ ucl_object_emit_full\ (const\ ucl_object_t\ *obj,\ enum\ ucl_emitter\ emit_type,
\ \ \ \ \ \ \ \ struct\ ucl_emitter_functions\ *emitter);
\f[]
.fi
.PP
This function is similar to the previous with the exception that it
accepts the additional argument \f[C]emitter\f[] that defines the
concrete set of output functions.
This emit function could be useful for custom structures or streams
emitters (including C++ ones, for example).
.SH CONVERSION FUNCTIONS
.PP
Conversion functions are used to convert UCL objects to primitive types,
such as strings, numbers, or boolean values.
There are two types of conversion functions:
.IP \[bu] 2
safe: try to convert an ucl object to a primitive type and fail if such
a conversion is not possible
.IP \[bu] 2
unsafe: return primitive type without additional checks, if the object
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)
to a string representation.
For objects, arrays, booleans and numeric types this function performs