CtplEnviron

CtplEnviron — Environment

Functions

Types and Values

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.