ubjsc  0.6
Enterprise-grade C library for manipulating UBJSON
Typedefs | Functions
ubjs_parser.h File Reference

Streaing parser of bytestream to ubjson primitives. More...

#include "ubjs_common.h"
#include "ubjs_library.h"
#include "ubjs_primitives.h"
Include dependency graph for ubjs_parser.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct ubjs_parser ubjs_parser
 Parser itself.
 
typedef struct ubjs_parser_builder ubjs_parser_builder
 Parser builder.
 
typedef struct ubjs_parser_error ubjs_parser_error
 Holder for parser errors.
 
typedef void(* ubjs_parser_parsed_f) (void *userdata, ubjs_prmtv *primitive)
 Callback to be executed just when parser parsed a first-citizen primitive. More...
 
typedef void(* ubjs_parser_debug_f) (void *userdata, unsigned int len, char *message)
 Callback to be executed just when parser issued a debug message. More...
 
typedef void(* ubjs_parser_error_f) (void *userdata, ubjs_parser_error *error)
 Callback when encountered a parsing error. More...
 
typedef void(* ubjs_parser_free_f) (void *userdata)
 Callback when parser is about to be free-d. More...
 

Functions

UBJS_EXPORT ubjs_result ubjs_parser_error_get_message_length (ubjs_parser_error *this, unsigned int *plength)
 Gets the error message's length. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_error_get_message_text (ubjs_parser_error *this, char *text)
 Copies the error message's content to provided array. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_new (ubjs_library *lib, ubjs_parser_builder **pbuilder)
 Creates new builder. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_free (ubjs_parser_builder **pbuilder)
 Frees the builder. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_userdata (ubjs_parser_builder *builder, void *userdata)
 Sets parser's userdata. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_parsed_f (ubjs_parser_builder *builder, ubjs_parser_parsed_f parsed_f)
 Sets parsed callback for parser's userdata. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_debug_f (ubjs_parser_builder *builder, ubjs_parser_debug_f debug_f)
 Sets debug callback for parser's userdata. If this is set, parser will callback with lots of internal messages about how and what is being parsed. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_error_f (ubjs_parser_builder *builder, ubjs_parser_error_f error_f)
 Sets error callback for parser's userdata. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_free_f (ubjs_parser_builder *builder, ubjs_parser_free_f free_f)
 Sets free callback for parser's userdata. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_bytes_since_last_callback (ubjs_parser_builder *builder, unsigned int value)
 Sets max number of bytes to process since last callback. If this is 0, limit is effectively off. Else parser errors will occur once you process this-th byte. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_container_length (ubjs_parser_builder *builder, unsigned int value)
 Max number of items in container. This applies to arrays and objects. If this is 0, limit is effectively off. Else parser errors when: More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_string_length (ubjs_parser_builder *builder, unsigned int value)
 Max number of characters in string or HPN. If this is 0, limit is effectively off. Else parser errors when expected length exceeds the limit. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_recursion_level (ubjs_parser_builder *builder, unsigned int value)
 Max recursion level for containers. If this is 0, limit is effectively off. Else parser errors when recursion level exceeds the limit. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_set_silently_ignore_toplevel_noops (ubjs_parser_builder *builder, ubjs_bool value)
 Whether to silently ignore no-op primitives. If this is UTRUE: More...
 
UBJS_EXPORT ubjs_result ubjs_parser_builder_build (ubjs_parser_builder *builder, ubjs_parser **pthis)
 Creates new parser. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_free (ubjs_parser **pthis)
 Frees the parser. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_get_userdata (ubjs_parser *this, void **puserdata)
 Gets userdata from the parser. More...
 
UBJS_EXPORT ubjs_result ubjs_parser_parse (ubjs_parser *this, uint8_t *data, unsigned int len)
 Parses the incoming data. More...
 

Detailed Description

Streaing parser of bytestream to ubjson primitives.

This file describes ubjs_parser structure, that parses incoming bytes and produces ubjs_prmtv objects asynchronously.

Since
0.2

Typedef Documentation

◆ ubjs_parser_debug_f

typedef void(* ubjs_parser_debug_f) (void *userdata, unsigned int len, char *message)

Callback to be executed just when parser issued a debug message.

Parameters
userdataUserdata.
lenLength.
messageMessage.
Since
0.6

◆ ubjs_parser_error_f

typedef void(* ubjs_parser_error_f) (void *userdata, ubjs_parser_error *error)

Callback when encountered a parsing error.

The current call to ubjs_parser_parse will return UR_ERROR. The parser is still functional, but it remains at last valid state, before the error appeared.

Parameters
userdataUserdata.
errorError.
Since
0.6

◆ ubjs_parser_free_f

typedef void(* ubjs_parser_free_f) (void *userdata)

Callback when parser is about to be free-d.

Here you can cleanup your userdata.

Parameters
userdataUserdata.
Since
0.6

◆ ubjs_parser_parsed_f

typedef void(* ubjs_parser_parsed_f) (void *userdata, ubjs_prmtv *primitive)

Callback to be executed just when parser parsed a first-citizen primitive.

You should ubjs_prmtv_free(&primitive) by yourself.

Parameters
userdataUserdata.
primitiveNewly parsed primitive.
Since
0.6

Function Documentation

◆ ubjs_parser_builder_build()

UBJS_EXPORT ubjs_result ubjs_parser_builder_build ( ubjs_parser_builder builder,
ubjs_parser **  pthis 
)

Creates new parser.

Parameters
builderBuilder.
pthisPointer to where put newly created parser.
Returns
UR_ERROR if error occured, else UR_OK.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_free()

UBJS_EXPORT ubjs_result ubjs_parser_builder_free ( ubjs_parser_builder **  pbuilder)

Frees the builder.

Parameters
pbuilderPointer to where lies builder.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_new()

UBJS_EXPORT ubjs_result ubjs_parser_builder_new ( ubjs_library lib,
ubjs_parser_builder **  pbuilder 
)

Creates new builder.

Parameters
libLibrary.
pbuilderPointer to where put builder.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UFALSE, UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_debug_f()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_debug_f ( ubjs_parser_builder builder,
ubjs_parser_debug_f  debug_f 
)

Sets debug callback for parser's userdata. If this is set, parser will callback with lots of internal messages about how and what is being parsed.

Parameters
builderBuilder.
debug_fDebug callback.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_error_f()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_error_f ( ubjs_parser_builder builder,
ubjs_parser_error_f  error_f 
)

Sets error callback for parser's userdata.

Parameters
builderBuilder.
error_fError callback.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_free_f()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_free_f ( ubjs_parser_builder builder,
ubjs_parser_free_f  free_f 
)

Sets free callback for parser's userdata.

Parameters
builderBuilder.
free_fFree callback.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_limit_bytes_since_last_callback()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_bytes_since_last_callback ( ubjs_parser_builder builder,
unsigned int  value 
)

Sets max number of bytes to process since last callback. If this is 0, limit is effectively off. Else parser errors will occur once you process this-th byte.

This setting is global to whole parser.

Parameters
builderBuilder.
valueValue.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_limit_container_length()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_container_length ( ubjs_parser_builder builder,
unsigned int  value 
)

Max number of items in container. This applies to arrays and objects. If this is 0, limit is effectively off. Else parser errors when:

  • for unoptimized containers, n+1-th item is not an end marker,
  • for optimized containers, when received length and it exceeds the limit.

This setting is global to whole parser.

Parameters
builderBuilder.
valueValue.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_limit_recursion_level()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_recursion_level ( ubjs_parser_builder builder,
unsigned int  value 
)

Max recursion level for containers. If this is 0, limit is effectively off. Else parser errors when recursion level exceeds the limit.

This setting is global to whole parser.

Parameters
builderBuilder.
valueValue.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_limit_string_length()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_limit_string_length ( ubjs_parser_builder builder,
unsigned int  value 
)

Max number of characters in string or HPN. If this is 0, limit is effectively off. Else parser errors when expected length exceeds the limit.

This setting is global to whole parser.

Parameters
builderBuilder.
valueValue.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_parsed_f()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_parsed_f ( ubjs_parser_builder builder,
ubjs_parser_parsed_f  parsed_f 
)

Sets parsed callback for parser's userdata.

Parameters
builderBuilder.
parsed_fParsed callback.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_silently_ignore_toplevel_noops()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_silently_ignore_toplevel_noops ( ubjs_parser_builder builder,
ubjs_bool  value 
)

Whether to silently ignore no-op primitives. If this is UTRUE:

  • any top-level no-op does not result in callback,
  • no-ops found during parsing of a container are not added to it's content,
  • they also do not count in count-optimized containers. This means it is absolutely legal to have a 12-optimized array, and between elements there happen to be no-ops.

This setting is global to whole parser.

Parameters
builderBuilder.
valueValue.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_builder_set_userdata()

UBJS_EXPORT ubjs_result ubjs_parser_builder_set_userdata ( ubjs_parser_builder builder,
void *  userdata 
)

Sets parser's userdata.

Parameters
builderBuilder.
userdataUserdata.
Returns
UR_OK if succedeed, otherwise UR_ERROR.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_error_get_message_length()

UBJS_EXPORT ubjs_result ubjs_parser_error_get_message_length ( ubjs_parser_error this,
unsigned int *  plength 
)

Gets the error message's length.

Parameters
thisError.
plengthPointer to where set the value.
Returns
UR_ERROR if any of this/presult is 0, else UR_OK.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_error_get_message_text()

UBJS_EXPORT ubjs_result ubjs_parser_error_get_message_text ( ubjs_parser_error this,
char *  text 
)

Copies the error message's content to provided array.

Target array must be preallocated. Before the call, you may want to ubjs_parser_error_get_message_length and allocate the target array.

Parameters
thisError.
textTarget array.
Returns
UR_ERROR if any of this/text is 0, else UR_OK.
Since
0.6

References ubjs_glue_array_builder::build_f, ubjs_glue_array_builder::free_f, MARKER_ARRAY_BEGIN, MARKER_ARRAY_END, MARKER_CHAR, MARKER_FALSE, MARKER_FLOAT32, MARKER_FLOAT64, MARKER_HPN, MARKER_INT16, MARKER_INT32, MARKER_INT64, MARKER_INT8, MARKER_NOOP, MARKER_NULL, MARKER_OBJECT_BEGIN, MARKER_OBJECT_END, MARKER_OPTIMIZE_COUNT, MARKER_OPTIMIZE_TYPE, MARKER_STR, MARKER_TRUE, MARKER_UINT8, ubjs_glue_array_builder::set_value_free_f, ubjs_glue_array_array_builder_new(), UR_ERROR, and UR_OK.

Here is the call graph for this function:

◆ ubjs_parser_free()

UBJS_EXPORT ubjs_result ubjs_parser_free ( ubjs_parser **  pthis)

Frees the parser.

The call to context->free will occur here. After this, *pthis will be equal to 0.

Parameters
pthisPointer to the parser.
Returns
UR_ERROR if pthis is 0, else UR_OK.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_get_userdata()

UBJS_EXPORT ubjs_result ubjs_parser_get_userdata ( ubjs_parser this,
void **  puserdata 
)

Gets userdata from the parser.

Parameters
thisParser.
puserdataPointer to where put userdata.
Returns
UR_ERROR if any of this/pcontext is 0, else UR_OK.
Since
0.6

References UR_ERROR, and UR_OK.

◆ ubjs_parser_parse()

UBJS_EXPORT ubjs_result ubjs_parser_parse ( ubjs_parser this,
uint8_t *  data,
unsigned int  len 
)

Parses the incoming data.

This may produce the call (or calls) to context->parsed with just-parsed primitive, or context->error, or none of them.

In case there are many primitives parsed in single ubjs_parser_parse call, these many calls to context->parsed will be issues for each new primitive.

In case there is too little data to issue any callback, this method will not issue any callback.

If len == 0, this method does nothing and simply returns UR_OK.

Parameters
thisParser.
dataIncoming data.
lenLength of the data.
Returns
UR_ERROR if any of this/data is 0, else UR_OK.
Since
0.6

References ubjs_glue_array_iterator::free_f, ubjs_glue_array_iterator::get_f, ubjs_glue_array::get_length_f, ubjs_glue_array_iterator::next_f, ubjs_prmtv_debug_string_copy(), ubjs_prmtv_debug_string_get_length(), ubjs_prmtv_free(), ubjs_prmtv_get_type(), ubjs_prmtv_int_get(), UFALSE, UOT_NOOP, UR_ERROR, UR_OK, and UTRUE.

Here is the call graph for this function: