AC_MSG_CHECKING(for GCC atomic builtins)

AC_LINK_IFELSE([

	AC_LANG_SOURCE([[

		int main() {

			volatile unsigned long val = 1;

			__sync_synchronize();

			__sync_val_compare_and_swap(&val, 1, 0);

			__sync_add_and_fetch(&val, 1);

			__sync_sub_and_fetch(&val, 1);

			return 0;

		}

	]])

],

[

 	AC_MSG_RESULT([yes])

	AC_DEFINE([HAVE_ATOMIC_BUILTINS], [1], [Has gcc/MSVC atomic intrinsics])

],

[

 	AC_MSG_RESULT([no])

	AC_DEFINE([HAVE_ATOMIC_BUILTINS], [0], [Has gcc/MSVC atomic intrinsics])

])

EXTRA_DIST = uthash README.md

SUBDIRS = src tests utils doc

# LIBUCL

[![Build Status](https://travis-ci.org/vstakhov/libucl.svg?branch=master)](https://travis-ci.org/vstakhov/libucl)

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

- [Introduction](#introduction)

- [Basic structure](#basic-structure)

- [Improvements to the json notation](#improvements-to-the-json-notation)

	- [General syntax sugar](#general-syntax-sugar)

	- [Automatic arrays creation](#automatic-arrays-creation)

	- [Named keys hierarchy](#named-keys-hierarchy)

	- [Convenient numbers and booleans](#convenient-numbers-and-booleans)

- [General improvements](#general-improvements)

	- [Commments](#commments)

	- [Macros support](#macros-support)

	- [Variables support](#variables-support)

	- [Multiline strings](#multiline-strings)

- [Emitter](#emitter)

- [Validation](#validation)

- [Performance](#performance)

- [Conclusion](#conclusion)

## Validation

UCL allows validation of objects. It uses the same schema that is used for json: [json schema v4](http://json-schema.org). UCL supports the full set of json schema with the exception of remote references. This feature is unlikely useful for configuration objects. Of course, a schema definition can be in UCL format instead of JSON that simplifies schemas writing. Moreover, since UCL supports multiple values for keys in an object it is possible to specify generic integer constraints `maxValues` and `minValues` to define the limits of values count in a single key. UCL currently is not absolutely strict about validation schemas themselves, therefore UCL users should supply valid schemas (as it is defined in json-schema draft v4) to ensure that the input objects are validated properly.

AM_INIT_AUTOMAKE([1.11 foreign silent-rules -Wall -Wportability no-dist-gzip dist-xz])

AM_PROG_AR

AC_ARG_ENABLE([urls], AS_HELP_STRING([--enable-urls], 

	[Enable URLs fetch (requires libfetch or libcurl) @<:@default=no@:>@]), [],

	[enable_urls=no])

AC_ARG_ENABLE([regex], AS_HELP_STRING([--enable-regex], 

	[Enable regex checking for schema @<:@default=yes@:>@]), [],

	[enable_regex=yes])

AC_ARG_ENABLE([signatures], AS_HELP_STRING([--enable-signatures],

	[Enable signatures check (requires openssl) @<:@default=no@:>@]), [],

	[enable_signatures=no])

	AS_HELP_STRING([--enable-utils], [Build and install utils @<:@default=no@:>@]),

		LIBCRYPTO_LIB="-lcrypto"

AC_SUBST(LIBCRYPTO_LIB)

AC_PATH_PROG(PANDOC, pandoc, [/non/existent])

AS_IF([test "x$enable_regex" = "xyes"], [

	AC_CHECK_HEADER([regex.h], [

		AC_DEFINE(HAVE_REGEX_H, 1, [Define to 1 if you have the <regex.h> header file.])

		AC_SEARCH_LIBS([regexec], [regex], [

			AS_IF([test "x$ac_cv_search_regexec" = "x-lregex"], [

				LIBREGEX_LIB="-lregex"

				LIBS_EXTRA="${LIBS_EXTRA} -lregex"

				]

			)], 

			[AC_MSG_ERROR([unable to find the regexec() function])])],

			[AC_MSG_ERROR([unable to find the regex.h header])

		],

		[#include <sys/types.h>])

])

AC_SUBST(LIBREGEX_LIB)

AS_IF([test "x$enable_urls" = "xyes"], [

			LIBS_EXTRA="${LIBS_EXTRA} -lcurl"],

AC_MSG_CHECKING(for GCC atomic builtins)

AC_LINK_IFELSE([

	AC_LANG_SOURCE([[

		int main() {

			volatile unsigned long val = 1;

			__sync_synchronize();

			__sync_val_compare_and_swap(&val, 1, 0);

			__sync_add_and_fetch(&val, 1);

			__sync_sub_and_fetch(&val, 1);

			return 0;

		}

	]])

],

[

	AC_MSG_RESULT([yes])

	AC_DEFINE([HAVE_ATOMIC_BUILTINS], [1], [Has gcc/MSVC atomic intrinsics])

],

[

	AC_MSG_RESULT([no])

	AC_DEFINE([HAVE_ATOMIC_BUILTINS], [0], [Has gcc/MSVC atomic intrinsics])

	AC_MSG_WARN([Libucl references could be thread-unsafe because atomic builtins are missing])

])

	doc/Makefile \

EXTRA_DIST = api.md

dist_man_MANS = libucl.3

gen-man: @PANDOC@

	tail -n +$$(grep -n '# Synopsis' api.md | cut -d':' -f1) api.md | \

	cat pandoc.template - | sed -e 's/^# \(.*\)/# \U\1/' | \

	@PANDOC@ -s -f markdown -t man -o libucl.3 

# 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

# Description

### 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.

# Iteration functions

~~~

# Validation functions

Currently, there is only one validation function called `ucl_object_validate`. It performs validation of object using the specified schema. This function is defined as following:

## ucl_object_validate

~~~C

bool ucl_object_validate (ucl_object_t *schema,

	ucl_object_t *obj, struct ucl_schema_error *err);

~~~

This function uses ucl object `schema`, that must be valid in terms of `json-schema` draft v4, to validate input object `obj`. If this function returns `true` then validation procedure has been succeed. Otherwise, `false` is returned and `err` is set to a specific value. If caller set `err` to NULL then this function does not set any error just returning `false`. Error is the structure defined as following:

~~~C

struct ucl_schema_error {

	enum ucl_schema_error_code code;	/* error code */

	char msg[128];				/* error message */

	ucl_object_t *obj;			/* object where error occured */

};

~~~

Caller may use `code` field to get a numeric error code:

~~~C

enum ucl_schema_error_code {

	UCL_SCHEMA_OK = 0,          /* no error */

	UCL_SCHEMA_TYPE_MISMATCH,   /* type of object is incorrect */

	UCL_SCHEMA_INVALID_SCHEMA,  /* schema is invalid */

	UCL_SCHEMA_MISSING_PROPERTY,/* missing properties */

	UCL_SCHEMA_CONSTRAINT,      /* constraint found */

	UCL_SCHEMA_MISSING_DEPENDENCY, /* missing dependency */

	UCL_SCHEMA_UNKNOWN          /* generic error */

};

~~~

`msg` is a stiring description of an error and `obj` is an object where error has been occurred. Error object is not allocated by libucl, so there is no need to free it after validation (a static object should thus be used).

.TH LIBUCL 5 "March 20, 2014" "Libucl manual"

.SH NAME

.PP

\f[B]ucl_parser_new\f[], \f[B]ucl_parser_register_macro\f[],

\f[B]ucl_parser_register_variable\f[], \f[B]ucl_parser_add_chunk\f[],

\f[B]ucl_parser_add_string\f[], \f[B]ucl_parser_add_file\f[],

\f[B]ucl_parser_get_object\f[], \f[B]ucl_parser_get_error\f[],

\f[B]ucl_parser_free\f[], \f[B]ucl_pubkey_add\f[],

\f[B]ucl_parser_set_filevars\f[] - universal configuration library

parser and utility functions

.SH LIBRARY

.PP

UCL library (libucl, -lucl)

.SH SYNOPSIS

.PP

\f[C]#include\ <ucl.h>\f[]

.SH DESCRIPTION

.PP

Libucl is a parser and \f[C]C\f[] API to parse and generate \f[C]ucl\f[]

objects.

Libucl consist of several groups of functions:

.SS Parser functions

.PP

Used to parse \f[C]ucl\f[] files and provide interface to extract

\f[C]ucl\f[] object.

Currently, \f[C]libucl\f[] can parse only full \f[C]ucl\f[] documents,

for instance, it is impossible to parse a part of document and therefore

it is impossible to use \f[C]libucl\f[] as a streaming parser.

In future, this limitation can be removed.

.SS Emitting functions

.PP

Convert \f[C]ucl\f[] objects to some textual or binary representation.

Currently, libucl supports the following exports:

.IP \[bu] 2

\f[C]JSON\f[] - valid json format (can possibly loose some original

data, such as implicit arrays)

.IP \[bu] 2

\f[C]Config\f[] - human-readable configuration format (losseless)

.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 creating 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);

\f[]

.fi

.PP

This function acts exactly like \f[C]ucl_parser_add_chunk\f[] does but

if \f[C]len\f[] argument is zero, then the string \f[C]data\f[] must be

zero-terminated and the actual length is calculated up to \f[C]\\0\f[]

character.

.SS ucl_parser_add_file

.IP

.nf

\f[C]

bool\ ucl_parser_add_file\ (struct\ ucl_parser\ *parser,\ 

\ \ \ \ const\ char\ *filename);

\f[]

.fi

.PP

Load file \f[C]filename\f[] and parse it with the specified

\f[C]parser\f[].

This function uses \f[C]mmap\f[] call to load file, therefore, it should

not be \f[C]shrinked\f[] during parsing.

Otherwise, \f[C]libucl\f[] can cause memory corruption and terminate the

calling application.

This function is also used by the internal handler of \f[C]include\f[]

macro, hence, this macro has the same limitation.

.SS ucl_parser_get_object

.IP

.nf

\f[C]

ucl_object_t*\ ucl_parser_get_object\ (struct\ ucl_parser\ *parser);

\f[]

.fi

.PP

If the \f[C]ucl\f[] data has been parsed correctly this function returns

the top object for the parser.

Otherwise, this function returns the \f[C]NULL\f[] pointer.

The reference count for \f[C]ucl\f[] object returned is increased by

one, therefore, a caller should decrease reference by using

\f[C]ucl_object_unref\f[] to free object after usage.

.SS ucl_parser_get_error

.IP

.nf

\f[C]

const\ char\ *ucl_parser_get_error(struct\ ucl_parser\ *parser);

\f[]

.fi

.PP

Returns the constant error string for the parser object.

If no error occurred during parsing a \f[C]NULL\f[] object is returned.

A caller should not try to free or modify this string.

.SS ucl_parser_free

.IP

.nf

\f[C]

void\ ucl_parser_free\ (struct\ ucl_parser\ *parser);

\f[]

.fi

.PP

Frees memory occupied by the parser object.

The reference count for top object is decreased as well, however if the

function \f[C]ucl_parser_get_object\f[] was called previously then the

top object won\[aq]t be freed.

.SS ucl_pubkey_add

.IP

.nf

\f[C]

bool\ ucl_pubkey_add\ (struct\ ucl_parser\ *parser,\ 

\ \ \ \ const\ unsigned\ char\ *key,\ size_t\ len);

\f[]

.fi

.PP

This function adds a public key from text blob \f[C]key\f[] of length

\f[C]len\f[] to the \f[C]parser\f[] object.

This public key should be in the \f[C]PEM\f[] format and can be used by

\f[C].includes\f[] macro for checking signatures of files included.

\f[C]Openssl\f[] support should be enabled to make this function

working.

If a key cannot be added (e.g.

due to format error) or \f[C]openssl\f[] was not linked to

\f[C]libucl\f[] then this function returns \f[C]false\f[].

.SS ucl_parser_set_filevars

.IP

.nf

\f[C]

bool\ ucl_parser_set_filevars\ (struct\ ucl_parser\ *parser,\ 

\ \ \ \ const\ char\ *filename,\ bool\ need_expand);

\f[]

.fi

.PP

Add the standard file variables to the \f[C]parser\f[] based on the

\f[C]filename\f[] specified:

.IP \[bu] 2

\f[C]$FILENAME\f[] - a filename of \f[C]ucl\f[] input

.IP \[bu] 2

\f[C]$CURDIR\f[] - a current directory of the input

.PP

For example, if a \f[C]filename\f[] param is \f[C]../something.conf\f[]

then the variables will have the following values:

.IP \[bu] 2

\f[C]$FILENAME\f[] - "../something.conf"

.IP \[bu] 2

\f[C]$CURDIR\f[] - ".."

.PP

if \f[C]need_expand\f[] parameter is \f[C]true\f[] then all relative

paths are expanded using \f[C]realpath\f[] call.

In this example if \f[C]..\f[] is \f[C]/etc/dir\f[] then variables will

have these values:

.IP \[bu] 2

\f[C]$FILENAME\f[] - "/etc/something.conf"

.IP \[bu] 2

\f[C]$CURDIR\f[] - "/etc"

.SS Parser usage example

.PP

The following example loads, parses and extracts \f[C]ucl\f[] object

from stdin using \f[C]libucl\f[] parser functions (the length of input

is limited to 8K):

.IP

.nf

\f[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\ occured:\ %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 efficent 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\ (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\ (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 compound and numeric types this function performs emitting to a

compact json format actually.

.PP

Here is a list of all conversion functions:

.IP \[bu] 2

\f[C]ucl_object_toint\f[] - returns \f[C]int64_t\f[] of UCL object

.IP \[bu] 2

\f[C]ucl_object_todouble\f[] - returns \f[C]double\f[] of UCL object

.IP \[bu] 2

\f[C]ucl_object_toboolean\f[] - returns \f[C]bool\f[] of UCL object

.IP \[bu] 2

\f[C]ucl_object_tostring\f[] - returns \f[C]const\ char\ *\f[] of UCL

object (this string is NULL terminated)

.IP \[bu] 2

\f[C]ucl_object_tolstring\f[] - returns \f[C]const\ char\ *\f[] and

\f[C]size_t\f[] len of UCL object (string can be not NULL terminated)

.IP \[bu] 2

\f[C]ucl_object_tostring_forced\f[] - returns string representation of

any UCL object

.PP

Strings returned by these pointers are associated with the UCL object

and exist over its lifetime.

A caller should not free this memory.

.SH GENERATION FUNCTIONS

.PP

It is possible to generate UCL objects from C primitive types.

Moreover, libucl permits to create and modify complex UCL objects, such

as arrays or associative objects.

.SS ucl_object_new

.IP

.nf

\f[C]

ucl_object_t\ *\ ucl_object_new\ (void)

\f[]

.fi

.PP

Creates new object of type \f[C]UCL_NULL\f[].

This object should be released by caller.

.SS ucl_object_typed_new

.IP

.nf

\f[C]

ucl_object_t\ *\ ucl_object_typed_new\ (unsigned\ int\ type)

\f[]

.fi

.PP

Create an object of a specified type: - \f[C]UCL_OBJECT\f[] - UCL object

- key/value pairs - \f[C]UCL_ARRAY\f[] - UCL array - \f[C]UCL_INT\f[] -

integer number - \f[C]UCL_FLOAT\f[] - floating point number -

\f[C]UCL_STRING\f[] - NULL terminated string - \f[C]UCL_BOOLEAN\f[] -

boolean value - \f[C]UCL_TIME\f[] - time value (floating point number of

seconds) - \f[C]UCL_USERDATA\f[] - opaque userdata pointer (may be used

in macros) - \f[C]UCL_NULL\f[] - null value

.PP

This object should be released by caller.

.SS Primitive objects generation

.PP

Libucl provides the functions similar to inverse conversion functions

called with the specific C type: - \f[C]ucl_object_fromint\f[] -

converts \f[C]int64_t\f[] to UCL object - \f[C]ucl_object_fromdouble\f[]

- converts \f[C]double\f[] to UCL object -

\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 is 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 can be not 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 an UCL objects 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).

To iterate over an object, an array or a key with multiple values there

is a function \f[C]ucl_iterate_object\f[].

.SS ucl_iterate_object

.IP

.nf

\f[C]

ucl_object_t*\ ucl_iterate_object\ (ucl_object_t\ *obj,\ 

\ \ \ \ ucl_object_iter_t\ *iter,\ bool\ expand_values);

\f[]

.fi

.PP

This function accept 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 throught 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 are 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;

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

.SH VALIDATION FUNCTIONS

.PP

Currently, there is only one validation function called

\f[C]ucl_object_validate\f[].

It performs validation of object using the specified schema.

This function is defined as following:

.SS ucl_object_validate

.IP

.nf

\f[C]

bool\ ucl_object_validate\ (ucl_object_t\ *schema,

\ \ \ \ ucl_object_t\ *obj,\ struct\ ucl_schema_error\ *err);

\f[]

.fi

.PP

This function uses ucl object \f[C]schema\f[], that must be valid in

terms of \f[C]json-schema\f[] draft v4, to validate input object

\f[C]obj\f[].

If this function returns \f[C]true\f[] then validation procedure has

been succeed.

Otherwise, \f[C]false\f[] is returned and \f[C]err\f[] is set to a

specific value.

If caller set \f[C]err\f[] to NULL then this function does not set any

error just returning \f[C]false\f[].

Error is the structure defined as following:

.IP

.nf

\f[C]

struct\ ucl_schema_error\ {

\ \ \ \ enum\ ucl_schema_error_code\ code;\ \ \ \ /*\ error\ code\ */

\ \ \ \ char\ msg[128];\ \ \ \ \ \ \ \ \ \ \ \ \ \ /*\ error\ message\ */

\ \ \ \ ucl_object_t\ *obj;\ \ \ \ \ \ \ \ \ \ /*\ object\ where\ error\ occured\ */

};

\f[]

.fi

.PP

Caller may use \f[C]code\f[] field to get a numeric error code:

.IP

.nf

\f[C]

enum\ ucl_schema_error_code\ {

\ \ \ \ UCL_SCHEMA_OK\ =\ 0,\ \ \ \ \ \ \ \ \ \ /*\ no\ error\ */

\ \ \ \ UCL_SCHEMA_TYPE_MISMATCH,\ \ \ /*\ type\ of\ object\ is\ incorrect\ */

\ \ \ \ UCL_SCHEMA_INVALID_SCHEMA,\ \ /*\ schema\ is\ invalid\ */

\ \ \ \ UCL_SCHEMA_MISSING_PROPERTY,/*\ missing\ properties\ */

\ \ \ \ UCL_SCHEMA_CONSTRAINT,\ \ \ \ \ \ /*\ constraint\ found\ */

\ \ \ \ UCL_SCHEMA_MISSING_DEPENDENCY,\ /*\ missing\ dependency\ */

\ \ \ \ UCL_SCHEMA_UNKNOWN\ \ \ \ \ \ \ \ \ \ /*\ generic\ error\ */

};

\f[]

.fi

.PP

\f[C]msg\f[] is a stiring description of an error and \f[C]obj\f[] is an

object where error has been occurred.

Error object is not allocated by libucl, so there is no need to free it

after validation (a static object should thus be used).

.SH AUTHORS

Vsevolod Stakhov <vsevolod@highsecure.ru>.

% LIBUCL(5) Libucl manual

% Vsevolod Stakhov <vsevolod@highsecure.ru>

% March 20, 2014

# Name

**ucl_parser_new**, **ucl_parser_register_macro**, **ucl_parser_register_variable**, **ucl_parser_add_chunk**, **ucl_parser_add_string**, **ucl_parser_add_file**, **ucl_parser_get_object**, **ucl_parser_get_error**, **ucl_parser_free**, **ucl_pubkey_add**, **ucl_parser_set_filevars** - universal configuration library parser and utility functions

# Library

UCL library (libucl, -lucl)

	UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */

					@LIBCRYPTO_LIB@ \

					@LIBREGEX_LIB@ \

	ucl_object_t *cur, *otmp;

			DL_FOREACH_SAFE (elt->data, cur, otmp) {

				func (cur);

			}

#ifndef _WIN32

# define HAVE_REGEX_H

#endif

		struct ucl_schema_error *err,

		ucl_object_t *root);

	ucl_object_t *res = NULL;

#ifdef HAVE_REGEX_H

	ucl_object_t *elt;

#endif

 * Check dependencies for an object

 */

static bool

ucl_schema_validate_dependencies (ucl_object_t *deps,

		ucl_object_t *obj, struct ucl_schema_error *err,

		ucl_object_t *root)

{

	ucl_object_t *elt, *cur, *cur_dep;

	ucl_object_iter_t iter = NULL, piter;

	bool ret = true;

	while (ret && (cur = ucl_iterate_object (deps, &iter, true)) != NULL) {

		elt = ucl_object_find_key (obj, ucl_object_key (cur));

		if (elt != NULL) {

			/* Need to check dependencies */

			if (cur->type == UCL_ARRAY) {

				piter = NULL;

				while (ret && (cur_dep = ucl_iterate_object (cur, &piter, true)) != NULL) {

					if (ucl_object_find_key (obj, ucl_object_tostring (cur_dep)) == NULL) {

						ucl_schema_create_error (err, UCL_SCHEMA_MISSING_DEPENDENCY, elt,

								"dependency %s is missing for key %s",

								ucl_object_tostring (cur_dep), ucl_object_key (cur));

						ret = false;

						break;

					}

				}

			}

			else if (cur->type == UCL_OBJECT) {

				ret = ucl_schema_validate (cur, obj, true, err, root);

			}

		}

	}

	return ret;

}

/*

		ucl_object_t *obj, struct ucl_schema_error *err,

		ucl_object_t *root)

					ret = ucl_schema_validate (prop, found, true, err, root);

					ret = ucl_schema_validate (prop, found, true, err, root);

		else if (elt->type == UCL_OBJECT &&

				strcmp (ucl_object_key (elt), "dependencies") == 0) {

			ret = ucl_schema_validate_dependencies (elt, obj, err, root);

		}

						if (!ucl_schema_validate (additional_schema, elt, true, err, root)) {

#ifdef HAVE_REGEX_H

	regex_t re;

#endif

#ifdef HAVE_REGEX_H

		else if (elt->type == UCL_STRING &&

				strcmp (ucl_object_key (elt), "pattern") == 0) {

			if (regcomp (&re, ucl_object_tostring (elt),

					REG_EXTENDED | REG_NOSUB) != 0) {

				ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, elt,

						"cannot compile pattern %s", ucl_object_tostring (elt));

				ret = false;

				break;

			}

			if (regexec (&re, ucl_object_tostring (obj), 0, NULL, 0) != 0) {

				ucl_schema_create_error (err, UCL_SCHEMA_CONSTRAINT, obj,

						"string doesn't match regexp %s",

						ucl_object_tostring (elt));

				ret = false;

			}

			regfree (&re);

		}

#endif

		ucl_object_t *obj, struct ucl_schema_error *err,

		ucl_object_t *root)

						ret = ucl_schema_validate (it, found, false, err, root);

					ret = ucl_schema_validate (elt, it, false, err, root);

						if (!ucl_schema_validate (additional_schema, elt, false,

								err, root)) {

/*

 * Check a single ref component

 */

static ucl_object_t *

ucl_schema_resolve_ref_component (ucl_object_t *cur,

		const char *refc, int len,

		struct ucl_schema_error *err)

{

	ucl_object_t *res = NULL;

	char *err_str;

	int num, i;

	if (cur->type == UCL_OBJECT) {

		/* Find a key inside an object */

		res = ucl_object_find_keyl (cur, refc, len);

		if (res == NULL) {

			ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, cur,

					"reference %s is invalid, missing path component", refc);

			return NULL;

		}

	}

	else if (cur->type == UCL_ARRAY) {

		/* We must figure out a number inside array */

		num = strtoul (refc, &err_str, 10);

		if (err_str != NULL && *err_str != '/' && *err_str != '\0') {

			ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, cur,

					"reference %s is invalid, invalid item number", refc);

			return NULL;

		}

		res = cur->value.av;

		i = 0;

		while (res != NULL) {

			if (i == num) {

				break;

			}

			res = res->next;

		}

		if (res == NULL) {

			ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, cur,

					"reference %s is invalid, item number %d does not exist",

					refc, num);

			return NULL;

		}

	}

	else {

		ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, res,

				"reference %s is invalid, contains primitive object in the path",

				refc);

		return NULL;

	}

	return res;

}

/*

 * Find reference schema

 */

static ucl_object_t *

ucl_schema_resolve_ref (ucl_object_t *root, const char *ref,

		struct ucl_schema_error *err)

{

	const char *p, *c;

	ucl_object_t *res = NULL;

	if (ref[0] != '#') {

		ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, root,

				"reference %s is invalid, not started with #", ref);

		return NULL;

	}

	if (ref[1] == '/') {

		p = &ref[2];

	}

	else if (ref[1] == '\0') {

		return root;

	}

	else {

		ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, root,

				"reference %s is invalid, not started with #/", ref);

		return NULL;

	}

	c = p;

	res = root;

	while (*p != '\0') {

		if (*p == '/') {

			if (p - c == 0) {

				ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, res,

						"reference %s is invalid, empty path component", ref);

				return NULL;

			}

			/* Now we have some url part, so we need to figure out where we are */

			res = ucl_schema_resolve_ref_component (res, c, p - c, err);

			if (res == NULL) {

				return NULL;

			}

			c = p + 1;

		}

		p ++;

	}

	if (p - c != 0) {

		res = ucl_schema_resolve_ref_component (res, c, p - c, err);

	}

	if (res == NULL || res->type != UCL_OBJECT) {

		ucl_schema_create_error (err, UCL_SCHEMA_INVALID_SCHEMA, res,

				"reference %s is invalid, cannot find specified object",

				ref);

		return NULL;

	}

	return res;

}

static bool

ucl_schema_validate_values (ucl_object_t *schema, ucl_object_t *obj,

		struct ucl_schema_error *err)

{

	ucl_object_t *elt, *cur;

	int64_t constraint, i;

	elt = ucl_object_find_key (schema, "maxValues");

	if (elt != NULL && elt->type == UCL_INT) {

		constraint = ucl_object_toint (elt);

		cur = obj;

		i = 0;

		while (cur) {

			if (i > constraint) {

				ucl_schema_create_error (err, UCL_SCHEMA_CONSTRAINT, obj,

					"object has more values than defined: %ld",

					(long int)constraint);

				return false;

			}

			i ++;

			cur = cur->next;

		}

	}

	elt = ucl_object_find_key (schema, "minValues");

	if (elt != NULL && elt->type == UCL_INT) {

		constraint = ucl_object_toint (elt);

		cur = obj;

		i = 0;

		while (cur) {

			if (i >= constraint) {

				break;

			}

			i ++;

			cur = cur->next;

		}

		if (i < constraint) {

			ucl_schema_create_error (err, UCL_SCHEMA_CONSTRAINT, obj,

					"object has less values than defined: %ld",

					(long int)constraint);

			return false;

		}

	}

	return true;

}

		struct ucl_schema_error *err,

		ucl_object_t *root)

	if (try_array) {

		/*

		 * Special case for multiple values

		 */

		if (!ucl_schema_validate_values (schema, obj, err)) {

			return false;

		}

		LL_FOREACH (obj, cur) {

			if (!ucl_schema_validate (schema, cur, false, err, root)) {

				return false;

			}

		}

		return true;

	}

			ret = ucl_schema_validate (cur, obj, true, err, root);

			ret = ucl_schema_validate (cur, obj, true, err, root);

		ret = false;

				ret = ucl_schema_validate (cur, obj, true, err, root);

			else if (ucl_schema_validate (cur, obj, true, err, root)) {

		if (ucl_schema_validate (elt, obj, true, err, root)) {

	elt = ucl_object_find_key (schema, "$ref");

	if (elt != NULL) {

		cur = ucl_schema_resolve_ref (root, ucl_object_tostring (elt), err);

		if (cur == NULL) {

			return false;

		}

		if (!ucl_schema_validate (cur, obj, try_array, err, root)) {

			return false;

		}

	}

	elt = ucl_object_find_key (schema, "type");

		return ucl_schema_validate_object (schema, obj, err, root);

		return ucl_schema_validate_array (schema, obj, err, root);

	return ucl_schema_validate (schema, obj, true, err, schema);

typedef void (*ucl_object_dtor) (ucl_object_t *obj);

static void ucl_object_free_internal (ucl_object_t *obj, bool allow_rec,

		ucl_object_dtor dtor);

static void ucl_object_dtor_unref (ucl_object_t *obj);

ucl_object_dtor_free (ucl_object_t *obj)

	if (obj->trash_stack[UCL_TRASH_KEY] != NULL) {

		UCL_FREE (obj->hh.keylen, obj->trash_stack[UCL_TRASH_KEY]);

	}

	if (obj->trash_stack[UCL_TRASH_VALUE] != NULL) {

		UCL_FREE (obj->len, obj->trash_stack[UCL_TRASH_VALUE]);

	}

	UCL_FREE (sizeof (ucl_object_t), obj);

}

/*

 * This is a helper function that performs exactly the same as

 * `ucl_object_unref` but it doesn't iterate over elements allowing

 * to use it for individual elements of arrays and multiple values

 */

static void

ucl_object_dtor_unref_single (ucl_object_t *obj)

{

	if (obj != NULL) {

#ifdef HAVE_ATOMIC_BUILTINS

		unsigned int rc = __sync_sub_and_fetch (&obj->ref, 1);

		if (rc == 0) {

#else

		if (--obj->ref == 0) {

#endif

			ucl_object_free_internal (obj, false, ucl_object_dtor_unref);

	}

}

static void