ecoli_nodes - Man Page

struct ec_init
struct ec_node_type
struct ec_node_expr_eval_ops
struct ec_node_file_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 struct ec_strvec *(* ec_node_dynlist_get_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)

enum ec_node_dynlist_flags { DYNLIST_MATCH_LIST = 1 << 0, DYNLIST_MATCH_REGEXP = 1 << 1, DYNLIST_EXCLUDE_LIST = 1 << 2 }

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 (const 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)
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)
struct ec_node * ec_node_find_next (struct ec_node *root, const struct ec_node *prev, 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)
void ec_node_schema_dump (FILE *out, 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_dynlist (const char *id, ec_node_dynlist_get_t get, void *opaque, const char *re_str, enum ec_node_dynlist_flags flags)
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)
void ec_node_file_set_ops (const struct ec_node_file_ops *ops)
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_sh_lex_expand (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)

struct ec_node_type_list node_type_list

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.

Priority policy: 0 .. 99 : reserved for libecoli internal use. 100 .. : available for user code (recommended).

Do not use priorities < 100 for application code; internal libecoli components may depend on those priorities and using them can lead to uninitialized state, crashes, or undefined behaviour.

Definition at line 27 of file init.h.

Node has no identifier.

Definition at line 59 of file 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 80 of file 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 101 of file node.h.

Value:

__ec_node_cmd(args, EC_VA_END)

Definition at line 14 of file 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 19 of file node_or.h.

Value:

__ec_node_seq(args, EC_VA_END)

Definition at line 14 of file node_seq.h.

Value:

__ec_node_subset(args, EC_VA_END)

Definition at line 14 of file node_subset.h.

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

Definition at line 37 of file init.h.

Type of exit function.

Definition at line 42 of file 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.

This function provided by a node type is supposed to do additional checks to the configuration and store private, if needed. If it returns 0, ec_node_set_config() stores the generic configuration in the node. The function can just return 0 if nothing needs to be stored in private data.

Parameters

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

Returns

Definition at line 130 of file 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 155 of file 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 202 of file 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 free().

On error, NULL is returned and errno is set.

Definition at line 233 of file 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 instantiated, 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 249 of file 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 260 of file 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 272 of file 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 290 of file 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 node_dynamic.h.

Callback invoked by parse() or complete() to build the strvec containing the list of object names.

Parameters

pstate The current parsing state.
opaque The user pointer passed at node creation.

Returns

A string vector containing the list of object names.

Definition at line 1 of file node_dynlist.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 29 of file 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 48 of file node_expr.h.

Definition at line 55 of file node_expr.h.

Definition at line 62 of file node_expr.h.

Definition at line 70 of file node_expr.h.

Definition at line 78 of file node_expr.h.

Flags passed at ec_node_dynlist creation.

Enumerator

DYNLIST_MATCH_LIST

Match names returned by the user callback.

DYNLIST_MATCH_REGEXP

Match names from regexp pattern.

DYNLIST_EXCLUDE_LIST

Don't match names returned by the user callback, even if it matches the regexp.

Definition at line 39 of file node_dynlist.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.

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 from a known type is known

This function is typically called from the node constructor.

Parameters

type The type of the node to create.
id The node identifier.

Returns

The new node on success, or NULL on error.

Create a new node from its type name.

This function is typically called from user code, for node types that do not provide a specific constructor.

Parameters

typename The type name of the node to create.
id The node identifier.

Returns

The new node on success, or NULL on error.

Clone a grammar node.

This function takes a reference to the node. If ec_node_free() is later called on this node, it will decrease only the reference. The free is effective when the reference count reaches 0. The reference counter is initialized to 1 at node creation.

Parameters

node The node to clone.

Returns

The pointer to the cloned node, always equal to the parameter. It returns NULL if the parameter was NULL: in this case, nothing is done.

Decrement node reference counter and free the node if it is the last reference.

Parameters

node The grammar node to free.

Set node configuration.

For a node that supports generic configuration, set its configuration.

After a call to this function, the config is owned by the node and must not be used by the caller anymore.

Parameters

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

Returns

Get the current node configuration.

For a node that supports generic configuration, get its configuration.

Parameters

node The grammar node.

Returns

The generic node configuration on success, or NULL on error.

Return the number of children for a node.

Parameters

node The grammar node.

Returns

The number of children.

Get the n-th child of a node.

Parameters

node The grammar node.
i The index of the child node, that must be lower than the number of children.
child The pointer where the child node pointer will be stored on success.

Returns

The number of children.

Get the type of a node.

Parameters

node The grammar node.

Returns

The type structure of this node.

Get the attributes dict of the node.

A user can add any attribute to a node. The attributes keys starting with an underscore are reserved.

Parameters

node The grammar node.

Returns

The attribute dictionary of this node.

Get node identifier.

Parameters

node The grammar node.

Returns

The node identifier string.

Get node short description.

Parameters

node The grammar node.

Returns

An allocated string containing the node short description that must be freed by the caller. Return NULL on error.

Dump a grammar tree.

Parameters

out The stream where the dump is sent.
node The grammar tree to dump.

Find a node from its identifier string.

Browse the tree using pre-order depth traversal, and return the first node that matches the given identifier.

Parameters

node The grammar tree.
node The identifier to match.

Returns

A node matching the identifier.

Find the next node matching an identifier.

After a successful call to ec_node_find() or ec_node_find_next(), it is possible to get the next node that has the specified id. There are 2 options:

• continue the depth-first search where it was interrupted.
• skip the children of the current node, and continue the depth-first search.

Parameters

root The root of the search, as passed to ec_node_find().
prev The node returned by the previous search.
id The node identifier string to match.

Returns

The next node matching the identifier, or NULL if not found.

Check the type of a node.

Parameters

node The grammar node.
type The pointer to the type structure.

Returns

Get the type name of a grammar node.

Parameters

node The grammar node.

Returns

The type name of the node.

Get the pointer to the node private area.

Parameters

node The grammar node.

Returns

The pointer to the node private area.

Dump the node configuration schema.

Parameters

out The stream where the dump is sent.
node The grammar node.

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.

Create a dynlist node.

The parsing and completion depends on a list returned by a user provided callback, a regular expression, and flags.

Parameters

get The function that returns the list of object names as a string vector.
opaque A user pointer passed to the get function.
re_str The regular expression defining the valid pattern for object names.
flags Customize parsing and completion behavior.

Returns

The dynlist grammar node, or NULL on error.

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.

The list of registered node types. Must not be modified by user, except at initialization using the EC_NODE_TYPE_REGISTER() or EC_NODE_TYPE_REGISTER_OVERRIDE() macros.