ecoli_complete - Man Page
Name
ecoli_complete — Complete
— Complete string input using a grammar graph.
Synopsis
Macros
#define EC_COMP_FOREACH(item, comp, type)
Enumerations
enum ec_comp_type { EC_COMP_UNKNOWN = 0x1, EC_COMP_FULL = 0x2, EC_COMP_PARTIAL = 0x4, EC_COMP_ALL = 0x7 }
Functions
struct ec_comp * ec_complete (const struct ec_node *node, const char *str)
struct ec_comp * ec_complete_strvec (const struct ec_node *node, const struct ec_strvec *strvec)
struct ec_strvec * ec_complete_strvec_expand (const struct ec_node *node, enum ec_comp_type type, const struct ec_strvec *strvec)
int ec_complete_child (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)
struct ec_comp * ec_comp (void)
void ec_comp_free (struct ec_comp *comp)
void ec_comp_dump (FILE *out, const struct ec_comp *comp)
int ec_comp_merge (struct ec_comp *to, struct ec_comp *from)
struct ec_pnode * ec_comp_get_cur_pstate (const struct ec_comp *comp)
struct ec_comp_group * ec_comp_get_cur_group (const struct ec_comp *comp)
struct ec_dict * ec_comp_get_attrs (const struct ec_comp *comp)
struct ec_comp_item * ec_comp_add_item (struct ec_comp *comp, const struct ec_node *node, enum ec_comp_type type, const char *start, const char *full)
const char * ec_comp_item_get_str (const struct ec_comp_item *item)
const char * ec_comp_item_get_display (const struct ec_comp_item *item)
const char * ec_comp_item_get_completion (const struct ec_comp_item *item)
const struct ec_comp_group * ec_comp_item_get_grp (const struct ec_comp_item *item)
enum ec_comp_type ec_comp_item_get_type (const struct ec_comp_item *item)
const struct ec_node * ec_comp_item_get_node (const struct ec_comp_item *item)
int ec_comp_item_set_str (struct ec_comp_item *item, const char *str)
int ec_comp_item_set_display (struct ec_comp_item *item, const char *display)
int ec_comp_item_set_completion (struct ec_comp_item *item, const char *completion)
const struct ec_node * ec_comp_group_get_node (const struct ec_comp_group *grp)
const struct ec_pnode * ec_comp_group_get_pstate (const struct ec_comp_group *grp)
const struct ec_dict * ec_comp_group_get_attrs (const struct ec_comp_group *grp)
int ec_complete_unknown (const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec)
size_t ec_comp_count (const struct ec_comp *comp, enum ec_comp_type type)
struct ec_comp_item * ec_comp_iter_first (const struct ec_comp *comp, enum ec_comp_type type)
struct ec_comp_item * ec_comp_iter_next (struct ec_comp_item *item, enum ec_comp_type 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 completions items of a group shares the same parsing state and are issued by the same node.
Macro Definition Documentation
#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))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.
Definition at line 506 of file complete.h.
Enumeration Type Documentation
enum ec_comp_type
Completion item type.
Enumerator
- EC_COMP_FULL
The item is fully completed.
- EC_COMP_PARTIAL
The item is partially completed.
Definition at line 41 of file complete.h.
Function Documentation
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 that 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).
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).
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).
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 (ex: 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).
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).
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.
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.
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).
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).
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).
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.
struct ec_comp_item * ec_comp_add_item (struct ec_comp * comp, const struct ec_node * node, enum ec_comp_type type, const char * start, 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 how to complete it (ex: the int node).
- Parameters
comp The current completion list.
node The node issuing the completion item.
type The type of the item.
start 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().
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.
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.
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.
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.
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).
const struct ec_node * ec_comp_item_get_node (const struct ec_comp_item * item)
Get the node associated to a completion item.
- Parameters
item The completion item.
- Returns
The node that issued the completion item.
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).
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 display the base name instead of the full path.
- Parameters
item The completion item to update.
str The new display string.
Returns
0 on success, or -1 on error (errno is set).
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.
str The new completion string.
Returns
0 on success, or -1 on error (errno is set).
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.
const struct ec_pnode * ec_comp_group_get_pstate (const struct ec_comp_group * grp)
Get the completion group parsing state.
All items of a completion group are issued by the same node. This function returns a pointer to this node.
- Parameters
grp The completion group.
- Returns
The node that issued the completion group.
const struct ec_dict * ec_comp_group_get_attrs (const struct ec_comp_group * grp)
Get the completion group attributes.
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.
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).
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.
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.
struct ec_comp_item * ec_comp_iter_next (struct ec_comp_item * item, 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.
Author
Generated automatically by Doxygen for Libecoli from the source code.
Referenced By
The man pages ec_comp(3), ec_comp_add_item(3), ec_comp_count(3), ec_comp_dump(3), EC_COMP_FOREACH(3), ec_comp_free(3), EC_COMP_FULL(3), ec_comp_get_attrs(3), ec_comp_get_cur_group(3), ec_comp_get_cur_pstate(3), ec_comp_group_get_attrs(3), ec_comp_group_get_node(3), ec_comp_group_get_pstate(3), ec_comp_item_get_completion(3), ec_comp_item_get_display(3), ec_comp_item_get_grp(3), ec_comp_item_get_node(3), ec_comp_item_get_str(3), ec_comp_item_get_type(3), ec_comp_item_set_completion(3), ec_comp_item_set_display(3), ec_comp_item_set_str(3), ec_comp_iter_first(3), ec_comp_iter_next(3), ec_complete(3), ec_complete_child(3), ec_complete_strvec(3), ec_complete_strvec_expand(3), ec_complete_unknown(3), ec_comp_merge(3), EC_COMP_PARTIAL(3) and ec_comp_type(3) are aliases of ecoli_complete(3).