![]() |
![]() |
![]() |
CTPL Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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);
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
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.
#define CTPL_ENVIRON_ERROR (ctpl_environ_error_quark ())
Error domain of CtplEnviron.
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.
gboolean (*CtplEnvironForeachFunc) (CtplEnviron *env, const gchar *symbol, const CtplValue *value, gpointer user_data);
User function for ctpl_environ_foreach()
.
|
The CtplEnviron on which the function was called |
|
The current symbol |
|
The symbol's value |
|
User data passed to ctpl_environ_foreach()
|
Returns : |
TRUE to continue enumerating environ, FALSE to stop.
|
CtplEnviron * ctpl_environ_new (void);
Creates a new CtplEnviron.
Returns : |
A new CtplEnviron |
CtplEnviron * ctpl_environ_ref (CtplEnviron *env);
Adds a reference to a CtplEnviron.
|
a CtplEnviron |
Returns : |
The environ |
Since 0.3
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.
|
a CtplEnviron |
Since 0.3
const CtplValue * ctpl_environ_lookup (const CtplEnviron *env, const gchar *symbol);
Looks up for a symbol in the given CtplEnviron.
|
A CtplEnviron |
|
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.
|
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.
|
A CtplEnviron |
|
The symbol name |
|
The symbol value |
void ctpl_environ_push_int (CtplEnviron *env, const gchar *symbol, glong value);
Pushes an integer symbol into a CtplEnviron. See ctpl_environ_push()
.
|
A CtplEnviron |
|
A symbol name |
|
The symbol value |
void ctpl_environ_push_float (CtplEnviron *env, const gchar *symbol, gdouble value);
Pushes a float symbol into a CtplEnviron. See ctpl_environ_push()
.
|
A CtplEnviron |
|
A symbol name |
|
The symbol value |
void ctpl_environ_push_string (CtplEnviron *env, const gchar *symbol, const gchar *value);
Pushes a string symbol into a CtplEnviron. See ctpl_environ_push()
.
|
A CtplEnviron |
|
A symbol name |
|
The symbol value |
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.
|
A CtplEnviron |
|
A symbol name |
|
out) (allow-none. out. allow-none. |
Returns : |
Whether a value has been poped. |
Since 0.3
void ctpl_environ_foreach (CtplEnviron *env, CtplEnvironForeachFunc func, gpointer user_data);
Calls func
on each symbol of the environment.
|
A CtplEnviron |
|
A CtplEnvironForeachFunc |
|
user data to pass to func
|
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
.
|
A CtplEnviron |
|
Source environ to merge with env
|
|
Whether to merge symbols that exists in both environs |
gboolean ctpl_environ_add_from_stream (CtplEnviron *env, CtplInputStream *stream, GError **error);
Loads an environment description from a CtplInputStream.
|
A CtplEnviron to fill |
|
A CtplInputStream from where read the environment description. |
|
Return location for an error, or NULL to ignore them
|
Returns : |
TRUE on success, FALSE otherwise.
|
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.
|
A CtplEnviron to fill |
|
The path of the file from which load the environment description, in the GLib's filename encoding |
|
Return location for an error, or NULL to ignore them
|
Returns : |
TRUE on success, FALSE otherwise.
|
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()
.
|
A CtplEnviron to fill |
|
A string containing an environment description |
|
Return location for an error, or NULL to ignore them
|
Returns : |
TRUE on success, FALSE otherwise.
|