NOSJ API Reference

Defines

json_array_for_each(var, tok_arr, start)

Loop through each value in a JSON array.

Example: 

size_t elem;
json_array_for_each(elem, tokens, 0) {
  printf("Element at index %lu\n", elem);
}

Parameters

  • var: A variable (size_t) which will contain the index of each token

  • tok_arr: The JSON token array

  • start: The index of the JSON array in the token array

Enums

enum json_type

Enumeration for all possible types of JSON values.

An instance of this enum is included in each struct json_token, since each token directly represents a JSON value.

The JSON spec lists each of these as their own type. So, NOSJ internally recognizes them as such. Note that the boolean values true and false actually are each their own type (as is null).

Values:

enumerator JSON_OBJECT
enumerator JSON_ARRAY
enumerator JSON_NUMBER
enumerator JSON_STRING
enumerator JSON_TRUE
enumerator JSON_FALSE
enumerator JSON_NULL
enum json_error

Errors that could be encountered in JSON parsing.

Values:

enumerator JSONERR_NO_ERROR

No error!

enumerator JSONERR_INVALID_NUMBER

An error was encountered while parsing a number.

enumerator JSONERR_PREMATURE_EOF

The string ended unexpectedly.

enumerator JSONERR_UNEXPECTED_TOKEN

Parser encountered a token that was not expected.

enumerator JSONERR_INVALID_SURROGATE

Parser encountered an invalid surrogate pair.

enumerator JSONERR_EXPECTED_TOKEN

Parser did not encounter an expected token.

This error has an argument (e.g. expected ‘:’).

Functions

struct json_parser json_parse(char *json, struct json_token *arr, size_t n)

Parse JSON into tokens.

This function simply tokenizes JSON. That is, it identifies the location of each JSON entity: objects, arrays, strings, numbers, booleans, and null. It tokenizes into an already allocated buffer of tokens, so that no memory allocation takes place. This means that you should pre-allocate a buffer. In order to know what size buffer to allocate, you can call this function with arr=NULL, and it will return the number of tokens it would have parsed as part of the json_parser return value (textidx).

Return

A parser result.

Parameters

  • json: The text buffer to parse.

  • arr: A buffer to put the tokens in. May be null.

  • n: The number of slots in the arr buffer.

void json_print(struct json_token *arr, size_t n)

Print a list of JSON tokens.

This is mostly for diagnostics. After you’ve parsed JSON, you may want to know whether you did it right. This function prints out the contents of a buffer of JSON tokens so that you can see the parse results.

Parameters

  • arr: The array of tokens to print.

  • n: The number of tokens in the buffer.

void json_print_error(FILE *f, struct json_parser p)

Print out a parser error message for a parser error.

Parameters

  • f: File to print to.

  • p: Parser return struct.

bool json_string_match(const char *json, const struct json_token *tokens, size_t index, const char *other)

Return whether or not a string matches a token string.

Return

True if they are equal, false otherwise.

Parameters

  • json: The original JSON buffer.

  • tokens: The parsed tokens.

  • index: The index of the string token.

  • other: The other string to compare to.

void json_string_load(const char *json, const struct json_token *tokens, size_t index, char *buffer)

Load a string into a buffer.

The buffer MUST NOT be null. It must point to an already allocated buffer, of at least size

tokens[index].length + 1 (room for the text and a NULL character).
Parameters

  • json: The original JSON buffer.

  • tokens: The parsed tokens.

  • index: The index of the string token.

  • buffer: The buffer to load the string into.

size_t json_object_get(const char *json, const struct json_token *tokens, size_t index, const char *key)

Return the value associated with a key in a JSON object.

Return

the index of the value token, or 0 if not found.

Parameters

  • json: The original JSON buffer.

  • tokens: The parsed token buffer.

  • index: The index of the JSON object.

  • key: The key you’re searching for.

size_t json_array_get(const char *json, const struct json_token *tokens, size_t index, size_t array_index)

Return the value at a certain index within a JSON array.

Return

the index of the value’s token, or 0 if not found.

Parameters

  • json: The original JSON buffer.

  • tokens: The parsed token buffer.

  • index: The index of the array token within the buffer.

  • array_index: The index to lookup in the JSON array.

double json_number_get(const char *json, const struct json_token *tokens, size_t index)

Return the value of a JSON number token.

Return

the value as a double-precision float

Parameters

  • json: The original JSON buffer.

  • tokens: The parsed token buffer.

  • index: The index of the number in the token buffer.

size_t json_lookup(const char *json, const struct json_token *arr, size_t tok, const char *key)

Lookup values from JSON array using an expression language.

The expression language starts relative to the tok parameter (which may be an object or array). Objects keys are traversed by using a “.keyname”. Arrays are indexed via “[NUM]”. An example of such an expression might be:

“data.entries[5].name”

For the most part, this expression language should be familiar to C-like language users. It should be particularly familiar to the way which a JSON object could be traversed in Javascript itself. One “key” difference (ha) is that there are fewer restrictions on object key names. This function accepts any object key which does not contain one of {‘.’, ‘[‘, ‘\0’}. Even an end bracket is legal, although not recommended.

Return

0 when the item is not found (due to any reason, including expression syntax error, or index/key not found), non-0 on success, which indicates the index of the target value.

Parameters

  • json: The original JSON text buffer

  • arr: The parsed tokens array

  • tok: Token which the expression will be evaluated relative to

  • key: The key, as a JSON-traversing expression

struct json_token
#include <nosj.h>

Represents a JSON “token”.

A “token” in NOSJ terminology maps directly to a single JSON value. This struct contains “metadata” that NOSJ can later use to navigate through the JSON structure or load the value. These tokens are stored in an array, so their relationships (child, next, etc) are simply other indices in the array. JSON values take on a “tree-like” structure, so tokens are stored in a pre-order traversal of this tree. That is, you have the parent object, followed by each of its children.

Public Members

enum json_type type

Type of the token.

size_t start

Index of the first character of the token in the string.

size_t end

Index of the last character of the token in the string.

size_t length

For tokens that can have a length, this is the length!

More specifically, this value represents:

  • For arrays, the number of elements.

  • For objects, the number of key, value pairs.

  • For strings, the number of Unicode code points.

size_t child

Index of the first “child” value.

A “child value” can mean slightly different things in different situations:

  • For an array, the child is the first element of the array.

  • For an object, the child is the first key of the object.

  • For strings that are keys in an object, the child is the value corresponding to that key.

size_t next

Index of the next value in the sequence.

Within lists, “next” refers to the next value in the list. Within objects, the “next” attribute of a key refers to the next key in the object.

struct json_parser
#include <nosj.h>

A data structure that contains parser state.

This struct is the return value of json_parse(). It is also used internally throughout parsing to represent the current state of the parser.

Public Members

size_t textidx

The index of the next “unhandled” character.

On return from json_parse(), this is the index of the first character that wasn’t parsed. Or, equivalently, this is the number of input characters parsed.

size_t tokenidx

The index of the next slot to stick a token in our array.

On return from json_parse(), this is the first index of the token array that was not used. Equivalently, this is the number of tokens parsed.

enum json_error error

Error code. This must be checked the first time you parse.

size_t errorarg

Argument to the error code. Useful for printing error messages.