view release on metacpan or  search on metacpan

libucl-0.8.1/doc/api.md  view on Meta::CPAN

~~~C
char inbuf[8192];
struct ucl_parser *parser = NULL;
int ret = 0, r = 0;
ucl_object_t *obj = NULL;
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);
}
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;
~~~

# Emitting functions

Libucl can transform UCL objects to a number of tectual formats:

- configuration (`UCL_EMIT_CONFIG`) - nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys
- compact json: `UCL_EMIT_JSON_COMPACT` - single line valid json without spaces
- formatted json: `UCL_EMIT_JSON` - pretty formatted JSON with newlines and spaces
- compact yaml: `UCL_EMIT_YAML` - compact YAML output

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:

~~~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;
};
~~~

This structure defines the following callbacks:

- `ucl_emitter_append_character` - a function that is called to append `nchars` characters equal to `c`
- `ucl_emitter_append_len` - used to append a string of length `len` starting from pointer `str`
- `ucl_emitter_append_int` - this function applies to integer numbers
- `ucl_emitter_append_double` - this function is intended to output floating point variable

The set of these functions could be used to output text formats of `UCL` objects to different structures or streams.

Libucl provides the following functions for emitting UCL objects:

### ucl_object_emit

~~~C
unsigned char *ucl_object_emit (const ucl_object_t *obj, enum ucl_emitter emit_type);
~~~

Allocate a string that is suitable to fit the underlying UCL object `obj` and fill it with the textual representation of the object `obj` according to style `emit_type`. The caller should free the returned string after using.

### ucl_object_emit_full

~~~C
bool ucl_object_emit_full (const ucl_object_t *obj, enum ucl_emitter emit_type,
		struct ucl_emitter_functions *emitter);
~~~

This function is similar to the previous with the exception that it accepts the additional argument `emitter` that defines the concrete set of output functions. This emit function could be useful for custom structures or streams emitters (including C...

# Conversion functions

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:

- safe: try to convert an ucl object to a primitive type and fail if such a conversion is not possible
- 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)

Also there is a single `ucl_object_tostring_forced` 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 emitting to a...

Here is a list of all conversion functions:

- `ucl_object_toint` - returns `int64_t` of UCL object
- `ucl_object_todouble` - returns `double` of UCL object
- `ucl_object_toboolean` - returns `bool` of UCL object
- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated)
- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string does not need to be NULL terminated)
- `ucl_object_tostring_forced` - returns string representation of any UCL object

Strings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory.

# Generation functions

It is possible to generate UCL objects from C primitive types. Moreover, libucl allows creation and modifying complex UCL objects, such as arrays or associative objects. 

## ucl_object_new
~~~C
ucl_object_t * ucl_object_new (void)
~~~

Creates new object of type `UCL_NULL`. This object should be released by caller.

## ucl_object_typed_new
~~~C