path: root/README.md
diff options
authorBaptiste Daroussin <bapt@FreeBSD.org>2014-11-29 00:33:10 +0000
committerBaptiste Daroussin <bapt@FreeBSD.org>2014-11-29 00:33:10 +0000
commit1eea90048f8f0e6360171d254c1f60f41a090814 (patch)
tree4aae5869b82bf4066989c1dce79dc9f06fa9526b /README.md
parent8f2b0cccb4a7a7fe296db2f59cb6cdbfbec9291b (diff)
Update libucl to latest versionvendor/libucl/20141129
Notes: svn path=/vendor/libucl/dist/; revision=275221 svn path=/vendor/libucl/20141129/; revision=275222; tag=vendor/libucl/20141129
Diffstat (limited to 'README.md')
1 files changed, 50 insertions, 8 deletions
diff --git a/README.md b/README.md
index b6353d10ae27..235cfb6595df 100644
--- a/README.md
+++ b/README.md
@@ -223,15 +223,57 @@ UCL supports external macros both multiline and single line ones:
-There are two internal macros provided by UCL:
-* `include` - read a file `/path/to/file` or an url `http://example.com/file` and include it to the current place of
-UCL configuration;
-* `try\_include` - try to read a file or url and include it but do not create a fatal error if a file or url is not accessible;
-* `includes` - read a file or an url like the previous macro, but fetch and check the signature file (which is obtained
-by `.sig` suffix appending).
+Moreover, each macro can accept an optional list of arguments in braces. These
+arguments themselves are the UCL object that is parsed and passed to a macro as
-Public keys which are used for the last command are specified by the concrete UCL user.
+.macro(param=value) "something";
+.macro(param={key=value}) "something";
+.macro(.include "params.conf") "something";
+.macro(#this is multiline macro
+param = [value1, value2]) "something";
+.macro(key="()") "something";
+UCL also provide a convenient `include` macro to load content from another files
+to the current UCL object. This macro accepts either path to file:
+.include "/full/path.conf"
+.include "./relative/path.conf"
+.include "${CURDIR}/path.conf"
+or URL (if ucl is built with url support provided by either `libcurl` or `libfetch`):
+ .include "http://example.com/file.conf"
+`.include` macro supports a set of options:
+* `try` (default: **false**) - if this option is `true` than UCL treats errors on loading of
+this file as non-fatal. For example, such a file can be absent but it won't stop the parsing
+of the top-level document.
+* `sign` (default: **false**) - if this option is `true` UCL loads and checks the signature for
+a file from path named `<FILEPATH>.sig`. Trusted public keys should be provided for UCL API after
+parser is created but before any configurations are parsed.
+* `glob` (default: **false**) - if this option is `true` UCL treats the filename as GLOB pattern and load
+all files that matches the specified pattern (normally the format of patterns is defined in `glob` manual page
+for your operating system). This option is meaningless for URL includes.
+* `url` (default: **true**) - allow URL includes.
+* `priority` (default: 0) - specify priority for the include (see below).
+Priorities are used by UCL parser to manage the policy of objects rewriting during including other files
+as following:
+* If we have two objects with the same priority then we form an implicit array
+* If a new object has bigger priority then we overwrite an old one
+* If a new object has lower priority then we ignore it
+By default, the priority of top-level object is set to zero (lowest priority). Currently,
+you can define up to 16 priorities (from 0 to 15). Includes with bigger priorities will
+rewrite keys from the objects with lower priorities as specified by the policy.
### Variables support
@@ -317,7 +359,7 @@ ucl: emitted compact json in 0.0991 seconds
ucl: emitted yaml in 0.1354 seconds
-You can do your own benchmarks by running `make test` in libucl top directory.
+You can do your own benchmarks by running `make check` in libucl top directory.
## Conclusion