Loading...
Searching...
No Matches
Complete

Complete string input using a grammar graph. More...

## Macros

#define | EC_COMP_FOREACH(item, comp, type)
| Iterate items matching a given type.

## Enumerations

enum | ec_comp_type { EC_COMP_UNKNOWN = 0x1 , EC_COMP_FULL = 0x2 , EC_COMP_PARTIAL = 0x4 , EC_COMP_ALL = 0x7 }
| Completion item type. More...

## Functions

struct ec_comp * | ec_complete (const struct ec_node *node, const char *str)
| Get the list of completions from a string input.
struct ec_comp * | ec_complete_strvec (const struct ec_node *node, const struct ec_strvec *strvec)
| Get the list of completions from a string vector input.
struct ec_strvec * | ec_complete_strvec_expand (const struct ec_node *node, enum ec_comp_type type, const struct ec_strvec *strvec)
| Return a new string vector based on the provided one using completion to expand non-ambiguous tokens to their full value.
int | ec_complete_child (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)
| Get the list of completions of a child node.
struct ec_comp * | ec_comp (void)
| Create an empty completion object (list of completion items).
void | ec_comp_free (struct ec_comp *comp)
| Free a completion object and all its items.
void | ec_comp_dump (FILE *out, const struct ec_comp *comp)
| Dump the content of a completions list.
int | ec_comp_merge (struct ec_comp *to, struct ec_comp *from)
| Merge items contained in `from` into `to`.
struct ec_pnode * | ec_comp_get_cur_pstate (const struct ec_comp *comp)
| Get current parsing state of completion.
struct ec_comp_group * | ec_comp_get_cur_group (const struct ec_comp *comp)
| Get current completion group.
struct ec_dict * | ec_comp_get_attrs (const struct ec_comp *comp)
| Get completion attributes.
struct ec_comp_item * | ec_comp_add_item (struct ec_comp *comp, const struct ec_node *node, enum ec_comp_type type, const char *current, const char *full)
| Add an item in completion list.
const char * | ec_comp_item_get_str (const struct ec_comp_item *item)
| Get the string value of a completion item.
const char * | ec_comp_item_get_display (const struct ec_comp_item *item)
| Get the display string value of a completion item.
const char * | ec_comp_item_get_completion (const struct ec_comp_item *item)
| Get the completion string value of a completion item.
const char * | ec_comp_item_get_current (const struct ec_comp_item *item)
| Get the current string value (before completion) of a completion item.
const struct ec_comp_group * | ec_comp_item_get_grp (const struct ec_comp_item *item)
| Get the group of a completion item.
enum ec_comp_type | ec_comp_item_get_type (const struct ec_comp_item *item)
| Get the type of a completion item.
const struct ec_node * | ec_comp_item_get_node (const struct ec_comp_item *item)
| Get the node associated with a completion item.
int | ec_comp_item_set_str (struct ec_comp_item *item, const char *str)
| Set the completion item string.
int | ec_comp_item_set_display (struct ec_comp_item *item, const char *display)
| Set the display value of an item.
int | ec_comp_item_set_completion (struct ec_comp_item *item, const char *completion)
| Set the completion value of an item.
const struct ec_node * | ec_comp_group_get_node (const struct ec_comp_group *grp)
| Get the completion group node.
const struct ec_pnode * | ec_comp_group_get_pstate (const struct ec_comp_group *grp)
| Get the completion group parsing state.
const struct ec_dict * | ec_comp_group_get_attrs (const struct ec_comp_group *grp)
| Get the completion group attributes.
int | ec_complete_unknown (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)
| Default node completion callback.
size_t | ec_comp_count (const struct ec_comp *comp, enum ec_comp_type type)
| Get the number of completion items.
struct ec_comp_item * | ec_comp_iter_first (const struct ec_comp *comp, enum ec_comp_type type)
| Get the first completion item matching the type.
struct ec_comp_item * | ec_comp_iter_next (struct ec_comp_item *item, enum ec_comp_type type)
| Get the next completion item matching the type.

## Detailed Description

Complete string input using a grammar graph.

This file provides helpers to list and manipulate the possible completions for a given input.

Use ec_complete_strvec() to complete a vector of strings when the input is already split into several tokens. You can use ec_complete() if you know that the size of the vector is

1. This is common if your grammar graph includes a lexer that will tokenize the input.

These two functions return a pointer to an ec_comp structure, that lists the possible completions. The completions are grouped into ::ec_comp_group. All completion items of a group share the same parsing state and are issued by the same node.

## Macro Definition Documentation

## EC_COMP_FOREACH

#define EC_COMP_FOREACH | ( |  | item,
|  |  | comp,
|  |  | type )

Value:
for (item = ec_comp_iter_first(comp, type); item != NULL; \
item = ec_comp_iter_next(item, type))
ec_comp_iter_next
struct ec_comp_item * ec_comp_iter_next(struct ec_comp_item *item, enum ec_comp_type type)
Get the next completion item matching the type.
ec_comp_iter_first
struct ec_comp_item * ec_comp_iter_first(const struct ec_comp *comp, enum ec_comp_type type)
Get the first completion item matching the type.

Iterate items matching a given type.

Parameters

  item | The item that will be set at each iteration.
  comp | The completion list.
  type | A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and EC_COMP_FULL, to select the type to iterate.

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

Definition at line 522 of file complete.h.

## Enumeration Type Documentation

## ec_comp_type

enum ec_comp_type

Completion item type.

Enumerator
EC_COMP_UNKNOWN | Valid token but completion not possible.
EC_COMP_FULL | The item is fully completed.
EC_COMP_PARTIAL | The item is partially completed.
EC_COMP_ALL | All completion types.

Examples
  readline/main.c.

Definition at line 47 of file complete.h.

## Function Documentation

## ec_complete()

struct ec_comp * ec_complete | ( | const struct ec_node * | node,
|  | const char * | str )

Get the list of completions from a string input.

It is equivalent to calling ec_complete_strvec() with a vector that only contains 1 element, the input string. Using this function is often more convenient if you get your input from a buffer, because you won't have to create a vector. Usually, it means you have a lexer in your grammar graph that will tokenize the input.

See ec_complete_strvec() for more details.

Parameters

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

Returns
  A pointer to the completion list on success, or NULL on error (errno is set).

Examples
  readline/main.c.

## ec_complete_strvec()

struct ec_comp * ec_complete_strvec | ( | const struct ec_node * | node,
|  | const struct ec_strvec * | strvec )

Get the list of completions from a string vector input.

This function tries to complete the last element of the given string vector. For instance, to complete with file names in an equivalent of the cat shell command, the passed vector should be ["cat", ""] (and not ["cat"]). To complete with files starting with "x", the passed vector should be ["cat", "x"].

To get the completion list, the engine parses the beginning of the input using the grammar graph. The resulting parsing tree is saved and attached to each completion group.

The result is a ec_comp structure pointer, which contains several groups of completion items.

Parameters

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

Returns
  A pointer to the completion list on success, or NULL on error (errno is set).

Examples
  parse-yaml/parse-yaml.c.

## ec_complete_strvec_expand()

struct ec_strvec * ec_complete_strvec_expand | ( | const struct ec_node * | node,
|  | enum ec_comp_type | type,
|  | const struct ec_strvec * | strvec )

Return a new string vector based on the provided one using completion to expand non-ambiguous tokens to their full value.

Parameters

  node | The grammar graph.
  type | Completion item type to consider.
  strvec | The input string vector.

Returns
  A new string vector with non-ambiguous tokens expanded, or NULL on error (errno is set).

## ec_complete_child()

int ec_complete_child | ( | const struct ec_node * | node,
|  | struct ec_comp * | comp,
|  | const struct ec_strvec * | strvec )

Get the list of completions of a child node.

This function is to be used by intermediate ecoli nodes, i.e., nodes which have children (e.g., ec_node_seq(), ec_node_or(), ...). It fills an existing ec_comp structure, passed by the parent node.

Parameters

  node | The grammar graph.
  comp | The current completion list to be filled.
  strvec | The input string vector.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp()

struct ec_comp * ec_comp | ( | void |  | ) |

Create an empty completion object (list of completion items).

Returns
  A pointer to the completion structure on success, or NULL on error (errno is set).

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

## ec_comp_free()

void ec_comp_free | ( | struct ec_comp * | comp | ) |

Free a completion object and all its items.

Parameters

  comp | The pointer to the completion structure to free.

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

## ec_comp_dump()

void ec_comp_dump | ( | FILE * | out,
|  | const struct ec_comp * | comp )

Dump the content of a completions list.

Parameters

  out | The stream where the dump is sent.
  comp | The pointer to the completion list structure.

## ec_comp_merge()

int ec_comp_merge | ( | struct ec_comp * | to,
|  | struct ec_comp * | from )

Merge items contained in `from` into `to`.

The `from` comp struct is freed.

Parameters

  to | The destination completion list.
  from | The source completion list.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp_get_cur_pstate()

struct ec_pnode * ec_comp_get_cur_pstate | ( | const struct ec_comp * | comp | ) |

Get current parsing state of completion.

This function can be called by a node during the completion process.

When processing the list of completions for a given input, an incomplete parsing tree is generated before the completion callback is invoked. A node may use it if the completions list depend on what was previously parsed. For instance, the ec_node_once() node checks in the parsing tree if the node is already parsed. In this case, no completion is issued.

Parameters

  comp | The current completion list.

Returns
  The current parsing state (cannot be NULL).

## ec_comp_get_cur_group()

struct ec_comp_group * ec_comp_get_cur_group | ( | const struct ec_comp * | comp | ) |

Get current completion group.

This function can be called by a node during the completion process.

A completion group is a list of completion items that share the same parsing state and are issued by the same grammar node. The completion group is created when the first item is added, thus this function returns NULL if no item has been added in the group.

Parameters

  comp | The current completion list.

Returns
  The current completion group (can be NULL).

## ec_comp_get_attrs()

struct ec_dict * ec_comp_get_attrs | ( | const struct ec_comp * | comp | ) |

Get completion attributes.

Arbitrary attributes (stored in a dictionary) can be attached to a completion state.

Parameters

  comp | The completion list.

Returns
  The associated attributes.

## ec_comp_add_item()

struct ec_comp_item * ec_comp_add_item | ( | struct ec_comp * | comp,
|  | const struct ec_node * | node,
|  | enum ec_comp_type | type,
|  | const char * | current,
|  | const char * | full )

Add an item in completion list.

This function can be called by a node during the completion process, for each completion item that should be added to the list. This is typically done in terminal nodes, like ec_node_str() or ec_node_file().

Create a new completion item, and add it into the completion list. A completion item has a type, which can be:

- EC_COMP_FULL - the item is fully completed (common case, used for instance in the str node)
- EC_COMP_PARTIAL - the item is only partially completed (this happens rarely, for instance in the file node, when a completion goes up to the next slash).
- EC_COMP_UNKNOWN - the node detects a valid token, but does not know how to complete it (e.g., the int node).

Parameters

  comp | The current completion list.
  node | The node issuing the completion item.
  type | The type of the item.
  current | The incomplete string being completed.
  full | The string fully completed.

Returns
  The item that was added in the list on success, or NULL on error. Note: do not free the returned value, as it is referenced by the completion list. It is returned in case it needs to be modified, for instance with ec_comp_item_set_display().

## ec_comp_item_get_str()

const char * ec_comp_item_get_str | ( | const struct ec_comp_item * | item | ) |

Get the string value of a completion item.

Parameters

  item | The completion item.

Returns
  The completion string of this item.

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

## ec_comp_item_get_display()

const char * ec_comp_item_get_display | ( | const struct ec_comp_item * | item | ) |

Get the display string value of a completion item.

The display string corresponds to what is displayed when listing the possible completions.

Parameters

  item | The completion item.

Returns
  The display string of this item.

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

## ec_comp_item_get_completion()

const char * ec_comp_item_get_completion | ( | const struct ec_comp_item * | item | ) |

Get the completion string value of a completion item.

The completion string corresponds to what should be added to the incomplete token to complete it.

Parameters

  item | The completion item.

Returns
  The completion string of this item.

## ec_comp_item_get_current()

const char * ec_comp_item_get_current | ( | const struct ec_comp_item * | item | ) |

Get the current string value (before completion) of a completion item.

Parameters

  item | The completion item.

Returns
  The current string of this item.

## ec_comp_item_get_grp()

const struct ec_comp_group * ec_comp_item_get_grp | ( | const struct ec_comp_item * | item | ) |

Get the group of a completion item.

The completion group corresponds to the list of items that share the same parsing state and are issued by the same node.

Parameters

  item | The completion item.

Returns
  The completion group of this item.

Examples
  readline/main.c.

## ec_comp_item_get_type()

enum ec_comp_type ec_comp_item_get_type | ( | const struct ec_comp_item * | item | ) |

Get the type of a completion item.

Parameters

  item | The completion item.

Returns
  The type of this item (EC_COMP_UNKNOWN, EC_COMP_PARTIAL or EC_COMP_FULL).

Examples
  readline/main.c.

## ec_comp_item_get_node()

const struct ec_node * ec_comp_item_get_node | ( | const struct ec_comp_item * | item | ) |

Get the node associated with a completion item.

Parameters

  item | The completion item.

Returns
  The node that issued the completion item.

## ec_comp_item_set_str()

int ec_comp_item_set_str | ( | struct ec_comp_item * | item,
|  | const char * | str )

Set the completion item string.

Some intermediate nodes like sh_lex modify the completion string of items generated by their children, for instance to add quotes.

Parameters

  item | The completion item to update.
  str | The new item string.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp_item_set_display()

int ec_comp_item_set_display | ( | struct ec_comp_item * | item,
|  | const char * | display )

Set the display value of an item.

The display string corresponds to what is displayed when listing the possible completions. Some nodes like ec_node_file() change the default value to display the base name instead of the full path.

Parameters

  item | The completion item to update.
  display | The new display string.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp_item_set_completion()

int ec_comp_item_set_completion | ( | struct ec_comp_item * | item,
|  | const char * | completion )

Set the completion value of an item.

The completion string corresponds to what should be added to the incomplete token to complete it. Some nodes like sh_lex modify it in the items generated by their children, for instance to add a terminating quote.

Parameters

  item | The completion item to update.
  completion | The new completion string.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp_group_get_node()

const struct ec_node * ec_comp_group_get_node | ( | const struct ec_comp_group * | grp | ) |

Get the completion group node.

Parameters

  grp | The completion group.

## ec_comp_group_get_pstate()

const struct ec_pnode * ec_comp_group_get_pstate | ( | const struct ec_comp_group * | grp | ) |

Get the completion group parsing state.

The parsing state contains the parsing result of the input data preceding the completion. All items of a completion group share the same parsing state.

Parameters

  grp | The completion group.

Returns
  The parsing state of the completion group.

Examples
  readline/main.c.

## ec_comp_group_get_attrs()

const struct ec_dict * ec_comp_group_get_attrs | ( | const struct ec_comp_group * | grp | ) |

Get the completion group attributes.

Arbitrary attributes (stored in a dictionary) can be attached to a completion group.

Parameters

  grp | The completion group.

Returns
  The attributes of the completion group.

## ec_complete_unknown()

int ec_complete_unknown | ( | const struct ec_node * | node,
|  | struct ec_comp * | comp,
|  | const struct ec_strvec * | strvec )

Default node completion callback.

This function is the default completion method for nodes that do not define one.

This helper adds a completion item of type EC_COMP_UNKNOWN if the input string vector contains one element, to indicate that everything before the last element of the string vector has been parsed successfully, but the node doesn't know how to complete the last element.

Parameters

  node | The completion node.
  comp | The completion list to update.
  strvec | The input string vector.

Returns
  0 on success, or -1 on error (errno is set).

## ec_comp_count()

size_t ec_comp_count | ( | const struct ec_comp * | comp,
|  | enum ec_comp_type | type )

Get the number of completion items.

Return the number of completion items that match a given type in a completion list.

Parameters

  comp | The completion list.
  type | A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and EC_COMP_FULL, to select the type to match.

Returns
  The number of matching items.

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

## ec_comp_iter_first()

struct ec_comp_item * ec_comp_iter_first | ( | const struct ec_comp * | comp,
|  | enum ec_comp_type | type )

Get the first completion item matching the type.

Also see EC_COMP_FOREACH().

Parameters

  comp | The completion list.
  type | A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and EC_COMP_FULL, to select the type to iterate.

Returns
  A completion item.

Examples
  readline/main.c.

## ec_comp_iter_next()

struct ec_comp_item * ec_comp_iter_next | ( | struct ec_comp_item * | item,
|  | enum ec_comp_type | type )

Get the next completion item matching the type.

Also see EC_COMP_FOREACH().

Parameters

  item | The current completion item.
  type | A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and EC_COMP_FULL, to select the type to iterate.

Returns
  The next completion item, or NULL if there is no more.

Examples
  readline/main.c.