# Version history

## Libucl 0.5

- Streamline emitter has been added, so it is now possible to output partial `ucl` objects

- Emitter now is more flexible due to emitter_context structure

m4_define([med_ver], [5])

m4_define([min_ver], [0])

m4_define([so_version], [2:0:0])

- `JSON` - valid json format (can possibly lose some original data, such as implicit arrays)

- `Config` - human-readable configuration format (lossless)

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.

Load file `filename` and parse it with the specified `parser`. This function uses `mmap` call to load file, therefore, it should not be `shrunk` during parsing. Otherwise, `libucl` can cause memory corruption and terminate the calling application. This function is also used by the internal handler of `include` macro, hence, this macro has the same limitation.

	printf ("Error occurred: %s\n", ucl_parser_get_error (parser));

efficient and zero-copy output of libucl objects. Libucl uses the following structure to support this feature:

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:

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 compact json format actually.

- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string does not need to be NULL terminated)

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_fromstring` - converts `const char *` to UCL object (this string should be NULL terminated)

- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string does not need to be NULL terminated)

This function is used to convert a string `str` of size `len` to a UCL object applying `flags` conversions. If `len` is equal to zero then a `str` is assumed as NULL-terminated. This function supports the following flags (a set of flags can be specified using logical `OR` operation):

This function accepts opaque iterator pointer `iter`. In the first call this iterator *must* be initialized to `NULL`. Iterator is changed by this function call. `ucl_iterate_object` returns the next UCL object in the compound object `obj` or `NULL` 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 `obj` should not be changed during the iteration process as well. `expand_values` flag speicifies whether `ucl_iterate_object` should expand keys with multiple values. The general rule is that if you need to iterate through the *object* or *explicit array*, then you always need to set this flag to `true`. However, if you get some key in the object and want to extract all its values then you should set `expand_values` to `false`. 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 `top` is `UCL_OBJECT` in this example):

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 a caller sets `err` to NULL then this function does not set any error just returning `false`. Error is the structure defined as following:

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

`msg` is a string description of an error and `obj` is an object where error has 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" "3" "July 26, 2014" "Libucl manual" ""

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

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

Allow creation of \f[C]ucl\f[] objects from C types and creating of

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

\ \ \ \ printf\ ("Error\ occurred:\ %s\\n",\ ucl_parser_get_error\ (parser));

allowing efficient and zero\-copy output of libucl objects.

such as strings, numbers, or boolean values.

For objects, arrays, booleans and numeric types this function performs

emitting to a compact json format actually.

\f[C]size_t\f[] len of UCL object (string does not need to be NULL

terminated)

Moreover, libucl allows creation and modifying complex UCL objects, such

\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)

\f[C]len\f[] to a UCL object applying \f[C]flags\f[] conversions.

This function accepts opaque iterator pointer \f[C]iter\f[].

The general rule is that if you need to iterate through the

Mixing of iteration types is not permitted since the iterator is set

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

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

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

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

object where error has occurred.

% LIBUCL(3) Libucl manual

% July 26, 2014

				/* Skip any spaces */

				while (p < chunk->end && ucl_test_character (*p,

						UCL_CHARACTER_WHITESPACE_UNSAFE)) {

					ucl_chunk_skipc (chunk, p);

				}

		speed.test \

		streamline.test

test_streamline_SOURCES = test_streamline.c

test_streamline_LDADD = $(common_test_ldadd)

test_streamline_CFLAGS = $(common_test_cflags)

check_PROGRAMS = test_basic test_speed test_generate test_schema test_streamline

   {"key": "value"}

key = "value";

key1 = "test string";

key2 = "test \\nstring";

key3 = "  test string    \n";

key4 [

    10,

    10.100000,

    9.999000,

]

#!/bin/sh

PROG=${TEST_BINARY_DIR}/test_streamline

$PROG ${TEST_OUT_DIR}/streamline.out

diff -s ${TEST_OUT_DIR}/streamline.out ${TEST_DIR}/streamline.res -u 2>/dev/null

if [ $? -ne 0 ] ; then

	rm ${TEST_OUT_DIR}/streamline.out

	echo "Test: streamline.res output missmatch"

	exit 1

fi

rm ${TEST_OUT_DIR}/streamline.out

	int ret = 0, inlen, opt, json = 0, compact = 0, yaml = 0;

	while ((opt = getopt(argc, argv, "jcy")) != -1) {

		case 'c':

			compact = 1;

			break;

		case 'y':

			yaml = 1;

			break;

			fprintf (stderr, "Usage: %s [-jcy] [in] [out]\n",

		if (compact) {

			emitted = ucl_object_emit (obj, UCL_EMIT_JSON_COMPACT);

		}

		else {

			emitted = ucl_object_emit (obj, UCL_EMIT_JSON);

		}

	}

	else if (yaml) {

		emitted = ucl_object_emit (obj, UCL_EMIT_YAML);

		if (compact) {

			emitted = ucl_object_emit (obj, UCL_EMIT_JSON_COMPACT);

		}

		else {

			emitted = ucl_object_emit (obj, UCL_EMIT_JSON);

		}

	}

	else if (yaml) {

		emitted = ucl_object_emit (obj, UCL_EMIT_YAML);

/* Copyright (c) 2013, Vsevolod Stakhov

 * All rights reserved.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions are met:

 *       * Redistributions of source code must retain the above copyright

 *         notice, this list of conditions and the following disclaimer.

 *       * Redistributions in binary form must reproduce the above copyright

 *         notice, this list of conditions and the following disclaimer in the

 *         documentation and/or other materials provided with the distribution.

 *

 * THIS SOFTWARE IS PROVIDED ''AS IS'' AND ANY

 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

 * DISCLAIMED. IN NO EVENT SHALL AUTHOR BE LIABLE FOR ANY

 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

#include <stdio.h>

#include <errno.h>

#include <assert.h>

#include "ucl.h"

int

main (int argc, char **argv)

{

	ucl_object_t *obj, *cur, *ar;

	FILE *out;

	const char *fname_out = NULL;

	struct ucl_emitter_context *ctx;

	struct ucl_emitter_functions *f;

	int ret = 0;

	switch (argc) {

	case 2:

		fname_out = argv[1];

		break;

	}

	if (fname_out != NULL) {

		out = fopen (fname_out, "w");

		if (out == NULL) {

			exit (-errno);

		}

	}

	else {

		out = stdout;

	}

	obj = ucl_object_typed_new (UCL_OBJECT);

	/* Create some strings */

	cur = ucl_object_fromstring_common ("  test string    ", 0, UCL_STRING_TRIM);

	ucl_object_insert_key (obj, cur, "key1", 0, false);

	cur = ucl_object_fromstring_common ("  test \nstring\n    ", 0, UCL_STRING_TRIM | UCL_STRING_ESCAPE);

	ucl_object_insert_key (obj, cur, "key2", 0, false);

	cur = ucl_object_fromstring_common ("  test string    \n", 0, 0);

	ucl_object_insert_key (obj, cur, "key3", 0, false);

	f = ucl_object_emit_file_funcs (out);

	ctx = ucl_object_emit_streamline_new (obj, UCL_EMIT_CONFIG, f);

	assert (ctx != NULL);

	/* Array of numbers */

	ar = ucl_object_typed_new (UCL_ARRAY);

	ar->key = "key4";

	ar->keylen = sizeof ("key4") - 1;

	ucl_object_emit_streamline_start_container (ctx, ar);

	cur = ucl_object_fromint (10);

	ucl_object_emit_streamline_add_object (ctx, cur);

	cur = ucl_object_fromdouble (10.1);

	ucl_object_emit_streamline_add_object (ctx, cur);

	cur = ucl_object_fromdouble (9.999);

	ucl_object_emit_streamline_add_object (ctx, cur);

	ucl_object_emit_streamline_end_container (ctx);

	ucl_object_emit_streamline_finish (ctx);

	ucl_object_emit_funcs_free (f);

	ucl_object_unref (obj);

	fclose (out);

	return ret;

}