ecoli_complete(3)
💖 NAME 💖
ecoli_complete - Complete
- Complete string input using a grammar graph.
(Yep bestie, this is the ecoli_complete(3) page from Libecoli, and it is literally the completion-engine main character.)
✨ 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 *current, 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 char * ec_comp_item_get_current (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 🌈
Okay so: this file is all about completing string input using a grammar graph. No cap, it gives you 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 🦋
#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 amongEC_COMP_UNKNOWN,EC_COMP_PARTIALandEC_COMP_FULL, to select the type to iterate.
Definition at line 522 of file complete.h.
🌸 Enumeration Type Documentation 🌸
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.
Definition at line 47 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 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).
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 (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).
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 * 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 thestrnode)EC_COMP_PARTIAL- the item is only partially completed (this happens rarely, for instance in thefilenode, 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., theintnode).
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, orNULLon 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 withec_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 — the actual string, no filter, no drama. 💅
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. It's the look, not necessarily the whole internal situation.
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. That's the whole point, bestie. ✨
item— the completion item.
Returns — the completion string of this 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.
item— the completion item.
Returns — the current 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. iykyk — they're all in the same group chat.
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.
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 with a completion item.
item— the completion item.
Returns — the node that issued the completion item. Main character node energy.
🔥 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. Glow-up via the parent node, honestly.
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 to display the base name instead of the full path. Short and cute for the listing, full path for the real ones.
item— the completion item to update.display— 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. Finishing touch — literally.
item— the completion item to update.completion— 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.
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.
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. One state, whole squad.
grp— the completion group.
Returns — the parsing state of the completion group.
🦋 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. Cute little extras, no cap.
grp— the completion group.
Returns — the attributes 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. It's giving "I parsed the vibe but not the ending." 😭
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.
comp— the completion list.type— a logical OR of flags amongEC_COMP_UNKNOWN,EC_COMP_PARTIALandEC_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().
comp— the completion list.type— a logical OR of flags amongEC_COMP_UNKNOWN,EC_COMP_PARTIALandEC_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 next completion item matching the type.
Also see EC_COMP_FOREACH().
item— the current completion item.type— a logical OR of flags amongEC_COMP_UNKNOWN,EC_COMP_PARTIALandEC_COMP_FULL, to select the type to iterate.
Returns — the next completion item, or NULL if there is no more.
💖 AUTHOR 💖
Generated automatically by Doxygen for Libecoli from the source code. Yes bestie, the robot wrote it, but I gave it the group-chat glow-up. 🫶
Okay that's the whole page, bestie! This lil manual-page moment comes from Libecoli, version 0.11.3, dated Thu Apr 9 2026, and it's the ecoli_complete(3) footer — bye and slay 💅✨
📦 where this page comes from
- epel 9: libecoli-devel 0.11.3-1.el9 · BSD-3-Clause AND LicenseRef-Fedora-Public-Domain
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms