epics/epics-base
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

Doxygen text and markup fixes and updates

Browse Source
This commit is contained in:
Andrew Johnson
2020-07-10 20:57:38 -05:00
parent de2de5e2fd
commit 975e9ec553
3 changed files with 194 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
modules/libcom/src/yajl/yajl_common.h
View File

@@ -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;

124
modules/libcom/src/yajl/yajl_gen.h
View File

@@ -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

183
modules/libcom/src/yajl/yajl_parse.h
View File

@@ -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