Complete

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

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

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

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.