Loading...
Searching...
No Matches
Parse nodes

Create parse tree from string input and grammar graph. More...

## Macros

#define | EC_PARSE_NOMATCH INT_MAX
| Return value of ec_parse_child() when input does not match grammar.
#define | EC_PNODE_GET_ROOT(parse)
| Get the root of the parsing tree.
#define | EC_PNODE_FOREACH_CHILD(child, pnode)
| Iterate the children of a node.
#define | EC_PNODE_ITER_NEXT(root, parse, iter_children)
| Get the next node in a parse tree iteration.
#define | EC_PNODE_FOREACH(iter, root)
| Iterate depth-first over a parsing tree.

## Functions

struct ec_pnode * | ec_pnode (const struct ec_node *node)
| Create an empty parsing tree.
void | ec_pnode_free (struct ec_pnode *pnode)
| Free a parsing tree.
void | ec_pnode_free_children (struct ec_pnode *pnode)
| Remove and free all the children of a parsing tree node.
struct ec_pnode * | ec_pnode_dup (const struct ec_pnode *pnode)
| Duplicate a parsing tree.
const struct ec_strvec * | ec_pnode_get_strvec (const struct ec_pnode *pnode)
| Get the string vector associated with a parsing node.
struct ec_pnode * | ec_parse (const struct ec_node *node, const char *str)
| Parse a string using a grammar tree.
struct ec_pnode * | ec_parse_strvec (const struct ec_node *node, const struct ec_strvec *strvec)
| Parse a string vector using a grammar tree.
int | ec_parse_child (const struct ec_node *node, struct ec_pnode *pstate, const struct ec_strvec *strvec)
| Parse a string vector using a grammar tree, from a parent node.
void | ec_pnode_link_child (struct ec_pnode *pnode, struct ec_pnode *child)
| Link a parsing node to a parsing tree.
void | ec_pnode_unlink_child (struct ec_pnode *child)
| Remove a child node from parsing tree.
struct ec_pnode * | ec_pnode_get_root (struct ec_pnode *pnode)
| Get the root of the parsing tree.
struct ec_pnode * | ec_pnode_get_parent (const struct ec_pnode *pnode)
| Get the parent node in the parsing tree.
struct ec_pnode * | ec_pnode_get_first_child (const struct ec_pnode *pnode)
| Get the first child of a node in the parsing tree.
struct ec_pnode * | ec_pnode_get_last_child (const struct ec_pnode *pnode)
| Get the last child of a node in the parsing tree.
struct ec_pnode * | ec_pnode_next (const struct ec_pnode *pnode)
| Get the next sibling node.
const struct ec_node * | ec_pnode_get_node (const struct ec_pnode *pnode)
| Get the grammar node corresponding to the parsing node.
void | ec_pnode_del_last_child (struct ec_pnode *pnode)
| Unlink and free the last child.
struct ec_dict * | ec_pnode_get_attrs (const struct ec_pnode *pnode)
| Get attributes associated with a node in a parsing tree.
void | ec_pnode_dump (FILE *out, const struct ec_pnode *pnode)
| Dump a parsing tree.
const struct ec_pnode * | ec_pnode_find (const struct ec_pnode *root, const char *id)
| Find a node from its identifier.
const struct ec_pnode * | ec_pnode_find_next (const struct ec_pnode *root, const struct ec_pnode *prev, const char *id, bool iter_children)
| Find the next node matching an identifier.
unsigned int | ec_pnode_count (const struct ec_pnode *root, const char *id)
| Count node occurrences in a parse subtree.
size_t | ec_pnode_len (const struct ec_pnode *pnode)
| Get the number of strings in the parsed string vector.
bool | ec_pnode_matches (const struct ec_pnode *pnode)
| Check if the parsing tree matches the input.

## Detailed Description

Create parse tree from string input and grammar graph.

Node parse API.

The parse operation is to check if an input (a string or vector of strings) matches the node tree. On success, the result is stored in a tree that describes which part of the input matches which node.

The parsing tree is sometimes referenced by another node than the root node. Use ec_pnode_get_root() to get the root node in that case.

## Macro Definition Documentation

## EC_PARSE_NOMATCH

#define EC_PARSE_NOMATCH INT_MAX

Return value of ec_parse_child() when input does not match grammar.

Definition at line 145 of file parse.h.

## EC_PNODE_GET_ROOT

#define EC_PNODE_GET_ROOT | ( |  | parse | ) |

Value:
({ \
const struct ec_pnode *p_ = parse; /* check type */ \
struct ec_pnode *pnode_ = (struct ec_pnode *)parse; \
__typeof__(parse) res_; \
(void)p_; \
res_ = ec_pnode_get_root(pnode_); \
res_; \
})
ec_pnode_get_root
struct ec_pnode * ec_pnode_get_root(struct ec_pnode *pnode)
Get the root of the parsing tree.
ec_pnode
struct ec_pnode * ec_pnode(const struct ec_node *node)
Create an empty parsing tree.

Get the root of the parsing tree.

Get the root of the parsing tree, keeping the const statement if the argument has it.

Parameters

  parse | A node in the parsing tree.

Returns
  The root of the parsing tree.

Definition at line 212 of file parse.h.

## EC_PNODE_FOREACH_CHILD

#define EC_PNODE_FOREACH_CHILD | ( |  | child,
|  |  | pnode )

Value:
for (child = ec_pnode_get_first_child(pnode); child != NULL; child = ec_pnode_next(child))
ec_pnode_next
struct ec_pnode * ec_pnode_next(const struct ec_pnode *pnode)
Get the next sibling node.
ec_pnode_get_first_child
struct ec_pnode * ec_pnode_get_first_child(const struct ec_pnode *pnode)
Get the first child of a node in the parsing tree.

Iterate the children of a node.

Parameters

  child | The item that will be set at each iteration.
  pnode | The parent node in the parsing tree.

Examples
  parse-yaml/parse-yaml.c.

Definition at line 286 of file parse.h.

## EC_PNODE_ITER_NEXT

#define EC_PNODE_ITER_NEXT | ( |  | root,
|  |  | parse,
|  |  | iter_children )

Value:
({ \
const struct ec_pnode *p_ = parse; /* check type */ \
struct ec_pnode *pnode_ = (struct ec_pnode *)parse; \
__typeof__(parse) res_; \
(void)p_; \
res_ = __ec_pnode_iter_next(root, pnode_, iter_children); \
res_; \
})

Get the next node in a parse tree iteration.

Parameters

  root | The root of the parse tree being iterated.
  parse | The current parse node.
  iter_children | If true, iterate over children; if false, skip to siblings.

Returns
  The next parse node, or NULL if iteration is complete.

Definition at line 415 of file parse.h.

## EC_PNODE_FOREACH

#define EC_PNODE_FOREACH | ( |  | iter,
|  |  | root )

Value:
for ((iter) = (root); (iter) != NULL; (iter) = EC_PNODE_ITER_NEXT((root), (iter), true))
EC_PNODE_ITER_NEXT
#define EC_PNODE_ITER_NEXT(root, parse, iter_children)
Get the next node in a parse tree iteration.
Definition parse.h:415

Iterate depth-first over a parsing tree.

Parameters

  iter | The item that will be set at each iteration.
  root | The root of the parsing tree to iterate.

Definition at line 433 of file parse.h.

## Function Documentation

## ec_pnode()

struct ec_pnode * ec_pnode | ( | const struct ec_node * | node | ) |

Create an empty parsing tree.

This function is used internally when parsing an input using a grammar tree.

Parameters

  node | The grammar node.

Returns
  The empty parse tree.

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

## ec_pnode_free()

void ec_pnode_free | ( | struct ec_pnode * | pnode | ) |

Free a parsing tree.

Parameters

  pnode | The root of the parsing tree to be freed. It must not have any parent.

Examples
  parse-yaml/parse-yaml.c, and readline/main.c.

## ec_pnode_free_children()

void ec_pnode_free_children | ( | struct ec_pnode * | pnode | ) |

Remove and free all the children of a parsing tree node.

Parameters

  pnode | Node whose children will be freed.

## ec_pnode_dup()

struct ec_pnode * ec_pnode_dup | ( | const struct ec_pnode * | pnode | ) |

Duplicate a parsing tree.

Parameters

  pnode | A node inside a parsing tree.

Returns
  A pointer to the copy of the input node, at the same place in the copy of the parsing tree. Return NULL on error (errno is set).

## ec_pnode_get_strvec()

const struct ec_strvec * ec_pnode_get_strvec | ( | const struct ec_pnode * | pnode | ) |

Get the string vector associated with a parsing node.

When an input is parsed successfully (i.e., the input string vector matches the grammar tree), the matching string vector is copied inside the associated parsing node.

For instance, parsing the input ["foo", "bar"] on a grammar which is a sequence of strings, the attached string vector will be ["foo", "bar"] on the root pnode, ["foo"] on the first leaf, and ["bar"] on the second leaf.

If the parsing tree does not match (see ec_pnode_matches()), the associated string vector is NULL.

Parameters

  pnode | The parsing node. If NULL, the function returns NULL.

Returns
  The string vector associated with the parsing node, or NULL if the node is not yet parsed (this happens when building the parsing tree), or if the parsing tree does not match the input.

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

## ec_parse()

struct ec_pnode * ec_parse | ( | const struct ec_node * | node,
|  | const char * | str )

Parse a string using a grammar tree.

This is equivalent to calling ec_parse_strvec() on the same node, with a string vector containing only the argument string str.

Parameters

  node | The grammar node.
  str | The input string.

Returns
  A parsing tree, or NULL on error (errno is set).

Examples
  readline/main.c.

## ec_parse_strvec()

struct ec_pnode * ec_parse_strvec | ( | const struct ec_node * | node,
|  | const struct ec_strvec * | strvec )

Parse a string vector using a grammar tree.

Generate a parsing tree by parsing the input string vector using the given grammar tree.

The parsing tree is composed of ec_pnode, and each of them is associated with a ec_node (the grammar node), to the string vector that matched the subtree, and to optional attributes.

When the input matches the grammar tree, the string vector associated to the root node of the returned parsing tree is the same than the strvec argument. Calling ec_pnode_matches() on this tree returns true.

If the input does not match the grammar tree, the returned parsing tree only contains one root node, with no associated string vector. Calling ec_pnode_matches() on this tree returns false.

Parameters

  node | The grammar node.
  strvec | The input string vector.

Returns
  A parsing tree, or NULL on error (errno is set).

## ec_parse_child()

int ec_parse_child | ( | const struct ec_node * | node,
|  | struct ec_pnode * | pstate,
|  | const struct ec_strvec * | strvec )

Parse a string vector using a grammar tree, from a parent node.

This function is usually called from an intermediate node (like ec_node_seq(), ec_node_or(), ...) to backfill the parsing tree, which is built piece by piece while browsing the grammar tree.

ec_parse_child() creates a new child in this parsing tree, and calls the parse() method for the child node, with pstate pointing to this new child. If it does not match, the child is removed in the state, else it is kept, with its possible descendants.

Parameters

  node | The grammar node.
  pstate | The node of the parsing tree.
  strvec | The input string vector.

Returns
  On success: the number of matched elements in the input string vector (which can be 0), or EC_PARSE_NOMATCH (which is a positive value) if the input does not match the grammar. On error, -1 is returned, and errno is set.

## ec_pnode_link_child()

void ec_pnode_link_child | ( | struct ec_pnode * | pnode,
|  | struct ec_pnode * | child )

Link a parsing node to a parsing tree.

Add a child to a node in a parsing tree, at the end of the children list.

Parameters

  pnode | The node of the parsing tree where the child is added.
  child | The node (or subtree) to add in the children list.

## ec_pnode_unlink_child()

void ec_pnode_unlink_child | ( | struct ec_pnode * | child | ) |

Remove a child node from parsing tree.

Remove a child node (and its children) from the children list its parent node in the parsing tree. The child node is not freed.

Parameters

  child | The node (or subtree) to remove.

## ec_pnode_get_root()

struct ec_pnode * ec_pnode_get_root | ( | struct ec_pnode * | pnode | ) |

Get the root of the parsing tree.

You may also use EC_PNODE_GET_ROOT() instead, that keeps the const statement.

Parameters

  pnode | A node in the parsing tree.

Returns
  The root of the parsing tree.

Examples
  pool-editline/main.c.

## ec_pnode_get_parent()

struct ec_pnode * ec_pnode_get_parent | ( | const struct ec_pnode * | pnode | ) |

Get the parent node in the parsing tree.

Parameters

  pnode | A node in the parsing tree.

Returns
  The parent node, or NULL if it is the root.

Examples
  readline/main.c.

## ec_pnode_get_first_child()

struct ec_pnode * ec_pnode_get_first_child | ( | const struct ec_pnode * | pnode | ) |

Get the first child of a node in the parsing tree.

Parameters

  pnode | A node in the parsing tree.

Returns
  The first child node, or NULL if it has no child.

Examples
  parse-yaml/parse-yaml.c.

## ec_pnode_get_last_child()

struct ec_pnode * ec_pnode_get_last_child | ( | const struct ec_pnode * | pnode | ) |

Get the last child of a node in the parsing tree.

Parameters

  pnode | A node in the parsing tree.

Returns
  The last child node, or NULL if it has no child.

## ec_pnode_next()

struct ec_pnode * ec_pnode_next | ( | const struct ec_pnode * | pnode | ) |

Get the next sibling node.

If pnode is the root of the parsing tree, return NULL. Otherwise, return the next sibling node.

Parameters

  pnode | A node in the parsing tree.

Returns
  The next sibling, or NULL if there is no sibling.

Examples
  parse-yaml/parse-yaml.c.

## ec_pnode_get_node()

const struct ec_node * ec_pnode_get_node | ( | const struct ec_pnode * | pnode | ) |

Get the grammar node corresponding to the parsing node.

Parameters

  pnode | A node in the parsing tree.

Returns
  The corresponding grammar node, that issued the parse.

Examples
  parse-yaml/parse-yaml.c, and readline/main.c.

## ec_pnode_del_last_child()

void ec_pnode_del_last_child | ( | struct ec_pnode * | pnode | ) |

Unlink and free the last child.

Shortcut to unlink and free the last child of a node. It is a quite common operation in intermediate nodes (like ec_node_seq(), ec_node_many(), ...) to remove a subtree that was temporarily added during the completion process.

Parameters

  pnode | A node in the parsing tree which has at least one child.

## ec_pnode_get_attrs()

struct ec_dict * ec_pnode_get_attrs | ( | const struct ec_pnode * | pnode | ) |

Get attributes associated with a node in a parsing tree.

Attributes are key/values that are stored in a dictionary and attached to a node in the parsing tree. An attribute can be added to a node by the parsing or completion method of an ec_node.

Parameters

  pnode | A node in the parsing tree.

Returns
  The dictionary containing the attributes.

## ec_pnode_dump()

void ec_pnode_dump | ( | FILE * | out,
|  | const struct ec_pnode * | pnode )

Dump a parsing tree.

Parameters

  out | The stream where the dump is done.
  pnode | The parsing tree to dump.

Examples
  readline/main.c.

## ec_pnode_find()

const struct ec_pnode * ec_pnode_find | ( | const struct ec_pnode * | root,
|  | const char * | id )

Find a node from its identifier.

Find the first node in the parsing tree which has the given node identifier. The search is a depth-first search.

Parameters

  root | The node of the parsing tree where the search starts.
  id | The node identifier string to match.

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

Examples
  extension-editline/main.c, pool-editline/main.c, and simple-editline/main.c.

## ec_pnode_find_next()

const struct ec_pnode * ec_pnode_find_next | ( | const struct ec_pnode * | root,
|  | const struct ec_pnode * | prev,
|  | const char * | id,
|  | bool | iter_children )

Find the next node matching an identifier.

After a successful call to ec_pnode_find() or ec_pnode_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_pnode_find().
  prev | The node returned by the previous search.
  id | The node identifier string to match.
  iter_children | True to iterate the children of "prev", false to skip them.

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

## ec_pnode_count()

unsigned int ec_pnode_count | ( | const struct ec_pnode * | root,
|  | const char * | id )

Count node occurrences in a parse subtree.

Parameters

  root | The node of the parsing tree where the search starts.
  id | The node identifier string to match.

Returns
  The number of nodes matching the identifier.

## ec_pnode_len()

size_t ec_pnode_len | ( | const struct ec_pnode * | pnode | ) |

Get the number of strings in the parsed string vector.

Parameters

  pnode | A node in the parsing tree.

Returns
  The number of strings in the parsed string vector, or 0 if the node is NULL or has no string vector.

## ec_pnode_matches()

bool ec_pnode_matches | ( | const struct ec_pnode * | pnode | ) |

Check if the parsing tree matches the input.

Parameters

  pnode | A node in the parsing tree.

Returns
  true if the parsing tree matches (has a string vector), false otherwise.

Examples
  parse-yaml/parse-yaml.c, and readline/main.c.