API

group gaml

Public function definitions and types for Yc’s GAML parsing and dumping.

Typedefs

typedef struct y_gaml *y_Gaml

The public-facing type of the data in a GAML document.

Enums

enum y_GamlType

The types that a GAML item can be.

Values:

enumerator y_GAML_NIL

A NULL item.

enumerator y_GAML_BOOL

A boolean.

enumerator y_GAML_INT

An integer.

enumerator y_GAML_FLOAT

A float.

enumerator y_GAML_STRING

A string.

enumerator y_GAML_SYMBOL

A symbol.

enumerator y_GAML_ARRAY

An array.

enumerator y_GAML_OBJECT

An object (map).

Functions

y_Gaml y_gaml_create(void)

Creates an empty y_Gaml object.

This must be freed with y_gaml_free().

Returns:

An empty y_Gaml object, or NULL on error.

y_Gaml y_gaml_screate(void)

Creates an empty y_Gaml object using the stack allocator.

This must be freed with y_stackpool_free().

Returns:

An empty y_Gaml object, or NULL on error.

y_Status y_gaml_read(y_Gaml g, y_Path path)

Reads the GAML file at path into the y_Gaml object.

If the y_Gaml object is not empty, it is emptied first.

Parameters:
  • g – The y_Gaml object.

  • path – The path to the file.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

path must be valid.

y_Status y_gaml_fprint(y_Gaml g, y_File f)

Prints the GAML data to the file.

Parameters:
  • g – The GAML data to print.

  • f – The file to print to.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

f must not be NULL.

Pre:

f must be valid and open.

y_Status y_gaml_print(y_Gaml g)

Prints the GAML data to stdout.

Parameters:

g – The GAML data to print.

Returns:

An error code, if any.

Pre:

g must not be NULL.

y_GamlType y_gaml_type(y_Gaml g)

Returns the type of the GAML item.

Parameters:

g – The GAML item.

Returns:

The type of the item.

Pre:

g must not be NULL.

bool y_gaml_bool(y_Gaml g)

Returns the bool in the GAML item.

If the item is not of type y_GAML_BOOL, this panics.

Parameters:

g – The GAML item.

Returns:

The boolean value in the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_BOOL.

y_GamlInt y_gaml_int(y_Gaml g)

Returns the integer in the GAML item.

If the item is not of type y_GAML_INT, this panics.

Parameters:

g – The GAML item.

Returns:

The integer value in the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_INT.

double y_gaml_float(y_Gaml g)

Returns the float in the GAML item.

If the item is not of type y_GAML_FLOAT, this panics.

Parameters:

g – The GAML item.

Returns:

The float value in the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_FLOAT.

y_str y_gaml_str(y_Gaml g)

Returns the string in the GAML item.

If the item is not of type y_GAML_STRING, this panics. The string must not be freed.

Parameters:

g – The GAML item.

Returns:

The string value in the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_STRING.

y_str y_gaml_symbol(y_Gaml g)

Returns the symbol in the GAML item.

If the item is not of type y_GAML_SYMBOL, this panics. The symbol must not be freed.

Parameters:

g – The GAML item.

Returns:

The symbol value in the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_SYMBOL.

bool y_gaml_itemExists(y_Gaml g, const char *key, y_Gaml *res)

Returns true if an item with the provided key exists in the object.

Parameters:
  • g – The GAML item to search.

  • key – The item key.

  • res – If non-null, will be used to return the item.

Returns:

True if an item exists with key, false otherwise.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

y_Gaml y_gaml_getItem(y_Gaml g, const char *key)

Returns the GAML item at the specified key.

If g is not a y_GAML_OBJECT, this panics. It also panics if the key does not exist. The returned pointer is invalidated if any items are added to or removed from g.

Parameters:
  • g – The GAML item to search.

  • key – The item key.

Returns:

The GAML item at the key.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must exist in g.

size_t y_gaml_len(y_Gaml g)

Returns the length of the array item.

Parameters:

g – The GAML item to query.

Returns:

The length of the array at the item.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

y_Gaml y_gaml_getElem(y_Gaml g, size_t idx)

Returns the GAML item at the specified index.

If g is not a y_GAML_ARRAY, this panics. It also panics if the index is out of range. The returned pointer is invalidated if any items are added to or removed from g.

Parameters:
  • g – The GAML item to search.

  • idx – The item index.

Returns:

The GAML item at the index.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be in range.

y_Status y_gaml_addItem_object(y_Gaml g, const char *key, y_Gaml *res)

Adds an object item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_array(y_Gaml g, const char *key, y_Gaml *res)

Adds an array item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_nil(y_Gaml g, const char *key, y_Gaml *res)

Adds a nil item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_bool(y_Gaml g, const char *key, bool val, y_Gaml *res)

Adds a bool item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The value of the boolean to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_int(y_Gaml g, const char *key, y_ullong val, bool neg, y_Gaml *res)

Adds an integer item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The value of the integer to add.

  • neg – True if the value is negative, false otherwise.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_float(y_Gaml g, const char *key, double val, y_Gaml *res)

Adds a float item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The value of the float to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_str(y_Gaml g, const char *key, y_str val, y_Gaml *res)

Adds a string item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The string to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_cstr(y_Gaml g, const char *key, const y_uchar *val, y_Gaml *res)

Adds a string item, as a C string, to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The string to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

y_Status y_gaml_addItem_symbol(y_Gaml g, const char *key, y_str val, y_Gaml *res)

Adds a symbol item to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT. The symbol is copied; in other words, the given symbol is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The symbol to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must not exist in g.

Pre:

key must be a valid GAML key.

Pre:

val must begin with #.

y_Status y_gaml_addItem_csymbol(y_Gaml g, const char *key, const y_uchar *val, y_Gaml *res)

Adds a symbol item, as a C string, to the GAML item at the specified key.

This panics if the key already exists or if g is not of type y_GAML_OBJECT. The symbol is copied; in other words, the given symbol is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • key – The key to add the item at.

  • val – The symbol to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_OBJECT.

Pre:

key must not be NULL.

Pre:

key must be a valid GAML key.

Pre:

key must not exist in g.

Pre:

val must begin with #.

y_Status y_gaml_addElem_object(y_Gaml g, size_t idx, y_Gaml *res)

Adds an object item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_array(y_Gaml g, size_t idx, y_Gaml *res)

Adds an array item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_nil(y_Gaml g, size_t idx, y_Gaml *res)

Adds a nil item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_bool(y_Gaml g, size_t idx, bool val, y_Gaml *res)

Adds a boolean item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The value of the boolean to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_int(y_Gaml g, size_t idx, y_ullong val, bool neg, y_Gaml *res)

Adds an integer item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The value of the integer to add.

  • neg – True if the value is negative, false otherwise.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_float(y_Gaml g, size_t idx, double val, y_Gaml *res)

Adds a float item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The value of the float to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_str(y_Gaml g, size_t idx, y_str val, y_Gaml *res)

Adds a string item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The string to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_cstr(y_Gaml g, size_t idx, const y_uchar *val, y_Gaml *res)

Adds a string item, as a C string, to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The string to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

y_Status y_gaml_addElem_symbol(y_Gaml g, size_t idx, y_str val, y_Gaml *res)

Adds a symbol item to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The symbol to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

Pre:

val must begin with #.

y_Status y_gaml_addElem_csymbol(y_Gaml g, size_t idx, const y_uchar *val, y_Gaml *res)

Adds a symbol item, as a C string, to the GAML item at the specified index, pushing all elements at that index and later indices back one place.

This panics if g is not of type y_GAML_ARRAY or if the index is not in range. The string is copied; in other words, the given string is still owned by the caller.

Parameters:
  • g – The GAML item to add to.

  • idx – The index to add the item at.

  • val – The symbol to add.

  • res – A pointer to return the new item. Can be NULL.

Returns:

An error code, if any.

Pre:

g must not be NULL.

Pre:

g must be of type y_GAML_ARRAY.

Pre:

idx must be within range. It can be equal to the length.

Pre:

val must begin with #.

void y_gaml_change_int(y_Gaml g, y_ullong val, bool neg)

Changes the value of the integer item.

This panics if the item is not an integer item.

Parameters:
  • g – The item to change.

  • val – The value to change to.

  • neg – The new sign of the value.

Pre:

g must not be NULL.

Pre:

g must be an integer item.

void y_gaml_free(void *gaml)

Frees GAML data.

Parameters:

gaml – The GAML data to free.

Pre:

gaml must not be NULL.

struct y_GamlInt
#include <gaml.h>

A struct for an integer.