#define luxem_bool_t int

Standard boolean type. This is used consistently throughout the interface.

Compatible with standard C boolean expressions.

#define luxem_true 1

#define luxem_false 0

struct luxem_string_t { char const *pointer; size_t length; };

This represents a delineation of memory that contains string or binary sequeynce. This library performs minimal copying, so this will frequently be a subsection of a larger allocation of memory.

Strings can be modified to point to other memory locations and lengths, but the data may not be modified and pointer should not be freed.

Pointers to luxem_string_t will never be stored and can be safely stack allocated. Ownership stays with the allocator except when indicated elsewise.

#define luxem_print_string(string, stream) ...

Prints a string to stdout - primarily a debugging aid.

typedef luxem_bool_t (*luxem_rawread_void_callback_t)(struct luxem_rawread_context_t *context, void *user_data);

A callback that receives no unique argument. user_data is the value set for user_data in the reader's luxem_rawread_callbacks_t structure. Return luxem_false to indicate an error was encountered during callback operation.

typedef luxem_bool_t (*luxem_rawread_string_callback_t)(struct luxem_rawread_context_t *context, void *user_data, struct luxem_string_t const *string);

A callback that receives a string as an argument. user_data is the value set for user_data in the reader's luxem_rawread_callbacks_t structure. Return luxem_false to indicate an error was encountered during callback operation.

struct luxem_rawread_callbacks_t { luxem_rawread_void_callback_t object_begin, object_end, array_begin, array_end; luxem_rawread_string_callback_t key, type, primitive; void *user_data; };

Ths is the structure used internally by the reader to contain callbacks and user data for the callbacks. All of the properties are writable by the user and will not be modified by the reader. Any callback can be 0.

struct luxem_rawread_context_t *luxem_rawread_construct(void);

Allocates and prepares a new reader. Returns the new reader.

void luxem_rawread_destroy(struct luxem_rawread_context_t *context);

Destroys the reader and frees all associated memory.

struct luxem_rawread_callbacks_t *luxem_rawread_callbacks(struct luxem_rawread_context_t *context);

Returns a pointer to the reader's internal callbacks structure. Use this to set read callbacks and user data before parsing.

luxem_bool_t luxem_rawread_feed(struct luxem_rawread_context_t *context, struct luxem_string_t const *data, size_t *out_eaten, luxem_bool_t finish);

Reads a document chunk provided in data, returning luxem_true if the read failed or luxem_false if an error was encountered. Use luxem_rawread_get_error to retrieve the error in the case of a failure.

out_eaten will be set to the offset in data that was successfully read. Subsequent calls to luxem_rawread_feed should not include the data preceding the read offset.

If finish is set, the reader will attempt to finish the current state once all data has been read. Use this if there is no more data to parse in the current document, or if you are sure that the current value has been provided in whole.

luxem_bool_t luxem_rawread_feed_file(struct luxem_rawread_context_t *context, FILE *file, luxem_rawread_void_callback_t block_callback, luxem_rawread_void_callback_t unblock_callback);

Reads the entire file, parsing the contents and finishing the parse when the end of the file is reached. block_callback, if not 0, is called immediately before a blocking read is performed on file. unblock_callback, if not 0, is called immediately after the blocking read on file completes.

struct luxem_string_t *luxem_rawread_get_error(struct luxem_rawread_context_t *context);

Returns a pointer to the reader's internal error structure. This pointer should not be freed by the caller.

This should be used to get information about an error if a reader function fails.

Alternatively, this can be used to set information in a user callback. In this case, the call back should return luxem_false to indicate that the callback has failed and error has been set. The user must set `pointer` and `length` on the returned string.

size_t luxem_rawread_get_position(struct luxem_rawread_context_t *context);

Returns the number of characters read since the reader was constructed.

struct luxem_string_t const *luxem_from_ascii16(struct luxem_string_t const *data, struct luxem_string_t *error);

Decodes a valid ascii16 chunk into a byte array (as a luxem_string_t) and returns it. The caller is responsible for releasing the returned `luxem_string_t` with free. If the function returns 0, error will contain an error message.

typedef luxem_bool_t (*luxem_rawwrite_write_callback_t)(struct luxem_rawwrite_context_t *context, void *user_data, struct luxem_string_t const *string);

A callback that receives a chunk of rendered luxem data for custom writing.

Return `luxem_false` and set the error using `luxem_rawwrite_get_error` to indicate an error has occurred.

struct luxem_rawwrite_context_t *luxem_rawwrite_construct(void);

Returns a new writer. Before use, the writer must be configured with one of `luxem_rawwrite_set_write_callback`, `luxem_rawwrite_set_file_out`, or `luxem_rawwrite_set_buffer_out`.

void luxem_rawwrite_destroy(struct luxem_rawwrite_context_t *context);

Destroys and frees the writer.

void luxem_rawwrite_set_write_callback(struct luxem_rawwrite_context_t *context, luxem_rawwrite_write_callback_t callback, void *user_data);

Configures the writer to pass all generated text to `callback`, along with `user_data`, a pointer to arbitrary data.

void luxem_rawwrite_set_file_out(struct luxem_rawwrite_context_t *context, FILE *file);

Configures the writer to write all generated text to `file`.

luxem_bool_t luxem_rawwrite_set_buffer_out(struct luxem_rawwrite_context_t *context);

Configures the writer to write all generated text to an internal buffer. The written text can be accessed with `luxem_rawwrite_buffer_render`.

struct luxem_string_t *luxem_rawwrite_buffer_render(struct luxem_rawwrite_context_t *context);

Returns a string that contains all text generated by the writer. This only works if the writer was configured with `luxem_rawwrite_set_buffer_out`. Because the format of the internal buffer is unspecified, this function may perform taxing calculations. The user must free the returned `luxem_string_t` after use with `free`.

void luxem_rawwrite_set_pretty(struct luxem_rawwrite_context_t *context, char spacer, size_t multiple);

Enables prettification on output. This typically involves new lines after values and indentation of all elements in a block. `spacer` is the character to be used for indentation, and `multiple` specifies how many of `spacer` to use for each indentation level.

struct luxem_string_t *luxem_rawwrite_get_error(struct luxem_rawwrite_context_t *context);

Returns a pointer to the writer's internal error structure. This pointer should not be freed by the caller.

This should be used to get information about an error if a writer function fails.

Alternatively, this can be used to set information in a user callback. In this case, the call back should return luxem_false to indicate that the callback has failed and error has been set. The user must set `pointer` and `length` on the returned string.

luxem_bool_t luxem_rawwrite_object_begin(struct luxem_rawwrite_context_t *context);

Opens a new object in the output stream.

luxem_bool_t luxem_rawwrite_object_end(struct luxem_rawwrite_context_t *context);

Closes the current open object in the output stream. Returns `luxem_false` if an error occurred during the operation.

luxem_bool_t luxem_rawwrite_array_begin(struct luxem_rawwrite_context_t *context);

Opens a new array in the output stream. Returns `luxem_false` if an error occurred during the operation.

luxem_bool_t luxem_rawwrite_array_end(struct luxem_rawwrite_context_t *context);

Closes the current open object in the array stream. Returns `luxem_false` if an error occurred during the operation.

luxem_bool_t luxem_rawwrite_key(struct luxem_rawwrite_context_t *context, struct luxem_string_t const *string);

Writes `string` as a key to the output stream. This should only be called in an object. Automatically quotes the string if necessary. Returns `luxem_false` if an error occurred during the operation.

luxem_bool_t luxem_rawwrite_type(struct luxem_rawwrite_context_t *context, struct luxem_string_t const *string);

Writes `string` as a type to the output stream. This should always be immediately followed by a value. Automatically quotes the string if necessary. Returns `luxem_false` if an error occurred during the operation.

luxem_bool_t luxem_rawwrite_primitive(struct luxem_rawwrite_context_t *context, struct luxem_string_t const *string);

Writes `string` as a primitive to the output stream. Automatically quotes the string if necessary. Returns `luxem_false` if an error occurred during the operation.

struct luxem_string_t const *luxem_to_ascii16(struct luxem_string_t const *data, struct luxem_string_t *error);

Encodes `data` as ascii16 and returns the result as a `luxem_string_t`. The caller is responsible for releasing the returned `luxem_string_t` with free. If the function returns 0, error will contain an error message.