ion_extractor.h File Reference

#include "ion.h"
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	_ion_extractor_options

Macros
#define	ION_EXTRACTOR_MAX_PATH_LENGTH_LIMIT   UINT16_MAX
#define	ION_EXTRACTOR_MAX_NUM_PATHS_LIMIT   UINT16_MAX
#define	ION_EXTRACTOR_MAX_PATH_LENGTH_DEFAULT   DEFAULT_WRITER_STACK_DEPTH
#define	ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT   16
#define	ION_EXTRACTOR_MAX_PATH_LENGTH   ION_EXTRACTOR_MAX_PATH_LENGTH_DEFAULT
#define	ION_EXTRACTOR_MAX_NUM_PATHS   ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT

Typedefs
typedef uint16_t	ION_EXTRACTOR_SIZE
typedef struct _ion_extractor_options	ION_EXTRACTOR_OPTIONS
typedef struct _ion_extractor	ION_EXTRACTOR
typedef ION_EXTRACTOR *	hEXTRACTOR
typedef struct _ion_extractor_path_descriptor	ION_EXTRACTOR_PATH_DESCRIPTOR
typedef ION_EXTRACTOR_PATH_DESCRIPTOR *	hPATH
typedef int_fast16_t	ION_EXTRACTOR_CONTROL
typedef iERR(*	ION_EXTRACTOR_CALLBACK) (hREADER reader, hPATH matched_path, void *user_context, ION_EXTRACTOR_CONTROL *p_control)

Functions
ION_API_EXPORT iERR	ion_extractor_open (hEXTRACTOR *extractor, ION_EXTRACTOR_OPTIONS *options)
ION_API_EXPORT iERR	ion_extractor_path_create (hEXTRACTOR extractor, ION_EXTRACTOR_SIZE path_length, ION_EXTRACTOR_CALLBACK callback, void *user_context, hPATH *p_path)
ION_API_EXPORT iERR	ion_extractor_path_append_field (hPATH path, ION_STRING *value)
ION_API_EXPORT iERR	ion_extractor_path_append_ordinal (hPATH path, POSITION value)
ION_API_EXPORT iERR	ion_extractor_path_append_wildcard (hPATH path)
ION_API_EXPORT iERR	ion_extractor_path_create_from_ion (hEXTRACTOR extractor, ION_EXTRACTOR_CALLBACK callback, void *user_context, BYTE *ion_data, SIZE ion_data_length, hPATH *p_path)
ION_API_EXPORT iERR	ion_extractor_match (hEXTRACTOR extractor, hREADER reader)
ION_API_EXPORT iERR	ion_extractor_close (hEXTRACTOR extractor)

Macro Definition Documentation

ION_EXTRACTOR_MAX_NUM_PATHS

#define ION_EXTRACTOR_MAX_NUM_PATHS   ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT

The maximum number of paths that can be registered to any extractor. The value of this constant may be defined by the user as necessary. Its defined value may not be greater than ION_EXTRACTOR_MAX_NUM_PATHS_LIMIT nor less than 1, and will be defaulted to ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT if missing or less than 1 and clamped at ION_EXTRACTOR_MAX_NUM_PATHS_LIMIT if necessary.

Defining this value to be as small as possible while remaining larger than any extractor's max_num_paths will increase the memory density of each extractor, which may improve performance.

ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT

#define ION_EXTRACTOR_MAX_NUM_PATHS_DEFAULT   16

Default maximum number of paths that can be registered to any extractor. NOTE: this is a constant that may not be redefined by the user.

ION_EXTRACTOR_MAX_NUM_PATHS_LIMIT

#define ION_EXTRACTOR_MAX_NUM_PATHS_LIMIT   UINT16_MAX

Limit on the maximum number of paths that can be registered to any extractor. Sizes and indices are stored in an unsigned 16-bit integer, so this is the max value that can be represented. NOTE: this is a constant that may not be redefined by the user.

ION_EXTRACTOR_MAX_PATH_LENGTH

#define ION_EXTRACTOR_MAX_PATH_LENGTH   ION_EXTRACTOR_MAX_PATH_LENGTH_DEFAULT

The maximum length of paths that can be registered to any extractor. The value of this constant may be defined by the user as necessary. Its defined value may not be greater than ION_EXTRACTOR_MAX_PATH_LENGTH_LIMIT nor less than 1, and will be defaulted to DEFAULT_WRITER_STACK_DEPTH if missing or less than 1 and clamped at ION_EXTRACTOR_MAX_PATH_LENGTH_LIMIT if necessary.

Defining this value to be as small as possible while remaining larger than any extractor's max_path_length will increase the memory density of each extractor, which may improve performance.

ION_EXTRACTOR_MAX_PATH_LENGTH_DEFAULT

#define ION_EXTRACTOR_MAX_PATH_LENGTH_DEFAULT   DEFAULT_WRITER_STACK_DEPTH

Default maximum length of any path. DEFAULT_WRITER_STACK_DEPTH is chosen as the default because this is the default maximum depth to which readers can descend. Unless the reader is configured with a higher max_container_depth, attempting to match paths longer than this will fail. NOTE: this is a constant that may not be redefined by the user.

ION_EXTRACTOR_MAX_PATH_LENGTH_LIMIT

#define ION_EXTRACTOR_MAX_PATH_LENGTH_LIMIT   UINT16_MAX

A path extractor that operates on top of the ION_READER interface. Limit on the maximum length of any path. Sizes and indices are stored in an unsigned 16-bit integer, so this is the max value that can be represented. NOTE: this is a constant that may not be redefined by the user.

Typedef Documentation

hEXTRACTOR

typedef ION_EXTRACTOR* hEXTRACTOR

Handle to an ION_EXTRACTOR.

hPATH

typedef ION_EXTRACTOR_PATH_DESCRIPTOR* hPATH

Handle to an ION_EXTRACTOR_PATH_DESCRIPTOR.

ION_EXTRACTOR

typedef struct _ion_extractor ION_EXTRACTOR

The internal extractor structure.

ION_EXTRACTOR_CALLBACK

typedef iERR(* ION_EXTRACTOR_CALLBACK) (hREADER reader, hPATH matched_path, void *user_context, ION_EXTRACTOR_CONTROL *p_control)

Callback function to be invoked when the extractor matches a path.

The callback receives the matcher's ion_reader, positioned on the matching value, so that it can query the value's ion_type and to use the appropriate ion_reader function to read the matched value. Callback implementations MUST comply with the following:

• The reader must not be advanced past the matching value. Violating this will cause the following value to be skipped. If a value is skipped, neither the value itself nor any of its children will be checked for match against any of the extractor's registered paths.
• If the reader is positioned on a container value, its cursor must be at the same depth when the callback returns. In other words, if the user steps in to the matched value, it must step out an equal number of times. Violating this will raise an error.

Parameters

reader	- The reader provided to the matching extractor through ion_extractor_match, positioned on the matching value.
matched_path	- The path that was matched. This will be reference-equivalent to one of the extractor's registered paths.
user_context	- User context data, reference-equivalent to the user_context provided for matched_path during path registration.
p_control	- A control instruction to be conveyed back to the extractor (output parameter).

ION_EXTRACTOR_CONTROL

typedef int_fast16_t ION_EXTRACTOR_CONTROL

An instruction used by callback implementations to control execution of the extractor after a match. In general, these instructions tell the extractor to "step-out-N", meaning that the extractor should continue processing from N levels up from the length of the matched path.

The following functions are provided for convenience: ion_extractor_control_step_out - Creates a control instruction that tells the extractor to step out N. ion_extractor_control_next - Creates a control instruction that tells the extractor to continue normally, without stepping out (i.e. step out 0).

ION_EXTRACTOR_OPTIONS

typedef struct _ion_extractor_options ION_EXTRACTOR_OPTIONS

Extractor configuration to be supplied by the user when opening a new extractor.

ION_EXTRACTOR_PATH_DESCRIPTOR

typedef struct _ion_extractor_path_descriptor ION_EXTRACTOR_PATH_DESCRIPTOR

The internal path structure.

ION_EXTRACTOR_SIZE

typedef uint16_t ION_EXTRACTOR_SIZE

Represents indices and sizes for extractor-internal data. NOTE: this can be a uint16_t because both ION_EXTRACTOR_DEFAULT_MAX_NUM_PATHS and ION_EXTRACTOR_DEFAULT_MAX_PATH_LENGTH can be represented in 16 bits. Raising these limits (or making them configurable) will require a larger data type.

Function Documentation

ion_extractor_close()

ION_API_EXPORT iERR ion_extractor_close

(

hEXTRACTOR

extractor

)

Deallocates the given extractor.

Parameters

extractor

- The extractor to deallocate.

ion_extractor_match()

ION_API_EXPORT iERR ion_extractor_match	(	hEXTRACTOR	extractor,
		hREADER	reader
	)

Extracts matches within the data read by the extractor's reader using the extractor's registered paths.

The given reader should be positioned before the first value to be processed. Unless extractor.options.match_relative_paths is true, this must be at depth 0. Otherwise, this may be at any valid depth within the data. In order to avoid skipping any values at a particular non-zero depth, the reader should be navigated to that depth using ion_reader_step_in NOT followed by ion_reader_next.

Parameters

extractor	- The extractor to match.
reader	- A pre-allocated reader, which has already been opened by calling ion_reader_open_*.

Returns

a non-zero error code in the case of failure (including any underlying parsing failures), otherwise IERR_OK.

Ownership: the caller owns the reader and its associated resources, and guarantees that that they remain accessible at least until this call terminates. To free the reader, the caller must eventually call ion_reader_close as usual.

ion_extractor_open()

ION_API_EXPORT iERR ion_extractor_open	(	hEXTRACTOR *	extractor,
		ION_EXTRACTOR_OPTIONS *	options
	)

Allocates a new extractor and prepares it to process the given reader.

Parameters

extractor	- A non-null extractor pointer. The caller is responsible for freeing the resulting extractor using ion_extractor_close.
options	- Configuration options. May be null. If null, defaults will be used. The caller owns the memory, but is not required to keep it accessible after this call.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

ion_extractor_path_append_field()

ION_API_EXPORT iERR ion_extractor_path_append_field	(	hPATH	path,
		ION_STRING *	value
	)

Appends a path component representing a field name to the given path. Calling this function will fail if the given path was not created using ion_extractor_path_create or if appending another component to the given path would cause it to exceed the length declared during the call to ion_extractor_path_create.

Parameters

path	- A path which has already been registered to an extractor by calling ion_extractor_path_create.
value	- The field name to add to the path.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

Ownership: the caller owns the value, but is not required to keep it accessible after this call.

ion_extractor_path_append_ordinal()

ION_API_EXPORT iERR ion_extractor_path_append_ordinal	(	hPATH	path,
		POSITION	value
	)

Appends a path component representing an ordinal (e.g. a collection index) to the given path. Calling this function will fail if the given path was not created using ion_extractor_path_create or if appending another component to the given path would cause it to exceed the length declared during the call to ion_extractor_path_create.

Parameters

path	- A path which has already been registered to an extractor by calling ion_extractor_path_create.
value	- The ordinal to add to the path. Must be greater than or equal to zero.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

ion_extractor_path_append_wildcard()

ION_API_EXPORT iERR ion_extractor_path_append_wildcard

(

hPATH

path

)

Appends a path component representing a wildcard to the given path. Calling this function will fail if the given path was not created using ion_extractor_path_create or if appending another component to the given path would cause it to exceed the length declared during the call to ion_extractor_path_create.

Parameters

path	- A path which has already been registered to an extractor by calling ion_extractor_path_create.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

ion_extractor_path_create()

ION_API_EXPORT iERR ion_extractor_path_create	(	hEXTRACTOR	extractor,
		ION_EXTRACTOR_SIZE	path_length,
		ION_EXTRACTOR_CALLBACK	callback,
		void *	user_context,
		hPATH *	p_path
	)

Registers the given callback and user context to a new empty path. To finish constructing the path, the user must append exactly path_length components to the resulting path before calling ion_extractor_match on this extractor. A zero-length path will match every value at the extractor's initial depth (which must be zero unless extractor.options.match_relative_paths is true).

NOTE: registering a sub-path of another registered path is not supported. For example, if the path (foo bar) is registered to a given extractor, the path (foo bar 2) should not be registered to the same extractor.

Parameters

extractor	- An extractor which has already been opened by calling ion_extractor_open.
callback	- The callback function to be invoked by the extractor when the given path is matched.
user_context	- User context data to be passed as an argument to callback. This data remains opaque to the extractor, and may be null.
p_path	- A non-null pointer to a handle to the resulting path.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

Ownership: the caller owns the callback and the user context.

ion_extractor_path_create_from_ion()

ION_API_EXPORT iERR ion_extractor_path_create_from_ion	(	hEXTRACTOR	extractor,
		ION_EXTRACTOR_CALLBACK	callback,
		void *	user_context,
		BYTE *	ion_data,
		SIZE	ion_data_length,
		hPATH *	p_path
	)

Registers a path from text or binary Ion data. The data must contain exactly one top-level value: an ordered sequence (list or sexp) containing a number of elements less than or equal to the extractor's max_path_length. The elements (if any) must be either text types (string or symbol), representing fields or wildcards, or integers, representing ordinals. In order for a text value to represent a wildcard, it must be equivalent to one of the supported wildcards (currently only *). Field elements with the same text as a wildcard must be annotated with the special annotation $ion_extractor_field as its first annotation. For example,

   ()
 

represents a path of length zero, which will match all top-level values when the extractor's initial depth is zero, while

   (abc * 2 $ion_extractor_field::*)
 

represents a path of length 4 consisting of a field named abc, a wildcard, an ordinal with value 2, and a field named *.

NOTE: this is a standalone function that does not require a call to ion_extractor_path_create. However, other paths registered to the same extractor may be constructed using that function.

Parameters

extractor	- An extractor which has already been opened by calling ion_extractor_open.
callback	- The callback function to be invoked by the extractor when the given path is matched.
user_context	- User context data to be passed as an argument to callback. This data remains opaque to the extractor, and may be null.
ion_data	- The ion data representing the path, which follows the schema described above.
ion_data_length	- The length, in bytes, of ion_data.
p_path	- A non-null pointer to a handle to the resulting path.

Returns

a non-zero error code in the case of failure, otherwise IERR_OK.

Ownership: the caller owns the callback and the user context.