ecoli_nodes - Man Page

struct ec_init
struct ec_node_type
struct ec_node_expr_eval_ops

#define EC_INIT_REGISTER(t)
#define EC_NO_ID   ''
#define EC_NODE_TYPE_REGISTER(t)
#define EC_NODE_TYPE_REGISTER_OVERRIDE(t)
#define EC_NODE_CMD(args...)
#define EC_NODE_OR(args...)
#define EC_NODE_SEQ(args...)
#define EC_NODE_SUBSET(args...)

typedef int ec_init_t(void)
typedef void ec_exit_t(void)
typedef int(* ec_node_set_config_t) (struct ec_node *node, const struct ec_config *config)
typedef int(* ec_parse_t) (const struct ec_node *node, struct ec_pnode *pstate, const struct ec_strvec *strvec)
typedef int(* ec_complete_t) (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)
typedef char *(* ec_node_desc_t) (const struct ec_node *)
typedef int(* ec_node_init_priv_t) (struct ec_node *)
typedef void(* ec_node_free_priv_t) (struct ec_node *)
typedef size_t(* ec_node_get_children_count_t) (const struct ec_node *)
typedef int(* ec_node_get_child_t) (const struct ec_node *, size_t i, struct ec_node **child, unsigned int *refs)
typedef struct ec_node *(* ec_node_dynamic_build_t) (struct ec_pnode *pstate, void *opaque)
typedef int(* ec_node_expr_eval_var_t) (void **result, void *userctx, const struct ec_pnode *var)
typedef int(* ec_node_expr_eval_pre_op_t) (void **result, void *userctx, void *operand, const struct ec_pnode *operator)
typedef int(* ec_node_expr_eval_post_op_t) (void **result, void *userctx, void *operand, const struct ec_pnode *operator)
typedef int(* ec_node_expr_eval_bin_op_t) (void **result, void *userctx, void *operand1, const struct ec_pnode *operator, void *operand2)
typedef int(* ec_node_expr_eval_parenthesis_t) (void **result, void *userctx, const struct ec_pnode *open_paren, const struct ec_pnode *close_paren, void *value)
typedef void(* ec_node_expr_eval_free_t) (void *result, void *userctx)

void ec_init_register (struct ec_init *test)
int ec_init (void)
void ec_exit (void)
int ec_node_type_register (struct ec_node_type *type, bool override)
const struct ec_node_type * ec_node_type_lookup (const char *name)
void ec_node_type_dump (FILE *out)
const struct ec_config_schema * ec_node_type_schema (const struct ec_node_type *type)
const char * ec_node_type_name (const struct ec_node_type *type)
struct ec_node * ec_node_from_type (const struct ec_node_type *type, const char *id)
struct ec_node * ec_node (const char *typename, const char *id)
struct ec_node * ec_node_clone (struct ec_node *node)
void ec_node_free (struct ec_node *node)
int ec_node_set_config (struct ec_node *node, struct ec_config *config)
const struct ec_config * ec_node_get_config (struct ec_node *node)
size_t ec_node_get_children_count (const struct ec_node *node)
int ec_node_get_child (const struct ec_node *node, size_t i, struct ec_node **child, unsigned int *refs)
const struct ec_node_type * ec_node_type (const struct ec_node *node)
struct ec_dict * ec_node_attrs (const struct ec_node *node)
const char * ec_node_id (const struct ec_node *node)
char * ec_node_desc (const struct ec_node *node)
void ec_node_dump (FILE *out, const struct ec_node *node)
struct ec_node * ec_node_find (struct ec_node *node, const char *id)
int ec_node_check_type (const struct ec_node *node, const struct ec_node_type *type)
const char * ec_node_get_type_name (const struct ec_node *node)
void * ec_node_priv (const struct ec_node *node)
struct ec_node * ec_node_any (const char *id, const char *attr)
struct ec_node * ec_node_bypass (const char *id, struct ec_node *node)
int ec_node_bypass_set_child (struct ec_node *gen_node, struct ec_node *child)
struct ec_node * ec_node_cond (const char *id, const char *cond_str, struct ec_node *child)
struct ec_node * ec_node_dynamic (const char *id, ec_node_dynamic_build_t build, void *opaque)
struct ec_node * ec_node_empty (const char *id)
struct ec_node * ec_node_expr (const char *id)
int ec_node_expr_set_val_node (struct ec_node *gen_node, struct ec_node *val_node)
int ec_node_expr_add_bin_op (struct ec_node *gen_node, struct ec_node *op)
int ec_node_expr_add_pre_op (struct ec_node *gen_node, struct ec_node *op)
int ec_node_expr_add_post_op (struct ec_node *gen_node, struct ec_node *op)
int ec_node_expr_add_parenthesis (struct ec_node *gen_node, struct ec_node *open, struct ec_node *close)
int ec_node_expr_eval (void **result, const struct ec_node *node, struct ec_pnode *parse, const struct ec_node_expr_eval_ops *ops, void *userctx)
struct ec_node * ec_node_file (const char *id, const char *file)
int ec_node_file_set_str (struct ec_node *node, const char *file)
struct ec_node * ec_node_int (const char *id, int64_t min, int64_t max, unsigned int base)
int ec_node_int_getval (const struct ec_node *node, const char *str, int64_t *result)
struct ec_node * ec_node_uint (const char *id, uint64_t min, uint64_t max, unsigned int base)
int ec_node_uint_getval (const struct ec_node *node, const char *str, uint64_t *result)
struct ec_node * ec_node_many (const char *id, struct ec_node *child, unsigned int min, unsigned int max)
int ec_node_many_set_params (struct ec_node *gen_node, struct ec_node *child, unsigned int min, unsigned int max)
struct ec_node * ec_node_once (const char *id, struct ec_node *child)
int ec_node_once_set_child (struct ec_node *node, struct ec_node *child)
struct ec_node * ec_node_option (const char *id, struct ec_node *node)
int ec_node_option_set_child (struct ec_node *gen_node, struct ec_node *child)
struct ec_node * ec_node_or (const char *id)
int ec_node_or_add (struct ec_node *node, struct ec_node *child)
struct ec_node * ec_node_re (const char *id, const char *str)
int ec_node_re_set_regexp (struct ec_node *node, const char *re)
struct ec_node * ec_node_re_lex (const char *id, struct ec_node *child)
int ec_node_re_lex_add (struct ec_node *gen_node, const char *pattern, int keep, const char *attr_name)
struct ec_node * ec_node_seq (const char *id)
int ec_node_seq_add (struct ec_node *node, struct ec_node *child)
struct ec_node * ec_node_sh_lex (const char *id, struct ec_node *child)
struct ec_node * ec_node_str (const char *id, const char *str)
int ec_node_str_set_str (struct ec_node *node, const char *str)
struct ec_node * ec_node_subset (const char *id)
int ec_node_subset_add (struct ec_node *node, struct ec_node *child)

Value:

    static void ec_init_init_##t(void);             \
    static void __attribute__((constructor, used))          \
    ec_init_init_##t(void)                      \
    {                               \
         ec_init_register(&t);                  \
    }

Register initialization and exit callbacks. These callbacks are ordered by priority: for initialization, the lowest priority is called first. For exit, the callbacks are invoked in reverse order.

Definition at line 23 of file ecoli_init.h.

Node has no identifier.

Definition at line 60 of file ecoli_node.h.

Value:

    static void ec_node_init_##t(void);             \
    static void __attribute__((constructor, used))          \
    ec_node_init_##t(void)                      \
    {                               \
        if (ec_node_type_register(&t, 0) < 0)           \
            fprintf(stderr,                 \
                "cannot register node type %s\n",   \
                t.name);             \
    }

Register a node type at library load.

The node type is registered in a function that has the the constructor attribute: the function is called at library load.

Parameters

t The name of the ec_node_type structure variable.

Definition at line 81 of file ecoli_node.h.

Value:

    static void ec_node_init_##t(void);             \
    static void __attribute__((constructor, used))          \
    ec_node_init_##t(void)                      \
    {                               \
        if (ec_node_type_register(&t, 1) < 0)           \
            fprintf(stderr,                 \
                "cannot register node type %s\n",   \
                t.name);             \
    }

Register a node type at library load, overriding previous registration.

The node type is registered in a function that has the the constructor attribute: the function is called at library load.

Be careful when using this macro, as the last type with a given name is the one that is actually registered. The call order may be hard to predict, especially within the same binary.

Parameters

t The name of the ec_node_type structure variable.

Definition at line 105 of file ecoli_node.h.

Value:

__ec_node_cmd(args, EC_VA_END)

Definition at line 15 of file ecoli_node_cmd.h.

Value:

__ec_node_or(args, EC_VA_END)

Create a new 'or' node from an arbitrary list of child nodes. All nodes given in the list will be freed when freeing this one.

Definition at line 20 of file ecoli_node_or.h.

Value:

__ec_node_seq(args, EC_VA_END)

Definition at line 15 of file ecoli_node_seq.h.

Value:

__ec_node_subset(args, EC_VA_END)

Definition at line 15 of file ecoli_node_subset.h.

Type of init function. Return 0 on success, -1 on error.

Definition at line 34 of file ecoli_init.h.

Type of exit function.

Definition at line 39 of file ecoli_init.h.

Function type used to configure a node.

The function pointer is not called directly, the helper ec_node_set_config() should be used instead.

The configuration passed to this function pointer is valid, i.e. ec_config_validate() returned 0 on it.

Parameters

node The node to configure.
config The configuration to apply to the node.

Returns

Definition at line 137 of file ecoli_node.h.

Parse a string vector using the given grammar graph.

The function pointer is not called directly, the helpers ec_parse(), ec_parse_strvec() or ec_parse_child() should be used instead.

The implementation of this method for a node that manages children will call ec_parse_child(child, pstate, child_strvec).

Parameters

node The grammar graph.
pstate A pointer to the leaf being parsed in the parsing tree. It can be used by a node to retrieve information from the current parsing tree. To get the root of the tree, ec_pnode_get_root(pstate) should be used.
strvec The string vector to be parsed.

Returns

On success, return the number of consumed items in the string vector (can be 0) or EC_PARSE_NOMATCH if the node cannot parse the string vector. On error, a negative value is returned and errno is set.

Definition at line 163 of file ecoli_node.h.

Get completion items using the given grammar graph.

The function pointer should not be called directly, the helpers ec_complete(), ec_complete_strvec() or ec_complete_child() should be used instead.

This function completes the last element of the string vector. For instance, node.type->complete(node, comp, ['ls']) will list all commands that starts with 'ls', while node.type->complete(node, comp, ['ls', '']) will list all possible values for the next argument.

The implementation of this function in the node is supposed to either:

• call ec_comp_add_item() for each completion item that should be added to the list. This is typically done in terminal nodes, for example in ec_node_str() or ec_node_file().
• call ec_complete_child() to let the children nodes add their own completion. This is the case of ec_node_or which trivially calls ec_complete_child() on all its children, and of ec_node_seq, which has to do a more complex job (parsing strvec).

A node that does not provide any method for the completion will fallback to ec_complete_unknown(): this helper returns a completion item of type EC_COMP_UNKNOWN, just to indicate that everything before the last element of the string vector has been parsed successfully, but we don't know how to complete the last element.

Parameters

node The root node of the grammar graph.
comp The current list of completion items, to be filled by the node.type->complete() method.
strvec The string vector to be completed.

Returns

Definition at line 208 of file ecoli_node.h.

Get the short description of a grammar node.

This function pointer should not be called directly. The ec_node_desc() helper should be used instead.

This callback is typically used when building a help string for a grammar graph. It is used in ecoli editline interface to generate contextual help like this (first column):

<int> An integer. foo The foo string. bar The bar string.

If this callback is set to NULL in the node type, the default behavior is to return the node type name inside <>, for instance <int>. The string node type implements this method to return the string value. An integer node could implement it to return its range (ex: '1..10').

The returned value is a pointer that must be freed by the caller with ec_free().

On error, NULL is returned and errno is set.

Definition at line 237 of file ecoli_node.h.

Initialize the node private area.

This function pointer should not be called directly. The ec_node() and ec_node_from_type() helpers, that allocate new nodes, should be used instead.

If not NULL, this function is called when a node is instanciated, to initialize the private area of a node. In any case, the private area is first zeroed.

On success, 0 is returned. On error, a negative value is returned and errno is set.

Definition at line 253 of file ecoli_node.h.

Free the node private area.

This function pointer should not be called directly. The ec_node_free() helper should be used instead.

When a node is deleted, this function is called to free the resources referenced in the node private area.

Definition at line 264 of file ecoli_node.h.

Count the number of node children.

This function pointer should not be called directly. The ec_node_get_children_count() helper should be used instead.

Some grammar nodes like seq, or, many, (...), reference children nodes in the grammar graph. This function returns the number of children.

Definition at line 276 of file ecoli_node.h.

Count the number of node children.

This function pointer should not be called directly. The ec_node_get_child() helper should be used instead.

Some grammar nodes like seq, or, many, (...), reference children nodes in the grammar graph. This function sets the i-th child (with i lower than the return value of ec_node_get_children_count()) in the child pointer. It also returns the number of references to the child owned by the parent. This information is used by the algorithm that frees a grammar graph taking care of loops.

On success, 0 is returned. On error, a negative value is returned and errno is set.

Definition at line 294 of file ecoli_node.h.

callback invoked by parse() or complete() to build the dynamic node the behavior of the node can depend on what is already parsed

Definition at line 1 of file ecoli_node_dynamic.h.

Callback function type for evaluating a variable

Parameters

result On success, this pointer must be set by the user to point to a user structure describing the evaluated result.
userctx A user-defined context passed to all callback functions, which can be used to maintain a state or store global information.
var The parse result referencing the variable.

Returns

Definition at line 30 of file ecoli_node_expr.h.

Callback function type for evaluating a prefix-operator

Parameters

result On success, this pointer must be set by the user to point to a user structure describing the evaluated result.
userctx A user-defined context passed to all callback functions, which can be used to maintain a state or store global information.
operand The evaluated expression on which the operation should be applied.
operator The parse result referencing the operator.

Returns

Definition at line 51 of file ecoli_node_expr.h.

Definition at line 56 of file ecoli_node_expr.h.

Definition at line 61 of file ecoli_node_expr.h.

Definition at line 67 of file ecoli_node_expr.h.

Definition at line 73 of file ecoli_node_expr.h.

Register an initialization function.

Parameters

test A pointer to a ec_init structure to be registered.

Initialize ecoli library.

Must be called before any other function from libecoli, except ec_malloc_register().

Returns

Uninitialize ecoli library.

Register a node type.

The name of the type being registered is a uniq identifier. However, it is possible to force the registration of a type with an existing name by setting 'override' to true. Note that the initial type is not removed from the list, instead the new one is added before in the list.

Parameters

type The node type to be registered.
override Allow the registration of an existing type.

Returns

Lookup node type by name.

Parameters

name The name of the node type to search.

Returns

The (read-only) node type if found, or NULL on error.

Dump registered log types.

Parameters

out The stream where the dump is sent.

Get the config schema of a node type.

Parameters

type The node type.

Returns

The (read-only) config schema of the node type, or NULL if the node type has no config schema.

Get the name of a node type.

Parameters

type The node type.

Returns

The (read-only) name of the node type.

create a new node when the type is known, typically called from the node code

Create a new node from type name.

Get the pointer to the node private area.

Parameters

node The grammar node.

Returns

The pointer to the node private area.

Create a 'any' node.

This node always matches 1 string in the vector. An optional strvec attribute can be checked too. These attributes are usually set by a lexer node.

Parameters

id The node identifier.
attr The strvec attribute to match, or NULL.

Returns

The ecoli node.

A node that does nothing else than calling the child node. It can be helpful to build loops in a node graph.

Attach a child to a bypass node.

Create a condition node.

The condition node checks that an expression is true before parsing/completing the child node. If it is false, the node doesn't match anything.

Parameters

id The node identifier.
cond_str The condition string. This is an function-based expression.
child The ecoli child node.

Returns

The new ecoli cond node.

Dynamic node where parsing/validation is done in a user provided callback.

This node always matches an empty string vector

This node behaves like its child, but prevent from parsing it several times.

Example:

many(
  or(
    once(str("foo")),
    str("bar")))

Matches: [], ['foo', 'bar'], ['bar', 'bar'], ['foo', 'bar', 'bar'], ... But not: ['foo', 'foo'], ['foo', 'bar', 'foo'], ...

on error, child is not freed

on error, child is freed

Create an empty 'or' node.

Add a child to an 'or' node. Child is consumed.