Libecoli grammar nodes. More...

Topics
	Any node
	A node that matches any single token.
	Bypass node
	A pass-through node useful for building graph loops.
	Command node
	A node that parses commands using a format string.
	Condition node
	A node that conditionally matches based on an expression.
	Dynamic node
	A node built dynamically at parse time by a callback.
	Dynamic list node
	A node that matches names from a dynamic list.
	Empty node
	A node that matches an empty input.
	Expression node
	A node for parsing and evaluating expressions with operators.
	File node
	A node that matches and completes file paths.
	Integer node
	Nodes that match signed or unsigned integers.
	Many node
	A node that matches its child multiple times.
	None node
	A node that never matches anything.
	Once node
	A node that prevents its child from being parsed more than once.
	Option node
	A node that makes its child optional.
	Or node
	A node that matches one of its child nodes.
	Regex node
	A node that matches input against a regular expression.
	Regex lexer node
	A lexer node using regular expressions for tokenization.
	Sequence node
	A node that matches a sequence of child nodes in order.
	Shell lexer node
	A lexer node using shell-like tokenization rules.
	Space node
	A node that matches whitespace.
	String node
	A node that matches a specific string.
	Subset node
	A node that matches any subset of its children in any order.

Data Structures
struct	ec_node_type

Macros
#define	EC_NO_ID ""
#define	EC_NODE_TYPE_REGISTER(t)
#define	EC_NODE_TYPE_REGISTER_OVERRIDE(t)

Typedefs
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)

Functions
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_iter *	ec_node_iter (struct ec_node *node)
struct ec_node_iter *	ec_node_iter_next (struct ec_node_iter root, struct ec_node_iter iter, bool iter_children)
void	ec_node_iter_free (struct ec_node_iter *iter)
struct ec_node *	ec_node_iter_get_node (struct ec_node_iter *iter)
struct ec_node_iter *	ec_node_iter_get_parent (struct ec_node_iter *iter)
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)

Variables
struct ec_node_type_list	node_type_list

Detailed Description

Libecoli grammar nodes.

The grammar node is a main structure of the ecoli library, used to define how to match and complete the input tokens. A node is a generic object that implements:

a parse(node, input) method: check if an input matches
a complete(node, input) method: return possible completions for a given input
some other methods to initialize, free, ...

One basic example is the string node (ec_node_str()). A node ec_node_str("foo") will match any token list starting with "foo", for example:

["foo"]
["foo", "bar", ...] But will not match:
[]
["bar", ...]

A node ec_node_str("foo") will complete with "foo" if the input contains one token, with the same beginning as "foo":

[""]
["f"]
["fo"]
["foo"]

But it will not complete:

[]
["bar"]
["f", ""]
["", "f"]

A node can have child nodes. For instance, a sequence node ec_node_seq(ec_node_str("foo"), ec_node_str("bar")) will match a sequence: ["foo", "bar"].

Note: at some places in the documentation and the code, we may talk about the grammar tree, but as loops are allowed, we should instead talk about grammar graph.

Macro Definition Documentation

◆ EC_NO_ID

#define EC_NO_ID ""

Node has no identifier.

Examples: extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, readline/main.c, and simple-editline/main.c.

Definition at line 64 of file node.h.

◆ EC_NODE_TYPE_REGISTER

#define EC_NODE_TYPE_REGISTER ( t )

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 constructor attribute: the function is called at library load.

Parameters

t	The name of the ec_node_type structure variable.

Definition at line 88 of file node.h.

◆ EC_NODE_TYPE_REGISTER_OVERRIDE

#define EC_NODE_TYPE_REGISTER_OVERRIDE ( t )

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 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 109 of file node.h.

Typedef Documentation

◆ ec_node_set_config_t

typedef int(* ec_node_set_config_t) (struct ec_node *node, const struct ec_config *config)

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 on the configuration and store private data, 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: 0 on success, negative on error (errno is set).

Definition at line 138 of file node.h.

◆ ec_parse_t

typedef int(* ec_parse_t) (const struct ec_node *node, struct ec_pnode *pstate, const struct ec_strvec *strvec)

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 node.h.

◆ ec_complete_t

typedef int(* ec_complete_t) (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)

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 start 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 fall back 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: 0 on success, or a negative value on error (errno is set).

Definition at line 210 of file node.h.

◆ ec_node_desc_t

typedef char *(* ec_node_desc_t) (const struct ec_node *)

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 (e.g., "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 241 of file node.h.

◆ ec_node_init_priv_t

typedef int(* ec_node_init_priv_t) (struct ec_node *)

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 257 of file node.h.

◆ ec_node_free_priv_t

typedef void(* ec_node_free_priv_t) (struct ec_node *)

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 268 of file node.h.

◆ ec_node_get_children_count_t

typedef size_t(* ec_node_get_children_count_t) (const struct ec_node *)

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 280 of file node.h.

◆ ec_node_get_child_t

typedef int(* ec_node_get_child_t) (const struct ec_node *, size_t i, struct ec_node **child, unsigned int *refs)

Get the i-th child node.

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 298 of file node.h.

Function Documentation

◆ ec_node_type_register()

int ec_node_type_register	(	struct ec_node_type *	type,
		bool	override )

Register a node type.

The name of the type being registered is a unique 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: 0 on success, negative value on error.

◆ ec_node_type_lookup()

const struct ec_node_type * ec_node_type_lookup ( const char * name )

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.

◆ ec_node_type_dump()

void ec_node_type_dump ( FILE * out )

Dump registered node types.

Parameters

out	The stream where the dump is sent.

◆ ec_node_type_schema()

const struct ec_config_schema * ec_node_type_schema ( const struct ec_node_type * type )

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.

◆ ec_node_type_name()

const char * ec_node_type_name ( const struct ec_node_type * type )

Get the name of a node type.

Parameters

type	The node type.

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

Examples: parse-yaml/parse-yaml.c.

◆ ec_node_from_type()

struct ec_node * ec_node_from_type	(	const struct ec_node_type *	type,
		const char *	id )

Create a new node when the 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.

◆ ec_node()

struct ec_node * ec_node	(	const char *	typename,
		const char *	id )

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.

Examples: extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, readline/main.c, and simple-editline/main.c.

◆ ec_node_clone()

struct ec_node * ec_node_clone ( struct ec_node * node )

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.

Examples: parse-yaml/parse-yaml.c, and simple-editline/main.c.

◆ ec_node_free()

void ec_node_free ( struct ec_node * node )

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

Parameters

node	The grammar node to free.

Examples: extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, readline/main.c, and simple-editline/main.c.

◆ ec_node_set_config()

int ec_node_set_config	(	struct ec_node *	node,
		struct ec_config *	config )

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: 0 on success, or a negative value on error (in this case the config passed as parameter is freed).

◆ ec_node_get_config()

const struct ec_config * ec_node_get_config ( const struct ec_node * node )

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.

◆ ec_node_get_children_count()

size_t ec_node_get_children_count ( const struct ec_node * node )

Return the number of children for a node.

Parameters

node	The grammar node.

Returns: The number of children.

◆ ec_node_get_child()

int ec_node_get_child	(	const struct ec_node *	node,
		size_t	i,
		struct ec_node **	child )

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: 0 on success, -1 on error.

◆ ec_node_type()

const struct ec_node_type * ec_node_type ( const struct ec_node * node )

Get the type of a node.

Parameters

node	The grammar node.

Returns: The type structure of this node.

Examples: parse-yaml/parse-yaml.c.

◆ ec_node_attrs()

struct ec_dict * ec_node_attrs ( const struct ec_node * 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.

Examples: readline/main.c.

◆ ec_node_id()

const char * ec_node_id ( const struct ec_node * node )

Get node identifier.

Parameters

node	The grammar node.

Returns: The node identifier string.

Examples: parse-yaml/parse-yaml.c.

◆ ec_node_desc()

char * ec_node_desc ( const struct ec_node * node )

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.

Examples: readline/main.c.

◆ ec_node_dump()

void ec_node_dump	(	FILE *	out,
		const struct ec_node *	node )

Dump a grammar tree.

Parameters

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

◆ ec_node_find()

struct ec_node * ec_node_find	(	struct ec_node *	node,
		const char *	id )

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.
id	The identifier to match.

Returns: A node matching the identifier.

Examples: extension-editline/main.c, readline/main.c, and simple-editline/main.c.

◆ ec_node_iter()

struct ec_node_iter * ec_node_iter ( struct ec_node * node )

Create an iterator on a grammar tree.

A grammar tree is actually not really a tree, it is an oriented graph where loops can exist. For this reason, it is not possible to iterate the grammar graph without storing somewhere the list of browsed nodes in order to break loops.

Another property of grammar graphs is that the same node can appear several times at different places in the graph, having a different parent. This kind of node will be iterated only once.

The typical use is:

struct ec_node_iter *iter_root, *iter;
 
iter_root = ec_node_iter(node);
if (iter_root == NULL)
   goto fail;
 
for (iter = iter_root; iter != NULL;
     iter = ec_node_iter_next(iter_root, iter, true)) {
   do_something_with(ec_node_iter_get_node(iter));
}
 
ec_node_iter_free(iter_root);

Technically, this function builds a tree from the grammar graph. Each node of this tree references a node of the grammar graph.

Parameters

node	The grammar graph to iterate

Returns: The grammar graph iterator on success, that must be freed using ec_node_iter_free(). Return NULL on error.

◆ ec_node_iter_next()

struct ec_node_iter * ec_node_iter_next	(	struct ec_node_iter *	root,
		struct ec_node_iter *	iter,
		bool	iter_children )

Iterate to the next node.

See ec_node_iter().

Parameters

root	The iterator returned by ec_node_iter().
iter	The current node in the iterator.
iter_children	True to iterate the children of "iter", false to skip them.

Returns: The next node of the iterator, or NULL if iteration is finished.

◆ ec_node_iter_free()

void ec_node_iter_free ( struct ec_node_iter * iter )

Free a grammar graph iterator.

Parameters

iter	The iterator returned by ec_node_iter() to free.

◆ ec_node_iter_get_node()

struct ec_node * ec_node_iter_get_node ( struct ec_node_iter * iter )

Get the grammar node referenced by the iterator node.

Parameters

iter	The iterator node.

Returns: The associated grammar node.

◆ ec_node_iter_get_parent()

struct ec_node_iter * ec_node_iter_get_parent ( struct ec_node_iter * iter )

Get the parent of an iterator node.

Parameters

iter	The iterator node.

Returns: The parent of the iterator node in the iterator tree. Return NULL if it's the root.

◆ ec_node_check_type()

int ec_node_check_type	(	const struct ec_node *	node,
		const struct ec_node_type *	type )

Check the type of a node.

Parameters

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

Returns: 0 if the node is of specified type, else -1.

◆ ec_node_get_type_name()

const char * ec_node_get_type_name ( const struct ec_node * node )

Get the type name of a grammar node.

Parameters

node	The grammar node.

Returns: The type name of the node.

◆ ec_node_priv()

void * ec_node_priv ( const struct ec_node * node )

Get the pointer to the node private area.

Parameters

node	The grammar node.

Returns: The pointer to the node private area.

◆ ec_node_schema_dump()

void ec_node_schema_dump	(	FILE *	out,
		const struct ec_node *	node )

Dump the node configuration schema.

Parameters

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

Variable Documentation

◆ node_type_list

struct ec_node_type_list node_type_list

extern

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.

Topics

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ EC_NO_ID

◆ EC_NODE_TYPE_REGISTER

◆ EC_NODE_TYPE_REGISTER_OVERRIDE

Typedef Documentation

◆ ec_node_set_config_t

◆ ec_parse_t

◆ ec_complete_t

◆ ec_node_desc_t

◆ ec_node_init_priv_t

◆ ec_node_free_priv_t

◆ ec_node_get_children_count_t

◆ ec_node_get_child_t

Function Documentation

◆ ec_node_type_register()

◆ ec_node_type_lookup()

◆ ec_node_type_dump()

◆ ec_node_type_schema()

◆ ec_node_type_name()

◆ ec_node_from_type()

◆ ec_node()

◆ ec_node_clone()

◆ ec_node_free()

◆ ec_node_set_config()

◆ ec_node_get_config()

◆ ec_node_get_children_count()

◆ ec_node_get_child()

◆ ec_node_type()

◆ ec_node_attrs()

◆ ec_node_id()

◆ ec_node_desc()

◆ ec_node_dump()

◆ ec_node_find()

◆ ec_node_iter()

◆ ec_node_iter_next()

◆ ec_node_iter_free()

◆ ec_node_iter_get_node()

◆ ec_node_iter_get_parent()

◆ ec_node_check_type()

◆ ec_node_get_type_name()

◆ ec_node_priv()

◆ ec_node_schema_dump()

Variable Documentation

◆ node_type_list