CTPL Reference Manual: CtplEnviron

## CtplEnviron CtplEnviron — Environment |

## Functions

#define | CTPL_ENVIRON_ERROR
gboolean | (*CtplEnvironForeachFunc) ()
CtplEnviron * | ctpl_environ_new ()
CtplEnviron * | ctpl_environ_ref ()
void | ctpl_environ_unref ()
const CtplValue * | ctpl_environ_lookup ()
void | ctpl_environ_push ()
void | ctpl_environ_push_int ()
void | ctpl_environ_push_float ()
void | ctpl_environ_push_string ()
gboolean | ctpl_environ_pop ()
void | ctpl_environ_foreach ()
void | ctpl_environ_merge ()
gboolean | ctpl_environ_add_from_stream ()
gboolean | ctpl_environ_add_from_path ()
gboolean | ctpl_environ_add_from_string ()

## Types and Values

enum | CtplEnvironError
| CtplEnviron

## Includes

    #include <ctpl/ctpl.h>

## Description

A CtplEnviron represents an environment of symbols used to lookup, push and pop symbols when computing a template.

Use `ctpl_environ_new()` to create a new environment; and then `ctpl_environ_push()`, `ctpl_environ_push_int()`, `ctpl_environ_push_float()` and `ctpl_environ_push_string()` to fill it.

CtplEnviron uses a GObject-style refcounting, via `ctpl_environ_ref()` and `ctpl_environ_unref()`.

Example 10. Creating and filling a environment

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CtplEnviron *env;

    env = ctpl_environ_new ()
    ctpl_environ_push_string (env, "symbol name", "symbol value");
    ctpl_environ_push_int (env, "response", 42);

    /* ... */

    ctpl_environ_unref (env);

Environments can also be loaded from CtplInputStreams, strings or files using `ctpl_environ_add_from_stream()`, `ctpl_environ_add_from_string()` or `ctpl_environ_add_from_path()`. Environment descriptions are of the form

`SYMBOL = VALUE;` and can contain comments. Comments start with a `#` (number sign) and end at the next line ending.

For more details, see the

environment description syntax.

## Functions

### CTPL_ENVIRON_ERROR

    #define CTPL_ENVIRON_ERROR  (ctpl_environ_error_quark ())

Error domain of CtplEnviron.

### CtplEnvironForeachFunc ()

    gboolean
    (*CtplEnvironForeachFunc) (CtplEnviron *env,
                               const gchar *symbol,
                               const CtplValue *value,
                               gpointer user_data);

User function for `ctpl_environ_foreach()`.

#### Parameters

env | The CtplEnviron on which the function was called |
symbol | The current symbol |
value | The symbol's value |
user_data | User data passed to `ctpl_environ_foreach()` |

#### Returns

`TRUE` to continue enumerating environ, `FALSE` to stop.

### ctpl_environ_new ()

    CtplEnviron *
    ctpl_environ_new (void);

Creates a new CtplEnviron.

#### Returns

A new CtplEnviron

### ctpl_environ_ref ()

    CtplEnviron *
    ctpl_environ_ref (CtplEnviron *env);

Adds a reference to a CtplEnviron.

#### Parameters

env | a CtplEnviron |

#### Returns

The environ

Since 0.3

### ctpl_environ_unref ()

    void
    ctpl_environ_unref (CtplEnviron *env);

Removes a reference from a CtplEnviron. If the reference count drops to 0, frees the environ and all its allocated resources.

#### Parameters

env | a CtplEnviron |

Since 0.3

### ctpl_environ_lookup ()

    const CtplValue *
    ctpl_environ_lookup (const CtplEnviron *env,
                         const gchar *symbol);

Looks up for a symbol in the given CtplEnviron.

#### Parameters

env | A CtplEnviron |
symbol | A symbol name |

#### Returns

The CtplValue holding the symbol's value, or `NULL` if the symbol can't be found. This value should not be modified or freed.

### ctpl_environ_push ()

    void
    ctpl_environ_push (CtplEnviron *env,
                       const gchar *symbol,
                       const CtplValue *value);

Pushes a symbol into a CtplEnviron. Pushing a symbol adds it or overwrites the value in place for it while keeping any already present value for latter poping. The push/pop concept is simple as a stack: when you push, you add a value on the top of a stack, and when you pop, you remove the top element of this stack, revealing the previous value.

#### Parameters

env | A CtplEnviron |
symbol | The symbol name |
value | The symbol value |

### ctpl_environ_push_int ()

    void
    ctpl_environ_push_int (CtplEnviron *env,
                           const gchar *symbol,
                           glong value);

Pushes an integer symbol into a CtplEnviron. See `ctpl_environ_push()`.

#### Parameters

env | A CtplEnviron |
symbol | A symbol name |
value | The symbol value |

### ctpl_environ_push_float ()

    void
    ctpl_environ_push_float (CtplEnviron *env,
                             const gchar *symbol,
                             gdouble value);

Pushes a float symbol into a CtplEnviron. See `ctpl_environ_push()`.

#### Parameters

env | A CtplEnviron |
symbol | A symbol name |
value | The symbol value |

### ctpl_environ_push_string ()

    void
    ctpl_environ_push_string (CtplEnviron *env,
                              const gchar *symbol,
                              const gchar *value);

Pushes a string symbol into a CtplEnviron. See `ctpl_environ_push()`.

#### Parameters

env | A CtplEnviron |
symbol | A symbol name |
value | The symbol value |

### ctpl_environ_pop ()

    gboolean
    ctpl_environ_pop (CtplEnviron *env,
                      const gchar *symbol,
                      CtplValue **poped_value);

Tries to pop a symbol from a CtplEnviron. See `ctpl_environ_push()` for details on pushing and poping. Use `ctpl_environ_lookup()` if you want to get the symbol's value without poping it from the environ.

#### Parameters

env | A CtplEnviron |
symbol | A symbol name |
poped_value | Return location for the poped value, or `NULL`. You must free this value with `ctpl_value_free()` when you no longer need it. This is set only if poping succeeded, so if this function returned `TRUE`. | [out][allow-none]

#### Returns

Whether a value has been poped.

Since 0.3

### ctpl_environ_foreach ()

    void
    ctpl_environ_foreach (CtplEnviron *env,
                          CtplEnvironForeachFunc func,
                          gpointer user_data);

Calls `func` on each symbol of the environment.

#### Parameters

env | A CtplEnviron |
func | A CtplEnvironForeachFunc |
user_data | user data to pass to `func` |

### ctpl_environ_merge ()

    void
    ctpl_environ_merge (CtplEnviron *env,
                        const CtplEnviron *source,
                        gboolean merge_symbols);

Merges an environment into another. If a symbol of the source environ already exists in the destination one, its value is either pushed if `merge_symbols` is true or ignored if `FALSE`.

Currently, symbol merging only pushes the topmost value from the source environ rather than pushing it entirely.

#### Parameters

env | A CtplEnviron |
source | Source environ to merge with `env` |
merge_symbols | Whether to merge symbols that exists in both environs |

### ctpl_environ_add_from_stream ()

    gboolean
    ctpl_environ_add_from_stream (CtplEnviron *env,
                                  CtplInputStream *stream,
                                  GError **error);

Loads an environment description from a CtplInputStream.

#### Parameters

env | A CtplEnviron to fill |
stream | A CtplInputStream from where read the environment description. |
error | Return location for an error, or `NULL` to ignore them |

#### Returns

`TRUE` on success, `FALSE` otherwise.

### ctpl_environ_add_from_path ()

    gboolean
    ctpl_environ_add_from_path (CtplEnviron *env,
                                const gchar *path,
                                GError **error);

Loads an environment description from a path. See `ctpl_environ_add_from_stream()`.

Errors can come from the `G_IO_ERROR` domain if the file loading failed, or from the `CTPL_ENVIRON_ERROR` domain if the parsing of the environment description failed.

#### Parameters

env | A CtplEnviron to fill |
path | The path of the file from which load the environment description, in the GLib's filename encoding |
error | Return location for an error, or `NULL` to ignore them |

#### Returns

`TRUE` on success, `FALSE` otherwise.

### ctpl_environ_add_from_string ()

    gboolean
    ctpl_environ_add_from_string (CtplEnviron *env,
                                  const gchar *string,
                                  GError **error);

Loads an environment description from a string. See `ctpl_environ_add_from_stream()`.

#### Parameters

env | A CtplEnviron to fill |
string | A string containing an environment description |
error | Return location for an error, or `NULL` to ignore them |

#### Returns

`TRUE` on success, `FALSE` otherwise.

## Types and Values

### enum CtplEnvironError

Errors in the `CTPL_ENVIRON_ERROR` domain.

#### Members

CTPL_ENVIRON_ERROR_LOADER_MISSING_SYMBOL | Missing symbol in environment description |
CTPL_ENVIRON_ERROR_LOADER_MISSING_VALUE | Missing value in environment description |
CTPL_ENVIRON_ERROR_LOADER_MISSING_SEPARATOR | Missing separator in environment description |
CTPL_ENVIRON_ERROR_FAILED | An error occurred |

### CtplEnviron

    typedef struct _CtplEnviron CtplEnviron;

Represents an environment.