| ucl.h (262398) | ucl.h (262975) |
|---|---|
| 1/* Copyright (c) 2013, Vsevolod Stakhov 2 * All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above copyright --- 18 unchanged lines hidden (view full) --- 27#include <string.h> 28#include <stddef.h> 29#include <stdlib.h> 30#include <stdint.h> 31#include <stdbool.h> 32#include <stdarg.h> 33#include <stdio.h> 34 | 1/* Copyright (c) 2013, Vsevolod Stakhov 2 * All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above copyright --- 18 unchanged lines hidden (view full) --- 27#include <string.h> 28#include <stddef.h> 29#include <stdlib.h> 30#include <stdint.h> 31#include <stdbool.h> 32#include <stdarg.h> 33#include <stdio.h> 34 |
| 35#ifdef _WIN32 36# define UCL_EXTERN __declspec(dllexport) 37#else 38# define UCL_EXTERN 39#endif 40 |
|
| 35/** 36 * @mainpage 37 * This is a reference manual for UCL API. You may find the description of UCL format by following this 38 * [github repository](https://github.com/vstakhov/libucl). 39 * 40 * This manual has several main sections: 41 * - @ref structures 42 * - @ref utils --- 152 unchanged lines hidden (view full) --- 195 * 196 * @{ 197 */ 198/** 199 * Copy and return a key of an object, returned key is zero-terminated 200 * @param obj CL object 201 * @return zero terminated key 202 */ | 41/** 42 * @mainpage 43 * This is a reference manual for UCL API. You may find the description of UCL format by following this 44 * [github repository](https://github.com/vstakhov/libucl). 45 * 46 * This manual has several main sections: 47 * - @ref structures 48 * - @ref utils --- 152 unchanged lines hidden (view full) --- 201 * 202 * @{ 203 */ 204/** 205 * Copy and return a key of an object, returned key is zero-terminated 206 * @param obj CL object 207 * @return zero terminated key 208 */ |
| 203char* ucl_copy_key_trash (ucl_object_t *obj); | 209UCL_EXTERN char* ucl_copy_key_trash (ucl_object_t *obj); |
| 204 205/** 206 * Copy and return a string value of an object, returned key is zero-terminated 207 * @param obj CL object 208 * @return zero terminated string representation of object value 209 */ | 210 211/** 212 * Copy and return a string value of an object, returned key is zero-terminated 213 * @param obj CL object 214 * @return zero terminated string representation of object value 215 */ |
| 210char* ucl_copy_value_trash (ucl_object_t *obj); | 216UCL_EXTERN char* ucl_copy_value_trash (ucl_object_t *obj); |
| 211 212/** 213 * Creates a new object 214 * @return new object 215 */ 216static inline ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT; 217static inline ucl_object_t * 218ucl_object_new (void) --- 29 unchanged lines hidden (view full) --- 248 249/** 250 * Convert any string to an ucl object making the specified transformations 251 * @param str fixed size or NULL terminated string 252 * @param len length (if len is zero, than str is treated as NULL terminated) 253 * @param flags conversion flags 254 * @return new object 255 */ | 217 218/** 219 * Creates a new object 220 * @return new object 221 */ 222static inline ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT; 223static inline ucl_object_t * 224ucl_object_new (void) --- 29 unchanged lines hidden (view full) --- 254 255/** 256 * Convert any string to an ucl object making the specified transformations 257 * @param str fixed size or NULL terminated string 258 * @param len length (if len is zero, than str is treated as NULL terminated) 259 * @param flags conversion flags 260 * @return new object 261 */ |
| 256ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len, | 262UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len, |
| 257 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT; 258 259/** 260 * Create a UCL object from the specified string 261 * @param str NULL terminated string, will be json escaped 262 * @return new object 263 */ 264static inline ucl_object_t * --- 75 unchanged lines hidden (view full) --- 340 * Insert a object 'elt' to the hash 'top' and associate it with key 'key' 341 * @param top destination object (will be created automatically if top is NULL) 342 * @param elt element to insert (must NOT be NULL) 343 * @param key key to associate with this object (either const or preallocated) 344 * @param keylen length of the key (or 0 for NULL terminated keys) 345 * @param copy_key make an internal copy of key 346 * @return new value of top object 347 */ | 263 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT; 264 265/** 266 * Create a UCL object from the specified string 267 * @param str NULL terminated string, will be json escaped 268 * @return new object 269 */ 270static inline ucl_object_t * --- 75 unchanged lines hidden (view full) --- 346 * Insert a object 'elt' to the hash 'top' and associate it with key 'key' 347 * @param top destination object (will be created automatically if top is NULL) 348 * @param elt element to insert (must NOT be NULL) 349 * @param key key to associate with this object (either const or preallocated) 350 * @param keylen length of the key (or 0 for NULL terminated keys) 351 * @param copy_key make an internal copy of key 352 * @return new value of top object 353 */ |
| 348ucl_object_t* ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt, | 354UCL_EXTERN ucl_object_t* ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt, |
| 349 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 350 351/** 352 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed, 353 * if no object has been found this function works like ucl_object_insert_key() 354 * @param top destination object (will be created automatically if top is NULL) 355 * @param elt element to insert (must NOT be NULL) 356 * @param key key to associate with this object (either const or preallocated) 357 * @param keylen length of the key (or 0 for NULL terminated keys) 358 * @param copy_key make an internal copy of key 359 * @return new value of top object 360 */ | 355 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 356 357/** 358 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed, 359 * if no object has been found this function works like ucl_object_insert_key() 360 * @param top destination object (will be created automatically if top is NULL) 361 * @param elt element to insert (must NOT be NULL) 362 * @param key key to associate with this object (either const or preallocated) 363 * @param keylen length of the key (or 0 for NULL terminated keys) 364 * @param copy_key make an internal copy of key 365 * @return new value of top object 366 */ |
| 361ucl_object_t* ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt, | 367UCL_EXTERN ucl_object_t* ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt, |
| 362 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 363 364/** | 368 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 369 370/** |
| 371 * Delete a object associated with key 'key', old object will be unrefered, 372 * @param top object 373 * @param key key associated to the object to remove 374 * @param keylen length of the key (or 0 for NULL terminated keys) 375 */ 376UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top, const char *key, size_t keylen); 377 378/** 379 * Delete a object associated with key 'key', old object will be unrefered, 380 * @param top object 381 * @param key key associated to the object to remove 382 */ 383UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top, const char *key); 384 385/** |
|
| 365 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist, 366 * try to merge its content 367 * @param top destination object (will be created automatically if top is NULL) 368 * @param elt element to insert (must NOT be NULL) 369 * @param key key to associate with this object (either const or preallocated) 370 * @param keylen length of the key (or 0 for NULL terminated keys) 371 * @param copy_key make an internal copy of key 372 * @return new value of top object 373 */ | 386 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist, 387 * try to merge its content 388 * @param top destination object (will be created automatically if top is NULL) 389 * @param elt element to insert (must NOT be NULL) 390 * @param key key to associate with this object (either const or preallocated) 391 * @param keylen length of the key (or 0 for NULL terminated keys) 392 * @param copy_key make an internal copy of key 393 * @return new value of top object 394 */ |
| 374ucl_object_t* ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt, | 395UCL_EXTERN ucl_object_t* ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt, |
| 375 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 376 377/** 378 * Append an element to the front of array object 379 * @param top destination object (will be created automatically if top is NULL) 380 * @param elt element to append (must NOT be NULL) 381 * @return new value of top object 382 */ --- 403 unchanged lines hidden (view full) --- 786} 787 788/** 789 * Return object identified by a key in the specified object 790 * @param obj object to get a key from (must be of type UCL_OBJECT) 791 * @param key key to search 792 * @return object matched the specified key or NULL if key is not found 793 */ | 396 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 397 398/** 399 * Append an element to the front of array object 400 * @param top destination object (will be created automatically if top is NULL) 401 * @param elt element to append (must NOT be NULL) 402 * @return new value of top object 403 */ --- 403 unchanged lines hidden (view full) --- 807} 808 809/** 810 * Return object identified by a key in the specified object 811 * @param obj object to get a key from (must be of type UCL_OBJECT) 812 * @param key key to search 813 * @return object matched the specified key or NULL if key is not found 814 */ |
| 794ucl_object_t * ucl_object_find_key (ucl_object_t *obj, const char *key); | 815UCL_EXTERN ucl_object_t * ucl_object_find_key (ucl_object_t *obj, const char *key); |
| 795 796/** 797 * Return object identified by a fixed size key in the specified object 798 * @param obj object to get a key from (must be of type UCL_OBJECT) 799 * @param key key to search 800 * @param klen length of a key 801 * @return object matched the specified key or NULL if key is not found 802 */ | 816 817/** 818 * Return object identified by a fixed size key in the specified object 819 * @param obj object to get a key from (must be of type UCL_OBJECT) 820 * @param key key to search 821 * @param klen length of a key 822 * @return object matched the specified key or NULL if key is not found 823 */ |
| 803ucl_object_t *ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen); | 824UCL_EXTERN ucl_object_t *ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen); |
| 804 805/** 806 * Returns a key of an object as a NULL terminated string 807 * @param obj CL object 808 * @return key or NULL if there is no key 809 */ 810static inline const char * 811ucl_object_key (ucl_object_t *obj) --- 13 unchanged lines hidden (view full) --- 825 *len = obj->keylen; 826 return obj->key; 827} 828 829/** 830 * Free ucl object 831 * @param obj ucl object to free 832 */ | 825 826/** 827 * Returns a key of an object as a NULL terminated string 828 * @param obj CL object 829 * @return key or NULL if there is no key 830 */ 831static inline const char * 832ucl_object_key (ucl_object_t *obj) --- 13 unchanged lines hidden (view full) --- 846 *len = obj->keylen; 847 return obj->key; 848} 849 850/** 851 * Free ucl object 852 * @param obj ucl object to free 853 */ |
| 833void ucl_object_free (ucl_object_t *obj); | 854UCL_EXTERN void ucl_object_free (ucl_object_t *obj); |
| 834 835/** 836 * Increase reference count for an object 837 * @param obj object to ref 838 */ 839static inline ucl_object_t * 840ucl_object_ref (ucl_object_t *obj) { 841 obj->ref ++; --- 18 unchanged lines hidden (view full) --- 860/** 861 * Get next key from an object 862 * @param obj object to iterate 863 * @param iter opaque iterator, must be set to NULL on the first call: 864 * ucl_object_iter_t it = NULL; 865 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ... 866 * @return the next object or NULL 867 */ | 855 856/** 857 * Increase reference count for an object 858 * @param obj object to ref 859 */ 860static inline ucl_object_t * 861ucl_object_ref (ucl_object_t *obj) { 862 obj->ref ++; --- 18 unchanged lines hidden (view full) --- 881/** 882 * Get next key from an object 883 * @param obj object to iterate 884 * @param iter opaque iterator, must be set to NULL on the first call: 885 * ucl_object_iter_t it = NULL; 886 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ... 887 * @return the next object or NULL 888 */ |
| 868ucl_object_t* ucl_iterate_object (ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values); | 889UCL_EXTERN ucl_object_t* ucl_iterate_object (ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values); |
| 869/** @} */ 870 871 872/** 873 * @defgroup parser Parsing functions 874 * These functions are used to parse UCL objects 875 * 876 * @{ --- 12 unchanged lines hidden (view full) --- 889/* Opaque parser */ 890struct ucl_parser; 891 892/** 893 * Creates new parser object 894 * @param pool pool to allocate memory from 895 * @return new parser object 896 */ | 890/** @} */ 891 892 893/** 894 * @defgroup parser Parsing functions 895 * These functions are used to parse UCL objects 896 * 897 * @{ --- 12 unchanged lines hidden (view full) --- 910/* Opaque parser */ 911struct ucl_parser; 912 913/** 914 * Creates new parser object 915 * @param pool pool to allocate memory from 916 * @return new parser object 917 */ |
| 897struct ucl_parser* ucl_parser_new (int flags); | 918UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags); |
| 898 899/** 900 * Register new handler for a macro 901 * @param parser parser object 902 * @param macro macro name (without leading dot) 903 * @param handler handler (it is called immediately after macro is parsed) 904 * @param ud opaque user data for a handler 905 */ | 919 920/** 921 * Register new handler for a macro 922 * @param parser parser object 923 * @param macro macro name (without leading dot) 924 * @param handler handler (it is called immediately after macro is parsed) 925 * @param ud opaque user data for a handler 926 */ |
| 906void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro, | 927UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro, |
| 907 ucl_macro_handler handler, void* ud); 908 909/** 910 * Register new parser variable 911 * @param parser parser object 912 * @param var variable name 913 * @param value variable value 914 */ | 928 ucl_macro_handler handler, void* ud); 929 930/** 931 * Register new parser variable 932 * @param parser parser object 933 * @param var variable name 934 * @param value variable value 935 */ |
| 915void ucl_parser_register_variable (struct ucl_parser *parser, const char *var, | 936UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var, |
| 916 const char *value); 917 918/** 919 * Load new chunk to a parser 920 * @param parser parser structure 921 * @param data the pointer to the beginning of a chunk 922 * @param len the length of a chunk 923 * @param err if *err is NULL it is set to parser error 924 * @return true if chunk has been added and false in case of error 925 */ | 937 const char *value); 938 939/** 940 * Load new chunk to a parser 941 * @param parser parser structure 942 * @param data the pointer to the beginning of a chunk 943 * @param len the length of a chunk 944 * @param err if *err is NULL it is set to parser error 945 * @return true if chunk has been added and false in case of error 946 */ |
| 926bool ucl_parser_add_chunk (struct ucl_parser *parser, const unsigned char *data, size_t len); | 947UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser, const unsigned char *data, size_t len); |
| 927 928/** 929 * Load and add data from a file 930 * @param parser parser structure 931 * @param filename the name of file 932 * @param err if *err is NULL it is set to parser error 933 * @return true if chunk has been added and false in case of error 934 */ | 948 949/** 950 * Load and add data from a file 951 * @param parser parser structure 952 * @param filename the name of file 953 * @param err if *err is NULL it is set to parser error 954 * @return true if chunk has been added and false in case of error 955 */ |
| 935bool ucl_parser_add_file (struct ucl_parser *parser, const char *filename); | 956UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser, const char *filename); |
| 936 937/** 938 * Get a top object for a parser 939 * @param parser parser structure 940 * @param err if *err is NULL it is set to parser error 941 * @return top parser object or NULL 942 */ | 957 958/** 959 * Get a top object for a parser 960 * @param parser parser structure 961 * @param err if *err is NULL it is set to parser error 962 * @return top parser object or NULL 963 */ |
| 943ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); | 964UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); |
| 944 945/** 946 * Get the error string if failing 947 * @param parser parser object 948 */ | 965 966/** 967 * Get the error string if failing 968 * @param parser parser object 969 */ |
| 949const char *ucl_parser_get_error(struct ucl_parser *parser); | 970UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser); |
| 950/** 951 * Free ucl parser object 952 * @param parser parser object 953 */ | 971/** 972 * Free ucl parser object 973 * @param parser parser object 974 */ |
| 954void ucl_parser_free (struct ucl_parser *parser); | 975UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser); |
| 955 956/** 957 * Add new public key to parser for signatures check 958 * @param parser parser object 959 * @param key PEM representation of a key 960 * @param len length of the key 961 * @param err if *err is NULL it is set to parser error 962 * @return true if a key has been successfully added 963 */ | 976 977/** 978 * Add new public key to parser for signatures check 979 * @param parser parser object 980 * @param key PEM representation of a key 981 * @param len length of the key 982 * @param err if *err is NULL it is set to parser error 983 * @return true if a key has been successfully added 984 */ |
| 964bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len); | 985UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len); |
| 965 966/** 967 * Set FILENAME and CURDIR variables in parser 968 * @param parser parser object 969 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd() 970 * @param need_expand perform realpath() if this variable is true and filename is not NULL 971 * @return true if variables has been set 972 */ | 986 987/** 988 * Set FILENAME and CURDIR variables in parser 989 * @param parser parser object 990 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd() 991 * @param need_expand perform realpath() if this variable is true and filename is not NULL 992 * @return true if variables has been set 993 */ |
| 973bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename, | 994UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename, |
| 974 bool need_expand); 975 976/** @} */ 977 978/** 979 * @defgroup emitter Emitting functions 980 * These functions are used to serialise UCL objects to some string representation. 981 * --- 18 unchanged lines hidden (view full) --- 1000 1001/** 1002 * Emit object to a string 1003 * @param obj object 1004 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1005 * #UCL_EMIT_CONFIG then emit config like object 1006 * @return dump of an object (must be freed after using) or NULL in case of error 1007 */ | 995 bool need_expand); 996 997/** @} */ 998 999/** 1000 * @defgroup emitter Emitting functions 1001 * These functions are used to serialise UCL objects to some string representation. 1002 * --- 18 unchanged lines hidden (view full) --- 1021 1022/** 1023 * Emit object to a string 1024 * @param obj object 1025 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1026 * #UCL_EMIT_CONFIG then emit config like object 1027 * @return dump of an object (must be freed after using) or NULL in case of error 1028 */ |
| 1008unsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type); | 1029UCL_EXTERN unsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type); |
| 1009 1010/** 1011 * Emit object to a string 1012 * @param obj object 1013 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1014 * #UCL_EMIT_CONFIG then emit config like object 1015 * @return dump of an object (must be freed after using) or NULL in case of error 1016 */ | 1030 1031/** 1032 * Emit object to a string 1033 * @param obj object 1034 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1035 * #UCL_EMIT_CONFIG then emit config like object 1036 * @return dump of an object (must be freed after using) or NULL in case of error 1037 */ |
| 1017bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, | 1038UCL_EXTERN bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, |
| 1018 struct ucl_emitter_functions *emitter); 1019/** @} */ 1020 1021#ifdef __cplusplus 1022} 1023#endif 1024/* 1025 * XXX: Poorly named API functions, need to replace them with the appropriate --- 20 unchanged lines hidden --- | 1039 struct ucl_emitter_functions *emitter); 1040/** @} */ 1041 1042#ifdef __cplusplus 1043} 1044#endif 1045/* 1046 * XXX: Poorly named API functions, need to replace them with the appropriate --- 20 unchanged lines hidden --- |