ESO Recipe Execution Tool  3.13
Classes | Functions
JSON Utilities

Classes

struct  er_json_node
 
struct  er_json_array_iterator
 
struct  er_json_object_iterator
 

Functions

cpl_error_code er_frameset_to_json (const cpl_frameset *frameset, const char *json_file)
 Write a JSON file with the contents of a frameset. More...
 
cpl_error_code er_frameset_to_text (const cpl_frameset *frameset, const char *text_file)
 Write a text file with the contents of a frameset. More...
 
cpl_error_code er_recipe_parameterlist_to_json (const cpl_parameterlist *plist, const char *recipe_name, const char *json_file)
 Write a JSON file with the contents of a parameterlist. More...
 
char * er_plugin_to_json (const cpl_plugin *plugin)
 Serialises a CPL plugin object to JSON text. More...
 
void er_json_node_delete (er_json_node *obj)
 Delete a parse tree JSON node returned by er_json_parse(). More...
 
er_json_type er_json_node_type (const er_json_node *obj)
 Return the type of the JSON node. More...
 
const char * er_json_node_location (const er_json_node *obj)
 Returns the node's location in the original JSON text. More...
 
cpl_boolean er_json_node_get_bool (const er_json_node *obj)
 Return the boolean value for a JSON node. More...
 
double er_json_node_get_number (const er_json_node *obj)
 Returns the number value for a JSON node. More...
 
const char * er_json_node_get_string (const er_json_node *obj)
 Returns the string value for a JSON node. More...
 
cpl_size er_json_node_array_size (const er_json_node *obj)
 Returns the size of an array node. More...
 
cpl_boolean er_json_node_array_empty (const er_json_node *obj)
 Checks if the array node is empty or not. More...
 
er_json_array_iterator er_json_node_array_begin (const er_json_node *obj)
 Gets an iterator to the first element of the array. More...
 
er_json_array_iterator er_json_node_array_end (const er_json_node *obj)
 Gets an iterator pointing to one past the last element of the array. More...
 
er_json_array_iterator er_json_node_array_next (const er_json_node *obj, er_json_array_iterator current)
 Moves to the next position in an array. More...
 
er_json_array_iterator er_json_node_array_previous (const er_json_node *obj, er_json_array_iterator current)
 Moves to the previous position in an array. More...
 
const er_json_nodeer_json_node_array_get (const er_json_node *obj, er_json_array_iterator iterator)
 Returns the corresponding array item pointed to by an iterator. More...
 
cpl_size er_json_node_object_size (const er_json_node *obj)
 Returns the size of an object node. More...
 
cpl_boolean er_json_node_object_empty (const er_json_node *obj)
 Checks if the object node is empty or not. More...
 
er_json_object_iterator er_json_node_object_begin (const er_json_node *obj)
 Gets an iterator to the first attribute of the object. More...
 
er_json_object_iterator er_json_node_object_end (const er_json_node *obj)
 Gets an iterator pointing to one past the last attribute of the object. More...
 
er_json_object_iterator er_json_node_object_next (const er_json_node *obj, er_json_object_iterator current)
 Moves to the next attribute in an object. More...
 
er_json_object_iterator er_json_node_object_previous (const er_json_node *obj, er_json_object_iterator current)
 Moves to the previous attribute in an object. More...
 
const char * er_json_node_object_get_key (const er_json_node *obj, er_json_object_iterator iterator)
 Returns the corresponding attribute name pointed to by an iterator. More...
 
const er_json_nodeer_json_node_object_get_value (const er_json_node *obj, er_json_object_iterator iterator)
 Returns the corresponding attribute value pointed to by an iterator. More...
 
const er_json_nodeer_json_node_object_get (const er_json_node *obj, const char *key)
 Finds the value for a particular attribute in an object node. More...
 
cpl_error_code er_json_find_line_column (const char *json, const char *location, int *line, int *column)
 Finds line and column numbers for a character position within a text. More...
 
er_json_nodeer_json_parse (const char *json)
 Parses a JSON text and produces a corresponding parse tree. More...
 
er_stringarray_ter_json_to_string_array (const er_json_node *parsetree, const char *json)
 Converts a parsed JSON array node into a er_stringarray_t object. More...
 

Detailed Description

This module allows to write some CPL objects to JSON format. There is a recursive descent parser provided that also allows to parse JSON text into a parse tree. The parser should be compatible with UTF-8 and has an expanded number range, specifically NaN and infinity are accepted. Additional utility functions provide conversion of the parse tree back into CPL objects.

Synopsis:
#include <er_json.h>

Function Documentation

cpl_error_code er_frameset_to_json ( const cpl_frameset *  frameset,
const char *  json_file 
)

Write a JSON file with the contents of a frameset.

Parameters
framesetThe frameset to export
json_fileName of the JSON file to write
Returns
CPL_ERROR_NONE on success.

This function will export the content of a frameset to a JSON format which can be machine readable. The format looks like:

[
 {
   "name": "ifu_trace.fits",
   "category": "IFU_TRACE"
 },
 {
   "name": "ifu_transmission.fits",
   "category": "IFU_TRANSMISSION"
 }
]
cpl_error_code er_frameset_to_text ( const cpl_frameset *  frameset,
const char *  text_file 
)

Write a text file with the contents of a frameset.

Parameters
framesetThe frameset to export
text_fileName of the JSON file to write
Returns
CPL_ERROR_NONE on success.

This function will export the contents of the frameset to a text human readable file, like the one used for the input sof. The output will look like this:

ifu_trace.fits     IFU_TRACE
ifu_transmission.fits     IFU_TRANSMISSION
cpl_error_code er_json_find_line_column ( const char *  json,
const char *  location,
int *  line,
int *  column 
)

Finds line and column numbers for a character position within a text.

Parameters
[in]jsonOriginal JSON text.
[in]locationA character position in the text, i.e. within json.
[out]linePointer to an integer that will contain the computed line number.
[out]columnPointer to an integer that will contain the computed column number.
Returns
CPL_ERROR_NONE on success, or an appropriate error code if the input pointers were not valid.

This function will compute the line and column number corresponding to the given character location within the JSON text.

er_json_array_iterator er_json_node_array_begin ( const er_json_node obj)

Gets an iterator to the first element of the array.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_ARRAY.
Returns
An iterator pointer or NULL if this node is not valid. A CPL error is set if an error occurs.

For an array type node this function returns an iterator to the first element of the array.

cpl_boolean er_json_node_array_empty ( const er_json_node obj)

Checks if the array node is empty or not.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_ARRAY.
Returns
CPL_TRUE if the array is empty or CPL_FALSE otherwise. If the node is not valid CPL_FALSE is returned and one should check this error condition with cpl_error_get_code().

For array type JSON nodes this function will test if the array is empty.

er_json_array_iterator er_json_node_array_end ( const er_json_node obj)

Gets an iterator pointing to one past the last element of the array.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_ARRAY.
Returns
An iterator pointer or NULL if this node is not valid. A CPL error is set if an error occurs.

For an array type node this function returns an iterator marking a position that is one element past the end of the array. This allows to construct the following kind of iteration loop:

1 for (er_json_array_iterator iter = er_json_node_array_begin(obj);
2  iter != er_json_node_array_end(obj);
3  iter = er_json_node_array_next(obj, iter))
4 {
5  ...
6 }
const er_json_node* er_json_node_array_get ( const er_json_node obj,
er_json_array_iterator  iterator 
)

Returns the corresponding array item pointed to by an iterator.

Parameters
objThe JSON node to from which iterator was created. Must be a node with er_json_node_type() returning JSON_ARRAY.
iteratorThe iterator object pointing to the item of interest.
Returns
The child JSON node item or NULL if the iterator or parent array node is invalid. A CPL error is set if an error occurs.

For array type nodes this function returns the child item pointed to by the given iterator. The iterator must have been created from the given array node.

er_json_array_iterator er_json_node_array_next ( const er_json_node obj,
er_json_array_iterator  current 
)

Moves to the next position in an array.

Parameters
objThe JSON node to from which current was created. Must be a node with er_json_node_type() returning JSON_ARRAY.
currentThe iterator object being incremented.
Returns
The incremented iterator or NULL if the current iterator or array node is invalid. A CPL error is set if an error occurs.

For array type nodes this will increment an iterator object that was created from the node. i.e. move the iterator to the next position in the array.

er_json_array_iterator er_json_node_array_previous ( const er_json_node obj,
er_json_array_iterator  current 
)

Moves to the previous position in an array.

Parameters
objThe JSON node to from which current was created. Must be a node with er_json_node_type() returning JSON_ARRAY.
currentThe iterator object being decremented.
Returns
The decremented iterator or NULL if the current iterator or array node is invalid. A CPL error is set if an error occurs.

For array type nodes this will decrement an iterator object that was created from the node. i.e. move the iterator to the previous position in the array.

cpl_size er_json_node_array_size ( const er_json_node obj)

Returns the size of an array node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_ARRAY.
Returns
The number of elements in the array or -1 if the node is not valid. A CPL error is set if an error occurs.

For array type JSON nodes this will return the number of elements in the array.

void er_json_node_delete ( er_json_node obj)

Delete a parse tree JSON node returned by er_json_parse().

Parameters
objThe parse tree object to be deleted.

This function must be called on the resultant object from a call to the er_json_parse() function when it is no longer needed. This will free the allocated buffers.

cpl_boolean er_json_node_get_bool ( const er_json_node obj)

Return the boolean value for a JSON node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_BOOL.
Returns
The CPL_TRUE or CPL_FALSE value. If this was not a valid node then CPL_FALSE is returned by default, cpl_error_get_code() can be used to check for such errors.

For boolean JSON nodes this function will return its value as a cpl_boolean.

double er_json_node_get_number ( const er_json_node obj)

Returns the number value for a JSON node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_NUMBER.
Returns
The floating point value or NaN (Not a Number) if this was not a valid node. cpl_error_get_code() can be used to check if the node really contains a NaN value or if it was in fact invalid.

For a number type JSON node this function will return its value as a double precision floating point number.

const char* er_json_node_get_string ( const er_json_node obj)

Returns the string value for a JSON node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_STRING.
Returns
The string value or NULL if the node is not valid. A CPL error is set if an error occurs.

For a string type JSON node this function will return its value as a null terminated character string.

const char* er_json_node_location ( const er_json_node obj)

Returns the node's location in the original JSON text.

Parameters
objThe JSON node to query.
Returns
The string position within the original JSON text or NULL if this node is not valid. A CPL error is set if an error occurs.

Returns the string location within the original JSON text that this JSON node was parsed from. Allows to calculate the line and column numbers for error messages using er_json_find_line_column().

er_json_object_iterator er_json_node_object_begin ( const er_json_node obj)

Gets an iterator to the first attribute of the object.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_OBJECT.
Returns
An iterator pointer or NULL if this node is not valid. A CPL error is set if an error occurs.

For an object type node this function returns an iterator to the first attribute of the object.

cpl_boolean er_json_node_object_empty ( const er_json_node obj)

Checks if the object node is empty or not.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_OBJECT.
Returns
CPL_TRUE if the object has no attributes or CPL_FALSE otherwise. If the node is not valid CPL_FALSE is returned and one should check this error condition with cpl_error_get_code().

For object type JSON nodes this function will test if the object contains any attributes.

er_json_object_iterator er_json_node_object_end ( const er_json_node obj)

Gets an iterator pointing to one past the last attribute of the object.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_OBJECT.
Returns
An iterator pointer or NULL if this node is not valid. A CPL error is set if an error occurs.

For an object type node this function returns an iterator marking a position that is one attribute past the end of the object's attribute list. This allows to construct the following kind of iteration loop:

1 for (er_json_object_iterator iter = er_json_node_object_begin(obj);
2  iter != er_json_node_object_end(obj);
3  iter = er_json_node_object_next(obj, iter))
4 {
5  ...
6 }
const er_json_node* er_json_node_object_get ( const er_json_node obj,
const char *  key 
)

Finds the value for a particular attribute in an object node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_OBJECT.
keyThe name of the attribute to search for in the object node.
Returns
The attribute's value node or NULL if no such attribute exists. If the parent node being queries is not valid then NULL is also returned and an error code is set, which can be queried with cpl_error_get_code().

This function will try to find an attribute in an object type JSON node. The attribute is named by the given key. If such an attribute is found it's corresponding value is returned or NULL if no such attribute can be found.

const char* er_json_node_object_get_key ( const er_json_node obj,
er_json_object_iterator  iterator 
)

Returns the corresponding attribute name pointed to by an iterator.

Parameters
objThe JSON node to from which iterator was created. Must be a node with er_json_node_type() returning JSON_OBJECT.
iteratorThe iterator object pointing to the attribute of interest.
Returns
The attribute name as a string, or NULL if the iterator or parent object node is invalid. A CPL error is set if an error occurs.

For object type nodes this function returns the key or attribute name pointed to by the given iterator. The iterator must have been created from the given object node.

const er_json_node* er_json_node_object_get_value ( const er_json_node obj,
er_json_object_iterator  iterator 
)

Returns the corresponding attribute value pointed to by an iterator.

Parameters
objThe JSON node to from which iterator was created. Must be a node with er_json_node_type() returning JSON_OBJECT.
iteratorThe iterator object pointing to the attribute of interest.
Returns
The attribute's value node object, or NULL if the iterator or parent node is invalid. A CPL error is set if an error occurs.

For object type nodes this function returns the attribute's value, pointed to by the given iterator. The iterator must have been created from the given object node.

er_json_object_iterator er_json_node_object_next ( const er_json_node obj,
er_json_object_iterator  current 
)

Moves to the next attribute in an object.

Parameters
objThe JSON node to from which current was created. Must be a node with er_json_node_type() returning JSON_OBJECT.
currentThe iterator object being incremented.
Returns
The incremented iterator or NULL if the current iterator or object node is invalid. A CPL error is set if an error occurs.

For object type nodes this will increment an iterator object that was created from the node. i.e. move the iterator to the next position in the object's attribute list.

er_json_object_iterator er_json_node_object_previous ( const er_json_node obj,
er_json_object_iterator  current 
)

Moves to the previous attribute in an object.

Parameters
objThe JSON node to from which current was created. Must be a node with er_json_node_type() returning JSON_OBJECT.
currentThe iterator object being decremented.
Returns
The decremented iterator or NULL if the current iterator or object node is invalid. A CPL error is set if an error occurs.

For object type nodes this will decrement an iterator object that was created from the node. i.e. move the iterator to the previous position in the object's attribute list.

cpl_size er_json_node_object_size ( const er_json_node obj)

Returns the size of an object node.

Parameters
objThe JSON node to query. Must be a node with er_json_node_type() returning JSON_OBJECT.
Returns
The number of attributes in the object or -1 if the node is not valid. A CPL error is set if an error occurs.

For object type JSON nodes this will return the number of attributes for the object.

er_json_type er_json_node_type ( const er_json_node obj)

Return the type of the JSON node.

Parameters
objThe JSON node to query.
Returns
The type code for this JSON node or JSON_NULL if obj is invalid. Must use cpl_error_get_code() to confirm if it was invalid.

This returns the type code that can be used to figure out what kind of JSON node one is dealing with. This is important to decide which functions can be used with this node. e.g. the array functions or object functions etc. Valid type codes returned by this function are one of the following:

  • JSON_NULL
  • JSON_BOOL
  • JSON_NUMBER
  • JSON_STRING
  • JSON_ARRAY
  • JSON_OBJECT
er_json_node* er_json_parse ( const char *  json)

Parses a JSON text and produces a corresponding parse tree.

Parameters
jsonThe JSON null terminated text string to parse.
Returns
A JSON node object to the root of the parse tree, or NULL if there was a parse error. In that case a CPL error code with an appropriate message is set.

This function will parse the input JSON text string and produce a parse tree. The parse tree is a tree of er_json_node objects representing the parsed information. The tree can be navigated to extract the converted string, boolean and floating point number data.

er_stringarray_t* er_json_to_string_array ( const er_json_node parsetree,
const char *  json 
)

Converts a parsed JSON array node into a er_stringarray_t object.

Parameters
parsetreeThe parse tree for the JSON text, as produced by the er_json_parse() function. This can be a subnode of the result produced by er_json_parse().
jsonThe original JSON text from which the parsetree node was produced.
Returns
CPL_ERROR_NONE on success or an appropriate error code otherwise.

Converts a JSON array node that is returned by the er_json_parse() function, into a er_stringarray_t object, which contains a list of strings. One of the subnodes of the resultant parse tree from er_json_parse() can be used instead, if we only want to convert a child element from the JSON text.

char* er_plugin_to_json ( const cpl_plugin *  plugin)

Serialises a CPL plugin object to JSON text.

Parameters
pluginThe CPL plugin object to convert.
Returns
The JSON test corresponding to the CPL plugin, otherwise NULL if an error occurred.

This function will produce JSON text that corresponds to a CPL plugin object. The following is an example of the produced JSON format:

{
  "class": "Recipe",
  "name": "somerecipe",
  "version": 10205,
  "synopsis": "recipe",
  "description": "This is a recipe",
  "author": "Some Author",
  "email": "someone@eso.org",
  "copyright": "copyright message",
  "parameters": [
    {
      "name": "somerecipe.par1",
      "class": "value",
      "id": 0,
      "description": "integer parameter",
      "context": "somerecipe",
      "value": 12,
      "default": 5,
      "present": false,
      "tag": null,
      "cli_enabled": true,
      "cli_alias": "somerecipe.par1",
      "env_enabled": true,
      "env_alias": "somerecipe.par1",
      "cfg_enabled": true,
      "cfg_alias": "somerecipe.par1"
    }
  ],
  "frames": [
    {
      "filename": "test.fits",
      "tag": "RAW",
      "type": 2,
      "group": 1,
      "level": 3
    }
  ]
}
Note
The caller must free the result with cpl_free() once it is no longer needed.
cpl_error_code er_recipe_parameterlist_to_json ( const cpl_parameterlist *  plist,
const char *  recipe_name,
const char *  json_file 
)

Write a JSON file with the contents of a parameterlist.

Parameters
plistThe parameter list to export
recipe_nameThe recipe this parameter list applies to
json_fileName of the JSON file to write
Returns
CPL_ERROR_NONE on success.

This function exports the content of a parameter list to a machine readable JSON format. The output looks like:

[
 {
   "name": "vimos.Parameters.stacking.singleframes",
   "value": true,
   "display_name": "AllowSingleFrames",
   "description": "Frame combination method is ignored.",
   "recipe": "vmbias"
 },
 {
   "name": "vimos.Parameters.stacking.method",
   "value": "Median",
   "display_name": "StackMethod",
   "description": "Frame combination method",
   "recipe": "vmbias"
 }
]