![]() |
![]() |
![]() |
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
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.
#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 |
|
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
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.
|