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.

typedef enum y_GamlType y_GamlType: The types that a GAML item can be.

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_Gaml y_gaml_root(y_Gaml g)¶

Returns the root GAML node of the tree that the GAML item is in.

Parameters:: g – The GAML item.
Returns:: The root item.
Pre:: g must not be NULL.

y_Gaml y_gaml_parent(y_Gaml g)¶

Returns the parent of the item.

If the item is the root item, it returns itself.

Parameters:: g – The GAML item.
Returns:: The parent of the item, or itself if it is the root.
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.

long 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.

y_usize 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, y_usize 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, long 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, y_usize 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, y_usize 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, y_usize 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, y_usize 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, y_usize 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, y_usize idx, long 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, y_usize 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, y_usize 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, y_usize 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, y_usize 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.

Variables

const char *const y_gaml_type_names[y_GAML_OBJECT + 1]¶: An array of names corresponding to GAML types.

struct y_GamlInt¶: #include <gaml.h>

A struct for an integer.