diff options
Diffstat (limited to 'include/ucl.h')
-rw-r--r-- | include/ucl.h | 170 |
1 files changed, 141 insertions, 29 deletions
diff --git a/include/ucl.h b/include/ucl.h index 82a1fd1880f39..024f5dd8fd357 100644 --- a/include/ucl.h +++ b/include/ucl.h @@ -107,7 +107,8 @@ typedef enum ucl_error { UCL_ENESTED, /**< Input has too many recursion levels */ UCL_EMACRO, /**< Error processing a macro */ UCL_EINTERNAL, /**< Internal unclassified error */ - UCL_ESSL /**< SSL error */ + UCL_ESSL, /**< SSL error */ + UCL_EMERGE /**< A merge error occured */ } ucl_error_t; /** @@ -147,11 +148,13 @@ typedef enum ucl_emitter { * UCL still has to perform copying implicitly. */ typedef enum ucl_parser_flags { - UCL_PARSER_DEFAULT = 0x0, /**< No special flags */ - UCL_PARSER_KEY_LOWERCASE = 0x1, /**< Convert all keys to lower case */ - UCL_PARSER_ZEROCOPY = 0x2, /**< Parse input in zero-copy mode if possible */ - UCL_PARSER_NO_TIME = 0x4, /**< Do not parse time and treat time values as strings */ - UCL_PARSER_NO_IMPLICIT_ARRAYS = 0x8 /** Create explicit arrays instead of implicit ones */ + UCL_PARSER_DEFAULT = 0, /**< No special flags */ + UCL_PARSER_KEY_LOWERCASE = (1 << 0), /**< Convert all keys to lower case */ + UCL_PARSER_ZEROCOPY = (1 << 1), /**< Parse input in zero-copy mode if possible */ + UCL_PARSER_NO_TIME = (1 << 2), /**< Do not parse time and treat time values as strings */ + UCL_PARSER_NO_IMPLICIT_ARRAYS = (1 << 3), /** Create explicit arrays instead of implicit ones */ + UCL_PARSER_SAVE_COMMENTS = (1 << 4), /** Save comments in the parser context */ + UCL_PARSER_DISABLE_MACRO = (1 << 5) /** Treat macros as comments */ } ucl_parser_flags_t; /** @@ -159,17 +162,17 @@ typedef enum ucl_parser_flags { */ typedef enum ucl_string_flags { UCL_STRING_RAW = 0x0, /**< Treat string as is */ - UCL_STRING_ESCAPE = 0x1, /**< Perform JSON escape */ - UCL_STRING_TRIM = 0x2, /**< Trim leading and trailing whitespaces */ - UCL_STRING_PARSE_BOOLEAN = 0x4, /**< Parse passed string and detect boolean */ - UCL_STRING_PARSE_INT = 0x8, /**< Parse passed string and detect integer number */ - UCL_STRING_PARSE_DOUBLE = 0x10, /**< Parse passed string and detect integer or float number */ - UCL_STRING_PARSE_TIME = 0x20, /**< Parse time strings */ + UCL_STRING_ESCAPE = (1 << 0), /**< Perform JSON escape */ + UCL_STRING_TRIM = (1 << 1), /**< Trim leading and trailing whitespaces */ + UCL_STRING_PARSE_BOOLEAN = (1 << 2), /**< Parse passed string and detect boolean */ + UCL_STRING_PARSE_INT = (1 << 3), /**< Parse passed string and detect integer number */ + UCL_STRING_PARSE_DOUBLE = (1 << 4), /**< Parse passed string and detect integer or float number */ + UCL_STRING_PARSE_TIME = (1 << 5), /**< Parse time strings */ UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME, /**< Parse passed string and detect number */ UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**< Parse passed string (and detect booleans and numbers) */ - UCL_STRING_PARSE_BYTES = 0x40 /**< Treat numbers as bytes */ + UCL_STRING_PARSE_BYTES = (1 << 6) /**< Treat numbers as bytes */ } ucl_string_flags_t; /** @@ -286,10 +289,12 @@ UCL_EXTERN ucl_object_t* ucl_object_new_full (ucl_type_t type, unsigned priority /** * Create new object with userdata dtor * @param dtor destructor function + * @param emitter emitter for userdata + * @param ptr opaque pointer * @return new object */ UCL_EXTERN ucl_object_t* ucl_object_new_userdata (ucl_userdata_dtor dtor, - ucl_userdata_emitter emitter) UCL_WARN_UNUSED_RESULT; + ucl_userdata_emitter emitter, void *ptr) UCL_WARN_UNUSED_RESULT; /** * Perform deep copy of an object copying everything @@ -306,6 +311,21 @@ UCL_EXTERN ucl_object_t * ucl_object_copy (const ucl_object_t *other) UCL_EXTERN ucl_type_t ucl_object_type (const ucl_object_t *obj); /** + * Converts ucl object type to its string representation + * @param type type of object + * @return constant string describing type + */ +UCL_EXTERN const char * ucl_object_type_to_string (ucl_type_t type); + +/** + * Converts string that represents ucl type to real ucl type enum + * @param input C string with name of type + * @param res resulting target + * @return true if `input` is a name of type stored in `res` + */ +UCL_EXTERN bool ucl_object_string_to_type (const char *input, ucl_type_t *res); + +/** * Convert any string to an ucl object making the specified transformations * @param str fixed size or NULL terminated string * @param len length (if len is zero, than str is treated as NULL terminated) @@ -642,8 +662,9 @@ UCL_EXTERN const char* ucl_object_tolstring (const ucl_object_t *obj, size_t *tl * @param key key to search * @return object matching the specified key or NULL if key was not found */ -UCL_EXTERN const ucl_object_t* ucl_object_find_key (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t* ucl_object_lookup (const ucl_object_t *obj, const char *key); +#define ucl_object_find_key ucl_object_lookup /** * Return object identified by a key in the specified object, if the first key is @@ -655,8 +676,9 @@ UCL_EXTERN const ucl_object_t* ucl_object_find_key (const ucl_object_t *obj, * @param ... list of alternative keys to search (NULL terminated) * @return object matching the specified key or NULL if key was not found */ -UCL_EXTERN const ucl_object_t* ucl_object_find_any_key (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t* ucl_object_lookup_any (const ucl_object_t *obj, const char *key, ...); +#define ucl_object_find_any_key ucl_object_lookup_any /** * Return object identified by a fixed size key in the specified object @@ -665,8 +687,9 @@ UCL_EXTERN const ucl_object_t* ucl_object_find_any_key (const ucl_object_t *obj, * @param klen length of a key * @return object matching the specified key or NULL if key was not found */ -UCL_EXTERN const ucl_object_t* ucl_object_find_keyl (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t* ucl_object_lookup_len (const ucl_object_t *obj, const char *key, size_t klen); +#define ucl_object_find_keyl ucl_object_lookup_len /** * Return object identified by dot notation string @@ -674,8 +697,9 @@ UCL_EXTERN const ucl_object_t* ucl_object_find_keyl (const ucl_object_t *obj, * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays * @return object matched the specified path or NULL if path is not found */ -UCL_EXTERN const ucl_object_t *ucl_lookup_path (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t *ucl_object_lookup_path (const ucl_object_t *obj, const char *path); +#define ucl_lookup_path ucl_object_lookup_path /** * Return object identified by object notation string using arbitrary delimiter @@ -684,8 +708,9 @@ UCL_EXTERN const ucl_object_t *ucl_lookup_path (const ucl_object_t *obj, * @param sep the sepatorator to use in place of . (incase keys have . in them) * @return object matched the specified path or NULL if path is not found */ -UCL_EXTERN const ucl_object_t *ucl_lookup_path_char (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t *ucl_object_lookup_path_char (const ucl_object_t *obj, const char *path, char sep); +#define ucl_lookup_path_char ucl_object_lookup_path_char /** * Returns a key of an object as a NULL terminated string @@ -735,6 +760,19 @@ UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1, const ucl_object_t *o2); /** + * Compare objects `o1` and `o2` useful for sorting + * @param o1 the first object + * @param o2 the second object + * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`. + * The order of comparison: + * 1) Type of objects + * 2) Size of objects + * 3) Content of objects + */ +UCL_EXTERN int ucl_object_compare_qsort (const ucl_object_t **o1, + const ucl_object_t **o2); + +/** * Sort UCL array using `cmp` compare function * @param ar * @param cmp @@ -770,8 +808,9 @@ typedef void* ucl_object_iter_t; * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ... * @return the next object or NULL */ -UCL_EXTERN const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, +UCL_EXTERN const ucl_object_t* ucl_object_iterate (const ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values); +#define ucl_iterate_object ucl_object_iterate /** * Create new safe iterator for the specified object @@ -1040,34 +1079,34 @@ UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); * @param parser parser object * @return error description */ -UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser); +UCL_EXTERN const char *ucl_parser_get_error (struct ucl_parser *parser); /** * Get the code of the last error * @param parser parser object * @return error code */ -UCL_EXTERN int ucl_parser_get_error_code(struct ucl_parser *parser); +UCL_EXTERN int ucl_parser_get_error_code (struct ucl_parser *parser); /** * Get the current column number within parser * @param parser parser object * @return current column number */ -UCL_EXTERN unsigned ucl_parser_get_column(struct ucl_parser *parser); +UCL_EXTERN unsigned ucl_parser_get_column (struct ucl_parser *parser); /** * Get the current line number within parser * @param parser parser object * @return current line number */ -UCL_EXTERN unsigned ucl_parser_get_linenum(struct ucl_parser *parser); +UCL_EXTERN unsigned ucl_parser_get_linenum (struct ucl_parser *parser); /** * Clear the error in the parser * @param parser parser object */ -UCL_EXTERN void ucl_parser_clear_error(struct ucl_parser *parser); +UCL_EXTERN void ucl_parser_clear_error (struct ucl_parser *parser); /** * Free ucl parser object @@ -1076,6 +1115,42 @@ UCL_EXTERN void ucl_parser_clear_error(struct ucl_parser *parser); UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser); /** + * Get constant opaque pointer to comments structure for this parser. Increase + * refcount to prevent this object to be destroyed on parser's destruction + * @param parser parser structure + * @return ucl comments pointer or NULL + */ +UCL_EXTERN const ucl_object_t * ucl_parser_get_comments (struct ucl_parser *parser); + +/** + * Utility function to find a comment object for the specified object in the input + * @param comments comments object + * @param srch search object + * @return string comment enclosed in ucl_object_t + */ +UCL_EXTERN const ucl_object_t * ucl_comments_find (const ucl_object_t *comments, + const ucl_object_t *srch); + +/** + * Move comment from `from` object to `to` object + * @param comments comments object + * @param what source object + * @param whith destination object + * @return `true` if `from` has comment and it has been moved to `to` + */ +UCL_EXTERN bool ucl_comments_move (ucl_object_t *comments, + const ucl_object_t *from, const ucl_object_t *to); + +/** + * Adds a new comment for an object + * @param comments comments object + * @param obj object to add comment to + * @param comment string representation of a comment + */ +UCL_EXTERN void ucl_comments_add (ucl_object_t *comments, + const ucl_object_t *obj, const char *comment); + +/** * Add new public key to parser for signatures check * @param parser parser object * @param key PEM representation of a key @@ -1083,7 +1158,8 @@ UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser); * @param err if *err is NULL it is set to parser error * @return true if a key has been successfully added */ -UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len); +UCL_EXTERN bool ucl_parser_pubkey_add (struct ucl_parser *parser, + const unsigned char *key, size_t len); /** * Set FILENAME and CURDIR variables in parser @@ -1156,8 +1232,8 @@ struct ucl_emitter_context { unsigned int indent; /** Top level object */ const ucl_object_t *top; - /** The rest of context */ - unsigned char data[1]; + /** Optional comments */ + const ucl_object_t *comments; }; /** @@ -1187,11 +1263,13 @@ UCL_EXTERN unsigned char *ucl_object_emit_len (const ucl_object_t *obj, * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is * #UCL_EMIT_CONFIG then emit config like object * @param emitter a set of emitter functions + * @param comments optional comments for the parser * @return dump of an object (must be freed after using) or NULL in case of error */ UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj, enum ucl_emitter emit_type, - struct ucl_emitter_functions *emitter); + struct ucl_emitter_functions *emitter, + const ucl_object_t *comments); /** * Start streamlined UCL object emitter @@ -1280,6 +1358,9 @@ enum ucl_schema_error_code { UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */ UCL_SCHEMA_CONSTRAINT, /**< constraint found */ UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */ + UCL_SCHEMA_EXTERNAL_REF_MISSING, /**< cannot fetch external ref */ + UCL_SCHEMA_EXTERNAL_REF_INVALID, /**< invalid external ref */ + UCL_SCHEMA_INTERNAL_ERROR, /**< something bad happened */ UCL_SCHEMA_UNKNOWN /**< generic error */ }; @@ -1303,6 +1384,37 @@ struct ucl_schema_error { UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema, const ucl_object_t *obj, struct ucl_schema_error *err); +/** + * Validate object `obj` using schema object `schema` and root schema at `root`. + * @param schema schema object + * @param obj object to validate + * @param root root schema object + * @param err error pointer, if this parameter is not NULL and error has been + * occured, then `err` is filled with the exact error definition. + * @return true if `obj` is valid using `schema` + */ +UCL_EXTERN bool ucl_object_validate_root (const ucl_object_t *schema, + const ucl_object_t *obj, + const ucl_object_t *root, + struct ucl_schema_error *err); + +/** + * Validate object `obj` using schema object `schema` and root schema at `root` + * using some external references provided. + * @param schema schema object + * @param obj object to validate + * @param root root schema object + * @param ext_refs external references (might be modified during validation) + * @param err error pointer, if this parameter is not NULL and error has been + * occured, then `err` is filled with the exact error definition. + * @return true if `obj` is valid using `schema` + */ +UCL_EXTERN bool ucl_object_validate_root_ext (const ucl_object_t *schema, + const ucl_object_t *obj, + const ucl_object_t *root, + ucl_object_t *ext_refs, + struct ucl_schema_error *err); + /** @} */ #ifdef __cplusplus |