diff options
author | Baptiste Daroussin <bapt@FreeBSD.org> | 2014-11-29 00:33:10 +0000 |
---|---|---|
committer | Baptiste Daroussin <bapt@FreeBSD.org> | 2014-11-29 00:33:10 +0000 |
commit | 1eea90048f8f0e6360171d254c1f60f41a090814 (patch) | |
tree | 4aae5869b82bf4066989c1dce79dc9f06fa9526b /README.md | |
parent | 8f2b0cccb4a7a7fe296db2f59cb6cdbfbec9291b (diff) | |
download | src-1eea90048f8f0e6360171d254c1f60f41a090814.tar.gz src-1eea90048f8f0e6360171d254c1f60f41a090814.zip |
Update libucl to latest versionvendor/libucl/20141129
Notes
Notes:
svn path=/vendor/libucl/dist/; revision=275221
svn path=/vendor/libucl/20141129/; revision=275222; tag=vendor/libucl/20141129
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 58 |
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 +options: -Public keys which are used for the last command are specified by the concrete UCL user. +```nginx +.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: + +```nginx +.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 |