## CtplEnviron CtplEnviron — Environment |

## Synopsis

    #include <ctpl/ctpl.h>

    #define             CTPL_ENVIRON_ERROR
    enum                CtplEnvironError;
                        CtplEnviron;
    gboolean            (*CtplEnvironForeachFunc)           (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             const CtplValue *value,
                                                             gpointer user_data);
    CtplEnviron *       ctpl_environ_new                    (void);
    CtplEnviron *       ctpl_environ_ref                    (CtplEnviron *env);
    void                ctpl_environ_unref                  (CtplEnviron *env);
    const CtplValue *   ctpl_environ_lookup                 (const CtplEnviron *env,
                                                             const gchar *symbol);
    void                ctpl_environ_push                   (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             const CtplValue *value);
    void                ctpl_environ_push_int               (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             glong value);
    void                ctpl_environ_push_float             (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             gdouble value);
    void                ctpl_environ_push_string            (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             const gchar *value);
    gboolean            ctpl_environ_pop                    (CtplEnviron *env,
                                                             const gchar *symbol,
                                                             CtplValue **poped_value);
    void                ctpl_environ_foreach                (CtplEnviron *env,
                                                             CtplEnvironForeachFunc func,
                                                             gpointer user_data);
    void                ctpl_environ_merge                  (CtplEnviron *env,
                                                             const CtplEnviron *source,
                                                             gboolean merge_symbols);
    gboolean            ctpl_environ_add_from_stream        (CtplEnviron *env,
                                                             CtplInputStream *stream,
                                                             GError **error);
    gboolean            ctpl_environ_add_from_path          (CtplEnviron *env,
                                                             const gchar *path,
                                                             GError **error);
    gboolean            ctpl_environ_add_from_string        (CtplEnviron *env,
                                                             const gchar *string,
                                                             GError **error);

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

## Details

### CTPL_ENVIRON_ERROR

    #define CTPL_ENVIRON_ERROR  (ctpl_environ_error_quark ())

Error domain of CtplEnviron.

### enum CtplEnvironError

    typedef enum _CtplEnvironError
    {
      CTPL_ENVIRON_ERROR_LOADER_MISSING_SYMBOL,
      CTPL_ENVIRON_ERROR_LOADER_MISSING_VALUE,
      CTPL_ENVIRON_ERROR_LOADER_MISSING_SEPARATOR,
      CTPL_ENVIRON_ERROR_FAILED
    } CtplEnvironError;

Errors in the `CTPL_ENVIRON_ERROR` domain.

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

### CtplEnvironForeachFunc ()

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

User function for `ctpl_environ_foreach()`.

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

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

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

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

`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()`.

`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()`.

`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()`.

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

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

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

### Warning

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

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

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

`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()`.

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