1# LIBUCL
2
3[](https://travis-ci.org/vstakhov/libucl)
4
5**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
6
7- [Introduction](#introduction)
8- [Basic structure](#basic-structure)
9- [Improvements to the json notation](#improvements-to-the-json-notation)
10 - [General syntax sugar](#general-syntax-sugar)
11 - [Automatic arrays creation](#automatic-arrays-creation)
12 - [Named keys hierarchy](#named-keys-hierarchy)
13 - [Convenient numbers and booleans](#convenient-numbers-and-booleans)
14- [General improvements](#general-improvements)
15 - [Commments](#commments)
16 - [Macros support](#macros-support)
17 - [Variables support](#variables-support)
18 - [Multiline strings](#multiline-strings)
19- [Emitter](#emitter)
20- [Validation](#validation)
21- [Performance](#performance)
22- [Conclusion](#conclusion)
23
24## Introduction
25
26This document describes the main features and principles of the configuration
27language called `UCL` - universal configuration language.
28
29If you are looking for the libucl API documentation you can find it at [this page](doc/api.md).
30
31## Basic structure
--- 248 unchanged lines hidden (view full) ---
280
281Each UCL object can be serialized to one of the three supported formats:
282
283* `JSON` - canonic json notation (with spaces indented structure);
284* `Compacted JSON` - compact json notation (without spaces or newlines);
285* `Configuration` - nginx like notation;
286* `YAML` - yaml inlined notation.
287
288## Validation
289
290UCL 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, schema definition can be in UCL format instead of JSON that sinplifies 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 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 input is validated properly.
291
292## Performance
293
294Are UCL parser and emitter fast enough? Well, there are some numbers.
295I got a 19Mb file that consist of ~700 thousands lines of json (obtained via
296http://www.json-generator.com/). Then I checked jansson library that performs json
297parsing and emitting and compared it with UCL. Here are results:
298
299```
--- 28 unchanged lines hidden ---
2
3[](https://travis-ci.org/vstakhov/libucl)
4
5**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
6
7- [Introduction](#introduction)
8- [Basic structure](#basic-structure)
9- [Improvements to the json notation](#improvements-to-the-json-notation)
10 - [General syntax sugar](#general-syntax-sugar)
11 - [Automatic arrays creation](#automatic-arrays-creation)
12 - [Named keys hierarchy](#named-keys-hierarchy)
13 - [Convenient numbers and booleans](#convenient-numbers-and-booleans)
14- [General improvements](#general-improvements)
15 - [Commments](#commments)
16 - [Macros support](#macros-support)
17 - [Variables support](#variables-support)
18 - [Multiline strings](#multiline-strings)
19- [Emitter](#emitter)
20- [Validation](#validation)
21- [Performance](#performance)
22- [Conclusion](#conclusion)
23
24## Introduction
25
26This document describes the main features and principles of the configuration
27language called `UCL` - universal configuration language.
28
29If you are looking for the libucl API documentation you can find it at [this page](doc/api.md).
30
31## Basic structure
--- 248 unchanged lines hidden (view full) ---
280
281Each UCL object can be serialized to one of the three supported formats:
282
283* `JSON` - canonic json notation (with spaces indented structure);
284* `Compacted JSON` - compact json notation (without spaces or newlines);
285* `Configuration` - nginx like notation;
286* `YAML` - yaml inlined notation.
287
288## Validation
289
290UCL 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, schema definition can be in UCL format instead of JSON that sinplifies 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 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 input is validated properly.
291
292## Performance
293
294Are UCL parser and emitter fast enough? Well, there are some numbers.
295I got a 19Mb file that consist of ~700 thousands lines of json (obtained via
296http://www.json-generator.com/). Then I checked jansson library that performs json
297parsing and emitting and compared it with UCL. Here are results:
298
299```
--- 28 unchanged lines hidden ---