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.