view release on metacpan or  search on metacpan

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

# API documentation

**Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*

- [Synopsis](#synopsis)
- [Description](#description)
	- [Parser functions](#parser-functions)
	- [Emitting functions](#emitting-functions)
	- [Conversion functions](#conversion-functions)
	- [Generation functions](#generation-functions)
	- [Iteration functions](#iteration-functions)
	- [Validation functions](#validation-functions)
	- [Utility functions](#utility-functions)
- [Parser functions](#parser-functions-1)
	- [ucl_parser_new](#ucl_parser_new)
	- [ucl_parser_register_macro](#ucl_parser_register_macro)
	- [ucl_parser_register_variable](#ucl_parser_register_variable)
	- [ucl_parser_add_chunk](#ucl_parser_add_chunk)
	- [ucl_parser_add_string](#ucl_parser_add_string)
	- [ucl_parser_add_file](#ucl_parser_add_file)
	- [ucl_parser_get_object](#ucl_parser_get_object)
	- [ucl_parser_get_error](#ucl_parser_get_error)
	- [ucl_parser_free](#ucl_parser_free)
	- [ucl_pubkey_add](#ucl_pubkey_add)
	- [ucl_parser_set_filevars](#ucl_parser_set_filevars)
	- [Parser usage example](#parser-usage-example)
- [Emitting functions](#emitting-functions-1)
	- [ucl_object_emit](#ucl_object_emit)
	- [ucl_object_emit_full](#ucl_object_emit_full)
- [Conversion functions](#conversion-functions-1)
- [Generation functions](#generation-functions-1)
	- [ucl_object_new](#ucl_object_new)
	- [ucl_object_typed_new](#ucl_object_typed_new)
	- [Primitive objects generation](#primitive-objects-generation)
	- [ucl_object_fromstring_common](#ucl_object_fromstring_common)
- [Iteration functions](#iteration-functions-1)
	- [ucl_iterate_object](#ucl_iterate_object)
- [Validation functions](#validation-functions-1)
	- [ucl_object_validate](#ucl_object_validate)

# Synopsis

`#include <ucl.h>`

# Description

Libucl is a parser and `C` API to parse and generate `ucl` objects. Libucl consist of several groups of functions:

### Parser functions
Used to parse `ucl` files and provide interface to extract `ucl` object. Currently, `libucl` can parse only full `ucl` documents, for instance, it is impossible to parse a part of document and therefore it is impossible to use `libucl` as a streaming...

### Emitting functions
Convert `ucl` objects to some textual or binary representation. Currently, libucl supports the following exports:

- `JSON` - valid json format (can possibly lose some original data, such as implicit arrays)
- `Config` - human-readable configuration format (lossless)
- `YAML` - embedded yaml format (has the same limitations as `json` output)

### Conversion functions
Help to convert `ucl` objects to C types. These functions are used to convert `ucl_object_t` to C primitive types, such as numbers, strings or boolean values.

### Generation functions
Allow creation of `ucl` objects from C types and creating of complex `ucl` objects, such as hashes or arrays from primitive `ucl` objects, such as numbers or strings.

### Iteration functions
Iterate over `ucl` 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).

### Validation functions
Validation functions are used to validate some object `obj` using json-schema compatible object `schema`. Both input and schema must be UCL objects to perform validation.

### Utility functions
Provide basic utilities to manage `ucl` objects: creating, removing, retaining and releasing reference count and so on.

# Parser functions

Parser functions operates with `struct ucl_parser`.

### ucl_parser_new

~~~C
struct ucl_parser* ucl_parser_new (int flags);
~~~

Creates new parser with the specified flags:

- `UCL_PARSER_KEY_LOWERCASE` - lowercase keys parsed
- `UCL_PARSER_ZEROCOPY` - 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)
- `UCL_PARSER_NO_TIME` - treat time values as strings without parsing them as floats

### ucl_parser_register_macro

~~~C
void ucl_parser_register_macro (struct ucl_parser *parser,
    const char *macro, ucl_macro_handler handler, void* ud);
~~~

Register new macro with name .`macro` parsed by handler `handler` that accepts opaque data pointer `ud`. Macro handler should be of the following type:

~~~C
bool (*ucl_macro_handler) (const unsigned char *data,
    size_t len, void* ud);`
~~~

Handler function accepts macro text `data` of length `len` and the opaque pointer `ud`. If macro is parsed successfully the handler should return `true`. `false` indicates parsing failure and the parser can be terminated.

### ucl_parser_register_variable

~~~C
void ucl_parser_register_variable (struct ucl_parser *parser,
    const char *var, const char *value);