diff --git a/modules/libcom/src/yajl/yajl_common.h b/modules/libcom/src/yajl/yajl_common.h index 57e2d7eb5..d842aa5bf 100644 --- a/modules/libcom/src/yajl/yajl_common.h +++ b/modules/libcom/src/yajl/yajl_common.h @@ -45,10 +45,12 @@ extern "C" { */ #define EPICS_YAJL_VERSION VERSION_INT(2,1,0,0) -/** Maximum generation depth for YAJL's JSON generation routines */ +/** A limit used by the generator API, YAJL_MAX_DEPTH is the maximum + * depth to which arrays and maps may be nested. + */ #define YAJL_MAX_DEPTH 128 -/** Symbol decoration for Microsoft builds */ +/** Marks a yajl routine for export from the DLL/shared library. */ #define YAJL_API LIBCOM_API /** Pointer to a malloc() function, supporting client overriding memory @@ -62,18 +64,18 @@ typedef void (*yajl_free_func)(void *ctx, void * ptr); /** Pointer to a realloc() function which can resize an allocation. */ typedef void * (*yajl_realloc_func)(void *ctx, void * ptr, size_t sz); -/** A structure which can be passed to yajl_*_alloc routines to allow the +/** A structure which can be passed to yajl_*_alloc() routines to allow the * client to specify memory allocation functions to be used. */ typedef struct { - /** Pointer to a function that can allocate uninitialized memory */ + /** Pointer to a function that can allocate uninitialized memory. */ yajl_malloc_func malloc; - /** Pointer to a function that can resize memory allocations */ + /** Pointer to a function that can resize memory allocations. */ yajl_realloc_func realloc; /** Pointer to a function that can free memory allocated using - * reallocFunction or mallocFunction */ + * the above realloc or malloc functions. */ yajl_free_func free; - /** A context pointer that will be passed to above allocation routines */ + /** A context pointer that will be passed to above allocation routines. */ void * ctx; } yajl_alloc_funcs; diff --git a/modules/libcom/src/yajl/yajl_gen.h b/modules/libcom/src/yajl/yajl_gen.h index c142eeedf..35d3f2b4d 100644 --- a/modules/libcom/src/yajl/yajl_gen.h +++ b/modules/libcom/src/yajl/yajl_gen.h @@ -28,34 +28,34 @@ #ifdef __cplusplus extern "C" { #endif - /** Generator status codes */ + /** Generator status codes. */ typedef enum { - /** No error */ + /** No error. */ yajl_gen_status_ok = 0, /** At a point where a map key is generated, a function other than - * yajl_gen_string() was called */ + * yajl_gen_string() was called. */ yajl_gen_keys_must_be_strings, - /** YAJL's maximum generation depth was exceeded. see + /** YAJL's maximum generation depth was exceeded. See * \ref YAJL_MAX_DEPTH */ yajl_max_depth_exceeded, - /** A generator function (yajl_gen_XXX) was called while in an error - * state */ + /** A yajl_gen_XXX() generator function was called while in an error + * state. */ yajl_gen_in_error_state, - /** A complete JSON document has been generated */ + /** A complete JSON document has been generated. */ yajl_gen_generation_complete, /** yajl_gen_double() was passed an invalid floating point value - * (infinity or NaN). */ + * (infinity or NaN) without \ref yajl_gen_json5 set. */ yajl_gen_invalid_number, /** A print callback was passed in, so there is no internal - * buffer to get from */ + * buffer to get from. */ yajl_gen_no_buf, - /** Returned from yajl_gen_string() when the yajl_gen_validate_utf8() - * option is enabled and an invalid was passed by client code. + /** Returned from yajl_gen_string() when the \ref yajl_gen_validate_utf8 + * option is enabled and an invalid UTF8 code was passed by client. */ yajl_gen_invalid_string } yajl_gen_status; - /** An opaque handle to a generator */ + /** An opaque handle to a generator. */ typedef struct yajl_gen_t * yajl_gen; /** A callback used for "printing" the results. */ @@ -64,76 +64,110 @@ extern "C" { size_t len); /** Configuration parameters for the parser, these may be passed to - * yajl_gen_config() along with option specific argument(s). In general, + * yajl_gen_config() along with option-specific argument(s). In general, * all configuration parameters default to *off*. */ typedef enum { - /** Generate indented (beautiful) output */ + /** Generate indented (beautiful) output. + * + * yajl_gen_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_gen_config(g, yajl_gen_beautify, 1); // Human format please + * \endcode + */ yajl_gen_beautify = 0x01, /** - * Set an indent string which is used when yajl_gen_beautify() - * is enabled. Maybe something like \\t or some number of - * spaces. The default is four spaces ' '. + * Set the indent string which is used when \ref yajl_gen_beautify + * is enabled, which may only contain whitespace characters such as + * \c \\t or some number of spaces. The default is four spaces ' '. + * + * yajl_gen_config() argument type: const char * + * + * Example: \code{.cpp} + * yajl_gen_config(g, yajl_gen_indent_string, " "); // 2 spaces + * \endcode */ yajl_gen_indent_string = 0x02, /** * Set a function and context argument that should be used to - * output generated json. the function should conform to the - * yajl_print_t() prototype while the context argument is a + * output the generated json. The function should conform to the + * \ref yajl_print_t prototype while the context argument may be any * void * of your choosing. * + * yajl_gen_config() arguments: \ref yajl_print_t, void * + * * Example: \code{.cpp} - * yajl_gen_config(g, yajl_gen_print_callback, myFunc, myVoidPtr); - * \endcode + * yajl_gen_config(g, yajl_gen_print_callback, myFunc, myVoidPtr); + * \endcode */ yajl_gen_print_callback = 0x04, /** * Normally the generator does not validate that strings you - * pass to it via yajl_gen_string() are valid UTF8. Enabling + * pass to it via yajl_gen_string() are valid UTF8. Enabling * this option will cause it to do so. + * + * yajl_gen_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_gen_config(g, yajl_gen_validate_utf8, 1); // Check UTF8 + * \endcode */ yajl_gen_validate_utf8 = 0x08, /** * The forward solidus (slash or '/' in human) is not required to be - * escaped in json text. By default, YAJL will not escape it in the - * iterest of saving bytes. Setting this flag will cause YAJL to + * escaped in JSON text. By default, YAJL will not escape it in the + * interest of saving bytes. Setting this flag will cause YAJL to * always escape '/' in generated JSON strings. + * + * yajl_gen_config() argument type: int (boolean) */ yajl_gen_escape_solidus = 0x10, /** + * JSON5 is an updated version of JSON with additional capabilities. * Special numbers such as NaN and Infinity cannot be represented in * the original JSON, but are permitted in JSON5. Setting this flag - * allows yajl_gen_double() to output the JSON5 representation of these - * special numbers instead of returning with an error. + * allows YAJL to output the JSON5 representation of these special + * numbers instead of returning with an error, and to emit map keys + * that are valid javascript identifiers without quotes. + * + * yajl_gen_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_gen_config(g, yajl_gen_json5, 1); // Output JSON5 + * \endcode */ yajl_gen_json5 = 0x20, } yajl_gen_option; - /** Allow the modification of generator options subsequent to handle - * allocation (via yajl_alloc()) - * \returns zero in case of errors, non-zero otherwise + /** Set generator options associated with a generator handle. See the + * \ref yajl_gen_option documentation for details of the available + * options and their arguments. + * \returns Zero in case of error, non-zero otherwise. */ YAJL_API int yajl_gen_config(yajl_gen hand, int option, ...); - /** Allocate a generator handle - * \param allocFuncs An optional pointer to a structure which allows - * the client to overide the memory allocation - * used by yajl. May be NULL, in which case - * malloc(), free() and realloc() will be used. + /** Allocate a generator handle. + * \param allocFuncs An optional pointer to a structure which allows the + * client to provide memory allocation functions for + * use by yajl. May be \c NULL to use the C runtime + * library's malloc(), free() and realloc(). * - * \returns an allocated handle on success, NULL on failure (bad params) + * \returns An allocated handle on success, \c NULL on failure (bad params) */ YAJL_API yajl_gen yajl_gen_alloc(const yajl_alloc_funcs * allocFuncs); - /** Free a generator handle */ + /** Free a generator handle. */ YAJL_API void yajl_gen_free(yajl_gen handle); /** Generate an integer number. */ YAJL_API yajl_gen_status yajl_gen_integer(yajl_gen hand, long long int number); - /** generate a floating point number - * \param number the value to output, which may only be \c Infinity or \c NaN - * if the \ref yajl_gen_json5 flag is set, as these values - * have no legal representation in JSON. In these cases the - * generator will return \ref yajl_gen_invalid_number + /** Generate a floating point number. + * \param hand The generator handle. + * \param number The value to output. The values \c Infinity or \c NaN are + * only accepted if the \ref yajl_gen_json5 option is set, + * as these values have no legal representation in JSON; + * the generator will return \ref yajl_gen_invalid_number + * otherwise. */ YAJL_API yajl_gen_status yajl_gen_double(yajl_gen hand, double number); /** Generate a number from the string given in \p num. */ @@ -159,16 +193,16 @@ extern "C" { /** Finish generating a JSON array. */ YAJL_API yajl_gen_status yajl_gen_array_close(yajl_gen hand); - /** Access the null terminated generator buffer. If incrementally + /** Access the zero-terminated generator buffer. If incrementally * outputing JSON, one should call yajl_gen_clear() to clear the - * buffer. This allows stream generation. */ + * buffer. This allows stream generation. */ YAJL_API yajl_gen_status yajl_gen_get_buf(yajl_gen hand, const unsigned char ** buf, size_t * len); /** Clear yajl's output buffer, but maintain all internal generation - * state. This function will not "reset" the generator state, and is - * intended to enable incremental JSON outputing. */ + * state. This function will not reset the generator state, and is + * intended to enable incremental JSON output. */ YAJL_API void yajl_gen_clear(yajl_gen hand); #ifdef __cplusplus diff --git a/modules/libcom/src/yajl/yajl_parse.h b/modules/libcom/src/yajl/yajl_parse.h index c9a1ee216..09ab546ff 100644 --- a/modules/libcom/src/yajl/yajl_parse.h +++ b/modules/libcom/src/yajl/yajl_parse.h @@ -28,42 +28,42 @@ #ifdef __cplusplus extern "C" { #endif - /** Error codes returned from this interface */ + /** Error codes returned from this interface. */ typedef enum { - /** No error was encountered */ + /** No error was encountered. */ yajl_status_ok, - /** A client callback returned zero, stopping the parse */ + /** A client callback returned zero, stopping the parse. */ yajl_status_client_canceled, - /** An error occured during the parse. Call yajl_get_error() for - * more information about the encountered error */ + /** An error occured during the parse. Call yajl_get_error() for + * more information about the encountered error. */ yajl_status_error } yajl_status; - /** Attain a human readable, english, string for an error */ + /** Return a human readable, english, string for an error. */ YAJL_API const char * yajl_status_to_string(yajl_status code); - /** An opaque handle to a parser */ + /** An opaque handle to a parser. */ typedef struct yajl_handle_t * yajl_handle; - /** YAJL is an event driven parser. This means as json elements are - * parsed, you are called back to do something with the data. The + /** YAJL is an event driven parser. This means as json elements are + * parsed, you are called back to do something with the data. The * functions in this table indicate the various events for which * you will be called back. Each callback accepts a "context" - * pointer, this is a void * that is passed into the yajl_parse() + * pointer, this is a \c void \c * that is passed into the yajl_parse() * function which the client code may use to pass around context. * - * All callbacks return an integer. If non-zero, the parse will - * continue. If zero, the parse will be canceled and - * yajl_status_client_canceled() will be returned from the parse. + * All callbacks return an integer. If non-zero, the parse will + * continue. If zero, the parse will be canceled and + * \c yajl_status_client_canceled will be returned from the parse. * * \attention * A note about the handling of numbers: - * yajl will only convert numbers that can be represented in a + * YAJL will only convert numbers that can be represented in a * double or a 64 bit (long long) int. All other numbers will * be passed to the client in string form using the yajl_number() * callback. Furthermore, if yajl_number() is not NULL, it will * always be used to return numbers, that is yajl_integer() and - * yajl_double() will be ignored. If yajl_number() is NULL but one + * yajl_double() will be ignored. If yajl_number() is NULL but one * of yajl_integer() or yajl_double() are defined, parsing of a * number larger than is representable in a double or 64 bit * integer will result in a parse error. @@ -74,12 +74,12 @@ extern "C" { int (* yajl_integer)(void * ctx, long long integerVal); int (* yajl_double)(void * ctx, double doubleVal); /** A callback which passes the string representation of the number - * back to the client. Will be used for all numbers when present */ + * back to the client. Will be used for all numbers when present. */ int (* yajl_number)(void * ctx, const char * numberVal, size_t numberLen); - /** Strings are returned as pointers into the JSON text when, - * possible, as a result, they are _not_ null padded */ + /** Strings are returned as pointers into the JSON text when + * possible. As a result they are _not_ zero-terminated. */ int (* yajl_string)(void * ctx, const unsigned char * stringVal, size_t stringLen); @@ -92,123 +92,152 @@ extern "C" { int (* yajl_end_array)(void * ctx); } yajl_callbacks; - /** Allocate a parser handle - * \param callbacks A yajl callbacks structure specifying the + /** Allocate a parser handle. + * \param callbacks A \c yajl_callbacks structure specifying the * functions to call when different JSON entities - * are encountered in the input text. May be NULL, + * are encountered in the input text. May be \c NULL, * which is only useful for validation. - * \param afs memory allocation functions, may be NULL for to use - * C runtime library routines (malloc and friends) - * \param ctx a context pointer that will be passed to callbacks. + * \param afs Memory allocation functions, pass \c NULL to use the + * C runtime library routines (malloc() and friends). + * \param ctx A context pointer that will be passed to callbacks. */ YAJL_API yajl_handle yajl_alloc(const yajl_callbacks * callbacks, yajl_alloc_funcs * afs, void * ctx); - /** Configuration parameters for the parser, these may be passed to - * yajl_config() along with option specific argument(s). In general, - * all configuration parameters default to *off*. */ + /** Configuration parameters for the parser. These should be passed to + * yajl_config() followed by any option specific argument(s). In general, + * all boolean configuration parameters default to *off*. */ typedef enum { - /** Ignore javascript style comments present in - * JSON input. Non-standard, but rather fun - * arguments: toggled off with integer zero, on otherwise. + /** + * Ignore javascript style comments present in the input. These are + * not standard in JSON but can be enabled with this. Turning on the + * \ref yajl_allow_json5 option enables this option automatically. * - * Example: \code{.cpp} - * yajl_config(h, yajl_allow_comments, 1); // turn comment support on - * \endcode + * yajl_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_config(h, yajl_allow_comments, 1); // turn comment support on + * \endcode */ yajl_allow_comments = 0x01, /** * When set the parser will verify that all strings in JSON input are - * valid UTF8 and will emit a parse error if this is not so. When set, - * this option makes parsing slightly more expensive (~7% depending - * on processor and compiler in use) + * valid UTF8, and will emit a parse error if this is not so. When set, + * this option makes parsing slightly more expensive (~7% depending on + * the processor and compiler in use) + * + * yajl_config() argument type: int (boolean) * * Example: \code{.cpp} - * yajl_config(h, yajl_dont_validate_strings, 1); // disable utf8 checking - * \endcode + * yajl_config(h, yajl_dont_validate_strings, 1); // disable utf8 checking + * \endcode */ yajl_dont_validate_strings = 0x02, /** - * By default, upon calls to yajl_complete_parse(), yajl will - * ensure the entire input text was consumed and will raise an error - * otherwise. Enabling this flag will cause yajl to disable this - * check. This can be useful when parsing json out of a that contains more - * than a single JSON document. + * By default, upon calls to yajl_complete_parse(), yajl will ensure + * the entire input text was consumed and will raise an error + * otherwise. Turning this flag on causes YAJL to disable the garbage + * check. This can be useful when parsing JSON out of an input stream + * that contains more than a single JSON document. + * + * yajl_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_config(h, yajl_allow_trailing_garbage, 1); // non-JSON follows + * \endcode */ yajl_allow_trailing_garbage = 0x04, /** - * Allow multiple values to be parsed by a single handle. The - * entire text must be valid JSON, and values can be seperated - * by any kind of whitespace. This flag will change the - * behavior of the parser, and cause it continue parsing after - * a value is parsed, rather than transitioning into a - * complete state. This option can be useful when parsing multiple - * values from an input stream. + * Allow multiple values to be parsed by a single handle. The entire + * text must be valid JSON, and values can be seperated by any kind of + * whitespace. This flag will change the behavior of the parser, and + * cause it to continue parsing after a value is parsed, rather than + * transitioning into a complete state. This option can be useful when + * parsing multiple values from an input stream. + * + * yajl_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_config(h, yajl_allow_multiple_values, 1); // multi-doc stream + * \endcode */ yajl_allow_multiple_values = 0x08, /** - * When yajl_complete_parse() is called the parser will - * check that the top level value was completely consumed. I.E., - * if called whilst in the middle of parsing a value - * yajl will enter an error state (premature EOF). Setting this - * flag suppresses that check and the corresponding error. + * When yajl_complete_parse() is called the parser will check that the + * top level value was completely consumed. If called whilst in the + * middle of parsing a value, yajl will enter an error state (premature + * EOF). Setting this flag suppresses that check and the corresponding + * error. + * + * yajl_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_config(h, yajl_allow_partial_values, 1); // might stop early + * \endcode */ yajl_allow_partial_values = 0x10, /** * The JSON5 standard allows additional formats for numbers, strings - * and object keys which are not permitted in the JSON standard. - * Setting this flag enables JSON5 formats in the lexer and parser. + * and object keys which are not permitted by the JSON standard. + * Setting this flag tells yajl to accept JSON5 standard input. + * This flag also enables \c yajl_allow_comments since comments are + * part of the JSON5 standard. + * + * yajl_config() argument type: int (boolean) + * + * Example: \code{.cpp} + * yajl_config(h, yajl_allow_json5, 1); // We accept JSON5! + * \endcode */ yajl_allow_json5 = 0x20, } yajl_option; - /** Allow the modification of parser options subsequent to handle - * allocation (via yajl_alloc()) - * \returns zero in case of errors, non-zero otherwise + /** Set parser options associated with a parser handle. See the + * \ref yajl_option documentation for details of the available options + * and their arguments. + * \returns Zero in case of error, non-zero otherwise. */ - YAJL_API int yajl_config(yajl_handle h, int option, ...); + YAJL_API int yajl_config(yajl_handle hand, int option, ...); - /** Free a parser handle */ - YAJL_API void yajl_free(yajl_handle handle); + /** Free a parser handle. */ + YAJL_API void yajl_free(yajl_handle hand); /** Parse some json! - * \param hand - a handle to the json parser allocated with yajl_alloc() - * \param jsonText - a pointer to the UTF8 json text to be parsed - * \param jsonTextLength - the length, in bytes, of input text + * \param hand A handle to the json parser allocated with yajl_alloc(). + * \param jsonText A pointer to the UTF8 json text to be parsed. + * \param jsonTextLength The length, in bytes, of input text. */ YAJL_API yajl_status yajl_parse(yajl_handle hand, const unsigned char * jsonText, size_t jsonTextLength); /** Parse any remaining buffered json. + * * Since yajl is a stream-based parser, without an explicit end of * input, yajl sometimes can't decide if content at the end of the - * stream is valid or not. For example, if "1" has been fed in, + * stream is valid or not. For example, if "1" has been received, * yajl can't know whether another digit is next or some character * that would terminate the integer token. * - * \param hand - a handle to the json parser allocated with yajl_alloc() + * \param hand a handle to the json parser allocated with yajl_alloc(). */ YAJL_API yajl_status yajl_complete_parse(yajl_handle hand); - /** Get an error string describing the state of the - * parse. + /** Get an error string describing the state of the parse. * - * If verbose is non-zero, the message will include the JSON - * text where the error occured, along with an arrow pointing to - * the specific char. + * If verbose is non-zero, the message will include the JSON text where + * the error occured, along with an arrow pointing to the specific char. * * \returns A dynamically allocated string will be returned which should - * be freed with yajl_free_error() + * be freed with yajl_free_error(). */ YAJL_API unsigned char * yajl_get_error(yajl_handle hand, int verbose, const unsigned char * jsonText, size_t jsonTextLength); - /** - * Get the amount of data consumed from the last chunk passed to YAJL. + /** Get the amount of data consumed from the last chunk passed to YAJL. * * In the case of a successful parse this can help you understand if * the entire buffer was consumed (which will allow you to handle @@ -221,7 +250,7 @@ extern "C" { */ YAJL_API size_t yajl_get_bytes_consumed(yajl_handle hand); - /** Free an error returned from yajl_get_error() */ + /** Free an error string returned from yajl_get_error(). */ YAJL_API void yajl_free_error(yajl_handle hand, unsigned char * str); #ifdef __cplusplus