Lines Matching +full:2 +full:c

16 \f[C]#include\ <ucl.h>\f[]
19 Libucl is a parser and \f[C]C\f[] API to parse and generate \f[C]ucl\f[]
24 Used to parse \f[C]ucl\f[] files and provide interface to extract
25 \f[C]ucl\f[] object.
26 Currently, \f[C]libucl\f[] can parse only full \f[C]ucl\f[] documents,
28 it is impossible to use \f[C]libucl\f[] as a streaming parser.
32 Convert \f[C]ucl\f[] objects to some textual or binary representation.
34 .IP \[bu] 2
35 \f[C]JSON\f[] \- valid json format (can possibly lose some original
37 .IP \[bu] 2
38 \f[C]Config\f[] \- human\-readable configuration format (lossless)
39 .IP \[bu] 2
40 \f[C]YAML\f[] \- embedded yaml format (has the same limitations as
41 \f[C]json\f[] output)
44 Help to convert \f[C]ucl\f[] objects to C types.
45 These functions are used to convert \f[C]ucl_object_t\f[] to C primitive
49 Allow creation of \f[C]ucl\f[] objects from C types and creating of
50 complex \f[C]ucl\f[] objects, such as hashes or arrays from primitive
51 \f[C]ucl\f[] objects, such as numbers or strings.
54 Iterate over \f[C]ucl\f[] complex objects or over a chain of values, for
59 Validation functions are used to validate some object \f[C]obj\f[] using
60 json\-schema compatible object \f[C]schema\f[].
64 Provide basic utilities to manage \f[C]ucl\f[] objects: creating,
68 Parser functions operates with \f[C]struct\ ucl_parser\f[].
72 \f[C]
78 .IP \[bu] 2
79 \f[C]UCL_PARSER_KEY_LOWERCASE\f[] \- lowercase keys parsed
80 .IP \[bu] 2
81 \f[C]UCL_PARSER_ZEROCOPY\f[] \- try to use zero\-copy mode when reading
84 .IP \[bu] 2
85 \f[C]UCL_PARSER_NO_TIME\f[] \- treat time values as strings without
90 \f[C]
96 Register new macro with name .\f[C]macro\f[] parsed by handler
97 \f[C]handler\f[] that accepts opaque data pointer \f[C]ud\f[].
101 \f[C]
107 Handler function accepts macro text \f[C]data\f[] of length \f[C]len\f[]
108 and the opaque pointer \f[C]ud\f[].
109 If macro is parsed successfully the handler should return \f[C]true\f[].
110 \f[C]false\f[] indicates parsing failure and the parser can be
115 \f[C]
121 Register new variable $\f[C]var\f[] that should be replaced by the
122 parser to the \f[C]value\f[] string.
126 \f[C]
132 Add new text chunk with \f[C]data\f[] of length \f[C]len\f[] to the
134 At the moment, \f[C]libucl\f[] parser is not a streamlined parser and
139 \f[C]
147 \f[C]
156 \f[C]
162 This function acts exactly like \f[C]ucl_parser_add_chunk\f[] does but
163 if \f[C]len\f[] argument is zero, then the string \f[C]data\f[] must be
164 zero\-terminated and the actual length is calculated up to \f[C]\\0\f[]
169 \f[C]
175 Load file \f[C]filename\f[] and parse it with the specified
176 \f[C]parser\f[].
177 This function uses \f[C]mmap\f[] call to load file, therefore, it should
178 not be \f[C]shrunk\f[] during parsing.
179 Otherwise, \f[C]libucl\f[] can cause memory corruption and terminate the
181 This function is also used by the internal handler of \f[C]include\f[]
186 \f[C]
191 If the \f[C]ucl\f[] data has been parsed correctly this function returns
193 Otherwise, this function returns the \f[C]NULL\f[] pointer.
194 The reference count for \f[C]ucl\f[] object returned is increased by
196 \f[C]ucl_object_unref\f[] to free object after usage.
200 \f[C]
206 If no error occurred during parsing a \f[C]NULL\f[] object is returned.
211 \f[C]
218 function \f[C]ucl_parser_get_object\f[] was called previously then the
223 \f[C]
229 This function adds a public key from text blob \f[C]key\f[] of length
230 \f[C]len\f[] to the \f[C]parser\f[] object.
231 This public key should be in the \f[C]PEM\f[] format and can be used by
232 \f[C]\&.includes\f[] macro for checking signatures of files included.
233 \f[C]Openssl\f[] support should be enabled to make this function
236 due to format error) or \f[C]openssl\f[] was not linked to
237 \f[C]libucl\f[] then this function returns \f[C]false\f[].
241 \f[C]
247 Add the standard file variables to the \f[C]parser\f[] based on the
248 \f[C]filename\f[] specified:
249 .IP \[bu] 2
250 \f[C]$FILENAME\f[] \- a filename of \f[C]ucl\f[] input
251 .IP \[bu] 2
252 \f[C]$CURDIR\f[] \- a current directory of the input
254 For example, if a \f[C]filename\f[] param is
255 \f[C]\&../something.conf\f[] then the variables will have the following
257 .IP \[bu] 2
258 \f[C]$FILENAME\f[] \- "../something.conf"
259 .IP \[bu] 2
260 \f[C]$CURDIR\f[] \- ".."
262 if \f[C]need_expand\f[] parameter is \f[C]true\f[] then all relative
263 paths are expanded using \f[C]realpath\f[] call.
264 In this example if \f[C]\&..\f[] is \f[C]/etc/dir\f[] then variables
266 .IP \[bu] 2
267 \f[C]$FILENAME\f[] \- "/etc/something.conf"
268 .IP \[bu] 2
269 \f[C]$CURDIR\f[] \- "/etc"
272 The following example loads, parses and extracts \f[C]ucl\f[] object
273 from stdin using \f[C]libucl\f[] parser functions (the length of input
277 \f[C]
312 .IP \[bu] 2
313 configuration (\f[C]UCL_EMIT_CONFIG\f[]) \- nginx like human readable
316 .IP \[bu] 2
317 compact json: \f[C]UCL_EMIT_JSON_COMPACT\f[] \- single line valid json
319 .IP \[bu] 2
320 formatted json: \f[C]UCL_EMIT_JSON\f[] \- pretty formatted JSON with
322 .IP \[bu] 2
323 compact yaml: \f[C]UCL_EMIT_YAML\f[] \- compact YAML output
330 \f[C]
333 \ \ \ \ int\ (*ucl_emitter_append_character)\ (unsigned\ char\ c,\ size_t\ nchars,\ void\ *ud);
347 .IP \[bu] 2
348 \f[C]ucl_emitter_append_character\f[] \- a function that is called to
349 append \f[C]nchars\f[] characters equal to \f[C]c\f[]
350 .IP \[bu] 2
351 \f[C]ucl_emitter_append_len\f[] \- used to append a string of length
352 \f[C]len\f[] starting from pointer \f[C]str\f[]
353 .IP \[bu] 2
354 \f[C]ucl_emitter_append_int\f[] \- this function applies to integer
356 .IP \[bu] 2
357 \f[C]ucl_emitter_append_double\f[] \- this function is intended to
361 \f[C]UCL\f[] objects to different structures or streams.
367 \f[C]
373 \f[C]obj\f[] and fill it with the textual representation of the object
374 \f[C]obj\f[] according to style \f[C]emit_type\f[].
379 \f[C]
386 accepts the additional argument \f[C]emitter\f[] that defines the
389 emitters (including C++ ones, for example).
395 .IP \[bu] 2
398 .IP \[bu] 2
403 Also there is a single \f[C]ucl_object_tostring_forced\f[] function that
410 .IP \[bu] 2
411 \f[C]ucl_object_toint\f[] \- returns \f[C]int64_t\f[] of UCL object
412 .IP \[bu] 2
413 \f[C]ucl_object_todouble\f[] \- returns \f[C]double\f[] of UCL object
414 .IP \[bu] 2
415 \f[C]ucl_object_toboolean\f[] \- returns \f[C]bool\f[] of UCL object
416 .IP \[bu] 2
417 \f[C]ucl_object_tostring\f[] \- returns \f[C]const\ char\ *\f[] of UCL
419 .IP \[bu] 2
420 \f[C]ucl_object_tolstring\f[] \- returns \f[C]const\ char\ *\f[] and
421 \f[C]size_t\f[] len of UCL object (string does not need to be NULL
423 .IP \[bu] 2
424 \f[C]ucl_object_tostring_forced\f[] \- returns string representation of
432 It is possible to generate UCL objects from C primitive types.
438 \f[C]
443 Creates new object of type \f[C]UCL_NULL\f[].
448 \f[C]
453 Create an object of a specified type: \- \f[C]UCL_OBJECT\f[] \- UCL
454 object \- key/value pairs \- \f[C]UCL_ARRAY\f[] \- UCL array \-
455 \f[C]UCL_INT\f[] \- integer number \- \f[C]UCL_FLOAT\f[] \- floating
456 point number \- \f[C]UCL_STRING\f[] \- NULL terminated string \-
457 \f[C]UCL_BOOLEAN\f[] \- boolean value \- \f[C]UCL_TIME\f[] \- time value
458 (floating point number of seconds) \- \f[C]UCL_USERDATA\f[] \- opaque
459 userdata pointer (may be used in macros) \- \f[C]UCL_NULL\f[] \- null
466 called with the specific C type: \- \f[C]ucl_object_fromint\f[] \-
467 converts \f[C]int64_t\f[] to UCL object \-
468 \f[C]ucl_object_fromdouble\f[] \- converts \f[C]double\f[] to UCL object
469 \- \f[C]ucl_object_fromboolean\f[] \- converts \f[C]bool\f[] to UCL
470 object \- \f[C]ucl_object_fromstring\f[] \- converts
471 \f[C]const\ char\ *\f[] to UCL object (this string should be NULL
472 terminated) \- \f[C]ucl_object_fromlstring\f[] \- converts
473 \f[C]const\ char\ *\f[] and \f[C]size_t\f[] len to UCL object (string
478 \f[C]ucl_object_fromstring_common\f[].
482 \f[C]
488 This function is used to convert a string \f[C]str\f[] of size
489 \f[C]len\f[] to a UCL object applying \f[C]flags\f[] conversions.
490 If \f[C]len\f[] is equal to zero then a \f[C]str\f[] is assumed as
493 specified using logical \f[C]OR\f[] operation):
494 .IP \[bu] 2
495 \f[C]UCL_STRING_ESCAPE\f[] \- perform JSON escape
496 .IP \[bu] 2
497 \f[C]UCL_STRING_TRIM\f[] \- trim leading and trailing whitespaces
498 .IP \[bu] 2
499 \f[C]UCL_STRING_PARSE_BOOLEAN\f[] \- parse passed string and detect
501 .IP \[bu] 2
502 \f[C]UCL_STRING_PARSE_INT\f[] \- parse passed string and detect integer
504 .IP \[bu] 2
505 \f[C]UCL_STRING_PARSE_DOUBLE\f[] \- parse passed string and detect
507 .IP \[bu] 2
508 \f[C]UCL_STRING_PARSE_TIME\f[] \- parse time values as floating point
510 .IP \[bu] 2
511 \f[C]UCL_STRING_PARSE_NUMBER\f[] \- parse passed string and detect
513 .IP \[bu] 2
514 \f[C]UCL_STRING_PARSE\f[] \- parse passed string (and detect booleans,
516 .IP \[bu] 2
517 \f[C]UCL_STRING_PARSE_BYTES\f[] \- assume that numeric multipliers are
518 in bytes notation, for example \f[C]10k\f[] means \f[C]10*1024\f[] and
519 not \f[C]10*1000\f[] as assumed without this flag
522 \f[C]UCL_STRING\f[].
532 \f[C]ucl_iterate_object\f[] and the proposed interface of safe
537 \f[C]
543 This function accepts opaque iterator pointer \f[C]iter\f[].
545 \f[C]NULL\f[].
547 \f[C]ucl_iterate_object\f[] returns the next UCL object in the compound
548 object \f[C]obj\f[] or \f[C]NULL\f[] if all objects have been iterated.
552 The object \f[C]obj\f[] should not be changed during the iteration
554 \f[C]expand_values\f[] flag speicifies whether
555 \f[C]ucl_iterate_object\f[] should expand keys with multiple values.
558 this flag to \f[C]true\f[].
560 values then you should set \f[C]expand_values\f[] to \f[C]false\f[].
564 (assuming that \f[C]top\f[] is \f[C]UCL_OBJECT\f[] in this example):
567 \f[C]
592 .IP "2." 3
599 \f[C]
601 key\ =\ [2,\ 3,\ 4];
605 1,\ 2,\ 3,\ 4
609 1,\ [2,\ 3,\ 4]
614 .IP \[bu] 2
615 \f[C]ucl_object_iterate_new\f[] \- creates new safe iterator.
616 .IP \[bu] 2
617 \f[C]ucl_object_iterate_reset\f[] \- resets iterator to a new object.
618 .IP \[bu] 2
619 \f[C]ucl_object_iterate_safe\f[] \- safely iterate the object inside
622 Therefore it returns \f[C]NULL\f[] either while trying to access item
625 .IP \[bu] 2
626 \f[C]ucl_object_iter_chk_excpn\f[] \- check if the last call to
627 \f[C]ucl_object_iterate_safe\f[] ended up in unrecoverable exception
628 (e.g. \f[C]ENOMEM\f[]).
629 .IP \[bu] 2
630 \f[C]ucl_object_iterate_free\f[] \- free memory associated with the safe
635 An assert is likely generated if you use uninitialized or \f[C]NULL\f[]
639 \f[C]
672 \f[C]ucl_object_validate\f[].
678 \f[C]
684 This function uses ucl object \f[C]schema\f[], that must be valid in
685 terms of \f[C]json\-schema\f[] draft v4, to validate input object
686 \f[C]obj\f[].
687 If this function returns \f[C]true\f[] then validation procedure has
689 Otherwise, \f[C]false\f[] is returned and \f[C]err\f[] is set to a
691 If a caller sets \f[C]err\f[] to NULL then this function does not set
692 any error just returning \f[C]false\f[].
696 \f[C]
705 Caller may use \f[C]code\f[] field to get a numeric error code:
708 \f[C]
721 \f[C]msg\f[] is a string description of an error and \f[C]obj\f[] is an