CamelSExp: Camel Reference Manual

## CamelSExp CamelSExp |

## Functions

CamelSExpResult * | (*CamelSExpFunc) ()
CamelSExpResult * | (*CamelSExpIFunc) ()
CamelSExp * | camel_sexp_new ()
void | camel_sexp_add_function ()
void | camel_sexp_add_ifunction ()
void | camel_sexp_add_variable ()
void | camel_sexp_remove_symbol ()
gint | camel_sexp_set_scope ()
void | camel_sexp_input_text ()
void | camel_sexp_input_file ()
gint | camel_sexp_parse ()
CamelSExpResult * | camel_sexp_eval ()
CamelSExpResult * | camel_sexp_term_eval ()
CamelSExpResult * | camel_sexp_result_new ()
void | camel_sexp_result_free ()
void | camel_sexp_resultv_free ()
void | camel_sexp_encode_bool ()
void | camel_sexp_encode_string ()
void | camel_sexp_fatal_error ()
const gchar * | camel_sexp_error ()
CamelSExpTerm * | camel_sexp_parse_value ()
gboolean | camel_sexp_evaluate_occur_times ()

## Types and Values

enum | CamelSExpResultType
struct | CamelSExpResult
enum | CamelSExpTermType
struct | CamelSExpSymbol
struct | CamelSExpTerm
struct | CamelSExp

## Object Hierarchy

        GObject
        ╰── CamelSExp

## Description

## Functions

### CamelSExpFunc ()

    CamelSExpResult *
    (*CamelSExpFunc) (CamelSExp *sexp,
                      gint argc,
                      CamelSExpResult **argv,
                      gpointer user_data);

Callback type for function symbols used with `camel_sexp_add_function()`.

#### Parameters

sexp | a CamelSExp |
argc | count of arguments |
argv | array of values of the arguments. | [in][array length=argc]
user_data | user data as passed to `camel_sexp_add_function()` |

#### Returns

Result of the function call, allocated by `camel_sexp_result_new()`.

Since: 3.4

### CamelSExpIFunc ()

    CamelSExpResult *
    (*CamelSExpIFunc) (CamelSExp *sexp,
                       gint argc,
                       CamelSExpTerm **argv,
                       gpointer user_data);

Callback type for function symbols used with `camel_sexp_add_ifunction()`.

#### Parameters

sexp | a CamelSExp |
argc | count of arguments |
argv | array of values of the arguments. | [in][array length=argc]
user_data | user data as passed to `camel_sexp_add_ifunction()` |

#### Returns

Result of the function call, allocated by `camel_sexp_result_new()`.

Since: 3.4

### camel_sexp_new ()

    CamelSExp *
    camel_sexp_new (void);

#### Returns

a new CamelSExp.

[transfer full]

Since: 3.4

### camel_sexp_add_function ()

    void
    camel_sexp_add_function (CamelSExp *sexp,
                             guint scope,
                             const gchar *name,
                             CamelSExpFunc func,
                             gpointer user_data);

Adds a function symbol which can not perform short evaluation. Use `camel_sexp_add_ifunction()` for functions which can.

#### Parameters

sexp | a CamelSExp |
scope | a scope |
name | a function name |
func | a function callback. | [scope call][closure user_data]
user_data | user data for `func` |

Since: 3.4

### camel_sexp_add_ifunction ()

    void
    camel_sexp_add_ifunction (CamelSExp *sexp,
                              guint scope,
                              const gchar *name,
                              CamelSExpIFunc ifunc,
                              gpointer user_data);

Adds a function symbol which can perform short evaluation, or doesn't execute everything. Use `camel_sexp_add_function()` for any other types of the function symbols.

#### Parameters

sexp | a CamelSExp |
scope | a scope |
name | a function name |
ifunc | a function callback. | [scope call][closure user_data]
user_data | user data for `ifunc` |

Since: 3.4

### camel_sexp_add_variable ()

    void
    camel_sexp_add_variable (CamelSExp *sexp,
                             guint scope,
                             const gchar *name,
                             CamelSExpTerm *value);

Adds a variable named `name` to the given `scope` , set to the given `value` .

#### Parameters

sexp | a CamelSExp |
scope | a scope |
name | a variable name |
value | a variable value, as a CamelSExpTerm |

Since: 3.4

### camel_sexp_remove_symbol ()

    void
    camel_sexp_remove_symbol (CamelSExp *sexp,
                              guint scope,
                              const gchar *name);

Revoes a symbol from a scope.

#### Parameters

sexp | a CamelSExp |
scope | a scope |
name | a symbol name |

Since: 3.4

### camel_sexp_set_scope ()

    gint
    camel_sexp_set_scope (CamelSExp *sexp,
                          guint scope);

sets the current scope for the scanner.

#### Parameters

sexp | a CamelSExp |
scope | a scope to set |

#### Returns

the previous scope id

Since: 3.4

### camel_sexp_input_text ()

    void
    camel_sexp_input_text (CamelSExp *sexp,
                           const gchar *text,
                           gint len);

Prepares to scan a text buffer.

#### Parameters

sexp | a CamelSExp |
text | a text buffer to scan |
len | the length of the text buffer |

Since: 3.4

### camel_sexp_input_file ()

    void
    camel_sexp_input_file (CamelSExp *sexp,
                           gint fd);

Prepares to scan a file.

#### Parameters

sexp | a CamelSExp |
fd | a file descriptor |

Since: 3.4

### camel_sexp_parse ()

    gint
    camel_sexp_parse (CamelSExp *sexp);

#### Parameters

sexp | a CamelSExp |

Since: 3.4

### camel_sexp_eval ()

    CamelSExpResult *
    camel_sexp_eval (CamelSExp *sexp);

[skip]

#### Parameters

sexp | a CamelSExp |

Since: 3.4

### camel_sexp_term_eval ()

    CamelSExpResult *
    camel_sexp_term_eval (CamelSExp *sexp,
                          CamelSExpTerm *term);

Evaluates a part of the expression.

[skip]

#### Parameters

sexp | a CamelSExp |
term | a CamelSExpTerm to evaluate |

#### Returns

a newly allocated result of the evaluation. Free the returned pointer with `camel_sexp_result_free()`, when no longer needed.

[transfer full]

Since: 3.4

### camel_sexp_result_new ()

    CamelSExpResult *
    camel_sexp_result_new (CamelSExp *sexp,
                           gint type);

[skip]

#### Parameters

sexp | a CamelSExp |
type | type of the result, one of CamelSExpResultType |

#### Returns

A new CamelSExpResult result structure, associated with `sexp` . Free with `camel_sexp_result_free()`, when no longer needed.

[transfer full]

Since: 3.4

### camel_sexp_result_free ()

    void
    camel_sexp_result_free (CamelSExp *sexp,
                            CamelSExpResult *result);

Frees the `result` and its internal data. Does nothing, when the `result` is `NULL`.

#### Parameters

sexp | a CamelSExp |
result | a CamelSExpResult to free. | [nullable]

Since: 3.4

### camel_sexp_resultv_free ()

    void
    camel_sexp_resultv_free (CamelSExp *sexp,
                             gint argc,
                             CamelSExpResult **argv);

Frees an array of results.

#### Parameters

sexp | a CamelSExp |
argc | a count of the `argv` |
argv | an array of CamelSExpResult to free. | [array length=argc]

Since: 3.4

### camel_sexp_encode_bool ()

    void
    camel_sexp_encode_bool (GString *string,
                            gboolean v_bool);

Encode a bool into an s-expression `string` . Bools are encoded using #t #f syntax.

#### Parameters

string | Destination GString |
v_bool | the value |

Since: 3.4

### camel_sexp_encode_string ()

    void
    camel_sexp_encode_string (GString *string,
                              const gchar *v_string);

Add a c string `v_string` to the s-expression stored in the gstring `s` . Quotes are added, and special characters are escaped appropriately.

#### Parameters

string | Destination GString |
v_string | String expression. |

Since: 3.4

### camel_sexp_fatal_error ()

    void
    camel_sexp_fatal_error (CamelSExp *sexp,
                            const gchar *why,
                            ...);

Sets an error from the given format and stops execution. Int replaces previously set error, if any.

#### Parameters

sexp | a CamelSExp |
why | a string format to use |
... | parameters for the format |

Since: 3.4

### camel_sexp_error ()

    const gchar *
    camel_sexp_error (CamelSExp *sexp);

#### Parameters

sexp | a CamelSExp |

#### Returns

Set error string on the `sexp` , or `NULL`, when none is set.

[nullable]

Since: 3.4

### camel_sexp_parse_value ()

    CamelSExpTerm *
    camel_sexp_parse_value (CamelSExp *sexp);

[skip]

#### Parameters

sexp | a CamelSExp |

#### Returns

a CamelSExpTerm of the next token, or `NULL` when there is none.

[nullable][transfer none]

Since: 3.4

### camel_sexp_evaluate_occur_times ()

    gboolean
    camel_sexp_evaluate_occur_times (CamelSExp *sexp,
                                     time_t *start,
                                     time_t *end);

## Types and Values

### enum CamelSExpResultType

Defines type of a CamelSExpResult.

#### Members

CAMEL_SEXP_RES_ARRAY_PTR | type is a ptrarray, what it points to is implementation dependant |
CAMEL_SEXP_RES_INT | type is a number |
CAMEL_SEXP_RES_STRING | type is a pointer to a single string |
CAMEL_SEXP_RES_BOOL | boolean type |
CAMEL_SEXP_RES_TIME | time_t type |
CAMEL_SEXP_RES_UNDEFINED | unknown type |

Since: 3.4

### struct CamelSExpResult

    struct CamelSExpResult {
    	CamelSExpResultType type;
    	union {
    		GPtrArray *ptrarray;
    		gint number;
    		gchar *string;
    		gint boolean;
    		time_t time;
    	} value;
    	gboolean time_generator;
    	time_t occuring_start;
    	time_t occuring_end;
    	gpointer user_data; /* caller-managed user data */
    	GDestroyNotify free_user_data;
    };

#### Members

CamelSExpResultType `type`; | a CamelSExpResultType, defining the `value` type |
gboolean `time_generator`; | a boolean whether the occuring times are used |
time_t `occuring_start`; | start time |
time_t `occuring_end`; | end time |
gpointer `user_data`; | a custom user data the caller can set; it's completely managed by the caller (Since: 3.58). | [nullable]
GDestroyNotify `free_user_data`; | optional destroy callback for the `user_data` (Since: 3.58). | [nullable]

Since: 3.4

### enum CamelSExpTermType

Defines type of a CamelSExpTerm and partly also CamelSExpSymbol

#### Members

CAMEL_SEXP_TERM_INT | integer literal |
CAMEL_SEXP_TERM_BOOL | boolean literal |
CAMEL_SEXP_TERM_STRING | string literal |
CAMEL_SEXP_TERM_TIME | time_t literal (number of seconds past the epoch) |
CAMEL_SEXP_TERM_FUNC | normal function, arguments are evaluated before calling |
CAMEL_SEXP_TERM_IFUNC | immediate function, raw terms are arguments |
CAMEL_SEXP_TERM_VAR | variable reference |

Since: 3.4

### struct CamelSExpSymbol

    struct CamelSExpSymbol {
    	gint type;		/* TERM_FUNC or TERM_VAR */
    	gchar *name;
    	gpointer data;
    	union {
    		CamelSExpFunc func;
    		CamelSExpIFunc ifunc;
    	} f;
    };

Describes a function or a variable symbol

#### Members

gint `type`; | a type of the symbol, either CAMEL_SEXP_TERM_FUNC or CAMEL_SEXP_TERM_VAR |
gchar *`name`; | name of the symbol |
gpointer `data`; | user data for the callback |

Since: 3.4

### struct CamelSExpTerm

    struct CamelSExpTerm {
    	CamelSExpTermType type;
    	union {
    		gchar *string;
    		gint number;
    		gint boolean;
    		time_t time;
    		struct {
    			CamelSExpSymbol *sym;
    			CamelSExpTerm **terms;
    			gint termcount;
    		} func;
    		CamelSExpSymbol *var;
    	} value;
    };

#### Members

CamelSExpTermType `type`; | a type of the term; one of CamelSExpTermType |
CamelSExpSymbol *`var`; |  |

Since: 3.4

### struct CamelSExp

    struct CamelSExp;

Since: 3.4