jx_parse.h File Reference

Parse JSON strings and files into JX expressions. More...

`#include "jx.h"`
`#include "link.h"`
`#include <stdbool.h>`
`#include <stdio.h>`

Go to the source code of this file.

## Functions

struct jx * | jx_parse_string (const char *str)
| Parse a JSON string to a JX expression.
struct jx * | jx_parse_string_and_length (const char *str, int length)
| Parse a JSON string to a JX expression.
struct jx * | jx_parse_stream (FILE *file)
| Parse a standard IO stream to a JX expression.
struct jx * | jx_parse_file (const char *name)
| Parse a file to a JX expression.
struct jx * | jx_parse_link (struct link *l, time_t stoptime)
| Parse a network link to a JX expression.
struct jx * | jx_parse_cmd_args (struct jx *jx_args, char *args_file)
| Parse a jx argument file from a commandline option.
int | jx_parse_cmd_define (struct jx *jx_args, char *define_stmt)
| Parse a jx define statement from a commandline option.
struct jx_parser * | jx_parser_create (bool strict_mode)
| Create a JX parser object.
void | jx_parser_read_stream (struct jx_parser *p, FILE *file)
| Attach parser to a file.
void | jx_parser_read_string (struct jx_parser *p, const char *str)
| Attach parser to a null-terminate string.
void | jx_parser_read_string_and_length (struct jx_parser *p, const char *str, int length)
| Attach parser to a raw string with known length.
void | jx_parser_read_link (struct jx_parser *p, struct link *l, time_t stoptime)
| Attach parser to a link.
struct jx * | jx_parser_yield (struct jx_parser *p)
| Parse and return a single value.
struct jx * | jx_parse (struct jx_parser *p)
| Parse a JX expression.
int | jx_parser_errors (struct jx_parser *p)
| Return number of parse errors.
const char * | jx_parser_error_string (struct jx_parser *p)
| Return text of first parse error encountered.
void | jx_parser_delete (struct jx_parser *p)
| Delete a parser.

## Detailed Description

Parse JSON strings and files into JX expressions.

This module parses arbirary JSON expressions according to the definition at json.org, with the following exceptions:

1. Atomic values are limited to 4KB in size.
2. Bare identifiers are permitted, to enable expression evaluation.

## Function Documentation

## jx_parse_string()

struct jx * jx_parse_string | ( | const char * | str | ) |

Parse a JSON string to a JX expression.

Parameters

  str | A null-terminated C string containing JSON data.

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse_string_and_length()

struct jx * jx_parse_string_and_length | ( | const char * | str,
|  | int | length )

Parse a JSON string to a JX expression.

Parameters

  str | An unterminated string containing JSON data.
  Length | of the string in bytes.

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse_stream()

struct jx * jx_parse_stream | ( | FILE * | file | ) |

Parse a standard IO stream to a JX expression.

Parameters

  file | A stream containing JSON data.

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse_file()

struct jx * jx_parse_file | ( | const char * | name | ) |

Parse a file to a JX expression.

Parameters

  name | The name of a file containing JSON data.

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse_link()

struct jx * jx_parse_link | ( | struct link * | l,
|  | time_t | stoptime )

Parse a network link to a JX expression.

Parameters

  l | A link pointer (opaque struct).
  stoptime | The absolute time at which to stop.

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse_cmd_args()

struct jx * jx_parse_cmd_args | ( | struct jx * | jx_args,
|  | char * | args_file )

Parse a jx argument file from a commandline option.

The passed-in object is consumed.

Parameters

  jx_args | A JX object to add args to.
  args_file | Name of the jx_args file that will be read in.

Returns
  An augmented JX object.
  NULL on failure.

## jx_parse_cmd_define()

int jx_parse_cmd_define | ( | struct jx * | jx_args,
|  | char * | define_stmt )

Parse a jx define statement from a commandline option.

Parameters

  jx_args | A JX object to add args to.
  define_stmt | Command line value of from VAR=EXPR.

Returns
  1 on success.
  0 on failure.

## jx_parser_create()

struct jx_parser * jx_parser_create | ( | bool | strict_mode | ) |

Create a JX parser object.

Returns
  A parser object.

## jx_parser_read_stream()

void jx_parser_read_stream | ( | struct jx_parser * | p,
|  | FILE * | file )

Attach parser to a file.

Parameters

  p | A parser object.
  file | A standard IO stream.

## jx_parser_read_string()

void jx_parser_read_string | ( | struct jx_parser * | p,
|  | const char * | str )

Attach parser to a null-terminate string.

Parameters

  p | A parser object.
  str | A JSON string to parse.

## jx_parser_read_string_and_length()

void jx_parser_read_string_and_length | ( | struct jx_parser * | p,
|  | const char * | str,
|  | int | length )

Attach parser to a raw string with known length.

Parameters

  p | A parser object.
  str | A JSON string to parse.
  length | The length of the string in bytes.

## jx_parser_read_link()

void jx_parser_read_link | ( | struct jx_parser * | p,
|  | struct link * | l,
|  | time_t | stoptime )

Attach parser to a link.

Parameters

  p | A parser object.
  l | A link object.
  stoptime | The absolute time at which to stop.

## jx_parser_yield()

struct jx * jx_parser_yield | ( | struct jx_parser * | p | ) |

Parse and return a single value.

This function is useful for streaming multiple independent values from a single source.

Parameters

  p | A parser object

Returns
  A JX expression which must be deleted with jx_delete. If the parse fails or no JSON value is present, null is returned.

## jx_parse()

struct jx * jx_parse | ( | struct jx_parser * | p | ) |

Parse a JX expression.

Note that in the event of a parse error, this function can return a partial result, reflecting the text that was parseable. You must call jx_parser_errors to determine if the parse was successul.

Parameters

  p | A parser created by jx_parser_create.

Returns
  A JX expression, or null if nothing was parsed.

## jx_parser_errors()

int jx_parser_errors | ( | struct jx_parser * | p | ) |

Return number of parse errors.

Parameters

  p | A parser object.

Returns
  Number of parse errors encountered.

## jx_parser_error_string()

const char * jx_parser_error_string | ( | struct jx_parser * | p | ) |

Return text of first parse error encountered.

Parameters

  p | A parser object.

Returns
  Error string, if available, null otherwise.

## jx_parser_delete()

void jx_parser_delete | ( | struct jx_parser * | p | ) |

Delete a parser.

Parameters

  p | The parser to delete.