1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
6 * @defgroup complete Complete
9 * @brief Complete string input using a grammar graph.
11 * This file provides helpers to list and manipulate the possible
12 * completions for a given input.
14 * Use @ec_complete_strvec() to complete a vector of strings when
15 * the input is already split into several tokens. You can use
16 * @ec_complete() if you know that the size of the vector is
17 * 1. This is common if your grammar graph includes a lexer that
18 * will tokenize the input.
20 * These 2 functions return a pointer to an @ec_comp structure, that
21 * lists the possible completions. The completions are grouped into
22 * @ec_group. All completions items of a group shares the same parsing
23 * state and are issued by the same node.
28 #ifndef ECOLI_COMPLETE_
29 #define ECOLI_COMPLETE_
31 #include <sys/queue.h>
32 #include <sys/types.h>
41 * Completion item type.
44 EC_COMP_UNKNOWN = 0x1,
45 EC_COMP_FULL = 0x2, /**< The item is fully completed. */
46 EC_COMP_PARTIAL = 0x4, /**< The item is partially completed. */
51 * Get the list of completions from a string input.
53 * It is equivalent that calling @ec_complete_strvec() with a
54 * vector that only contains 1 element, the input string. Using this
55 * function is often more convenient if you get your input from a
56 * buffer, because you won't have to create a vector. Usually, it means
57 * you have a lexer in your grammar graph that will tokenize the input.
59 * See @ec_complete_strvec() for more details.
66 * A pointer to the completion list on success, or NULL
67 * on error (errno is set).
69 struct ec_comp *ec_complete(const struct ec_node *node,
73 * Get the list of completions from a string vector input.
75 * This function tries to complete the last element of the given string
76 * vector. For instance, to complete with file names in an equivalent of
77 * the "cat" shell command, the passed vector should be ["cat", ""] (and
78 * not ["cat"]). To complete with files starting with "x", the passed
79 * vector should be ["cat", "x"].
81 * To get the completion list, the engine parses the beginning of the
82 * input using the grammar graph. The resulting parsing tree is saved and
83 * attached to each completion group.
85 * The result is a @ec_comp structure pointer, which contains several
86 * groups of completion items.
91 * The input string vector.
93 * A pointer to the completion list on success, or NULL
94 * on error (errno is set).
96 struct ec_comp *ec_complete_strvec(const struct ec_node *node,
97 const struct ec_strvec *strvec);
100 * Get the list of completions of a child node.
102 * This function is to be used by intermediate ecoli nodes, i.e. nodes
103 * which have children (ex: ec_node_seq, ec_node_or, ...). It fills an
104 * existing @ec_comp structure, passed by the parent node.
109 * The current completion list to be filled.
111 * The input string vector.
113 * 0 on success, or -1 on error (errno is set).
115 int ec_complete_child(const struct ec_node *node,
116 struct ec_comp *comp,
117 const struct ec_strvec *strvec);
120 * Create an empty completion object (list of completion items).
123 * A pointer to the completion structure on success, or NULL on error
126 struct ec_comp *ec_comp(void);
129 * Free a completion object and all its items.
132 * The pointer to the completion structure to free.
134 void ec_comp_free(struct ec_comp *comp);
137 * Dump the content of a completions list.
140 * The stream where the dump is sent.
142 * The pointer to the completion list structure.
144 void ec_comp_dump(FILE *out, const struct ec_comp *comp);
147 * Merge items contained in 'from' into 'to'.
149 * The 'from' comp struct is freed.
152 * The destination completion list.
154 * The source completion list.
156 * 0 on success, or -1 on error (errno is set).
158 int ec_comp_merge(struct ec_comp *to, struct ec_comp *from);
161 * Get current parsing state of completion.
163 * This function can be called by a node during the completion process.
165 * When processing the list of completions for a given input,
166 * an incomplete parsing tree is generated before the completion
167 * callback is invoked. A node may use it if the completions list
168 * depend on what was previously parsed. For instance, the "once"
169 * node checks in the parsing tree if the node is already parsed.
170 * In this case, no completion is issued.
173 * The current completion list.
175 * The current parsing state (cannot be NULL).
177 struct ec_pnode *ec_comp_get_cur_pstate(const struct ec_comp *comp);
180 * Get current completion group.
182 * This function can be called by a node during the completion process.
184 * A completion group is a list of completion items that share the same
185 * parsing state and are issued by the same grammar node. The completion
186 * group is created when the first item is added, thus this function
187 * returns NULL if no item has been added in the group.
190 * The current completion list.
192 * The current completion group (can be NULL).
194 struct ec_comp_group *ec_comp_get_cur_group(const struct ec_comp *comp);
197 * Get completion attributes.
199 * Arbitrary attributes (stored in a dictionary) can be attached to a
203 * The completion list.
205 * The associated attributes.
207 struct ec_dict *ec_comp_get_attrs(const struct ec_comp *comp);
210 * Add an item in competion list.
212 * This function can be called by a node during the completion process,
213 * for each completion item that should be added to the list. This is
214 * typically done in terminal nodes, like ec_node_str or ec_node_file.
216 * Create a new completion item, and add it into the completion
217 * list. A completion item has a type, which can be:
218 * - EC_COMP_FULL: the item is fully completed (common case, used
219 * for instance in the str node)
220 * - EC_COMP_PARTIAL: the item is only partially completed (this
221 * happens rarely, for instance in the file node, when a completion
222 * goes up to the next slash).
223 * - EC_COMP_UNKNOWN: the node detects a valid token, but does not
224 * how to complete it (ex: the int node).
227 * The current completion list.
229 * The node issuing the completion item.
231 * The type of the item.
233 * The incomplete string being completed.
235 * The string fully completed.
237 * The item that was added in the list on success, or NULL
238 * on error. Note: don't free the returned value, as it is referenced
239 * by the completion list. It is returned in case it needs to be
240 * modified, for instance with ec_comp_item_set_display().
242 struct ec_comp_item *ec_comp_add_item(struct ec_comp *comp,
243 const struct ec_node *node, enum ec_comp_type type,
244 const char *start, const char *full);
247 * Get the string value of a completion item.
250 * The completion item..
252 * The completion string of this item.
255 ec_comp_item_get_str(const struct ec_comp_item *item);
258 * Get the display string value of a completion item.
260 * The display string corresponds to what is displayed when
261 * listing the possible completions.
264 * The completion item..
266 * The display string of this item.
269 ec_comp_item_get_display(const struct ec_comp_item *item);
272 * Get the completion string value of a completion item.
274 * The completion string corresponds to what should be added to
275 * the incomplete token to complete it.
278 * The completion item.
280 * The completion string of this item.
283 ec_comp_item_get_completion(const struct ec_comp_item *item);
286 * Get the group of a completion item.
288 * The completion group corresponds to the list of items that share
289 * the same parsing state and are issued by the same node.
292 * The completion item.
294 * The completion group of this item.
296 const struct ec_comp_group *
297 ec_comp_item_get_grp(const struct ec_comp_item *item);
300 * Get the type of a completion item.
303 * The completion item.
305 * The type of this item (EC_COMP_UNKNOWN, EC_COMP_PARTIAL or
309 ec_comp_item_get_type(const struct ec_comp_item *item);
312 * Get the node associated to a completion item.
315 * The completion item.
317 * The node that issued the completion item.
319 const struct ec_node *
320 ec_comp_item_get_node(const struct ec_comp_item *item);
323 * Set the completion item string.
325 * Some intermediate nodes like sh_lex modify the completion string of
326 * items generated by their children, for instance to add quotes.
329 * The completion item to update.
331 * The new item string.
333 * 0 on success, or -1 on error (errno is set).
335 int ec_comp_item_set_str(struct ec_comp_item *item, const char *str);
338 * Set the display value of an item.
340 * The display string corresponds to what is displayed when listing the
341 * possible completions. Some nodes like ec_node_file change the default
342 * value display the base name instead of the full path.
345 * The completion item to update.
347 * The new display string.
349 * 0 on success, or -1 on error (errno is set).
351 int ec_comp_item_set_display(struct ec_comp_item *item,
352 const char *display);
355 * Set the completion value of an item.
357 * The completion string corresponds to what should be added to
358 * the incomplete token to complete it. Some nodes like sh_lex
359 * modify it in the items generated by their children, for instance
360 * to add a terminating quote.
363 * The completion item to update.
365 * The new completion string.
367 * 0 on success, or -1 on error (errno is set).
369 int ec_comp_item_set_completion(struct ec_comp_item *item,
370 const char *completion);
373 * Get the completion group node.
376 * The completion group.
378 const struct ec_node *
379 ec_comp_group_get_node(const struct ec_comp_group *grp);
382 * Get the completion group parsing state.
384 * All items of a completion group are issued by the same node.
385 * This function returns a pointer to this node.
388 * The completion group.
390 * The node that issued the completion group.
392 const struct ec_pnode *
393 ec_comp_group_get_pstate(const struct ec_comp_group *grp);
396 * Get the completion group attributes.
398 * The parsing state contains the parsing result of the input data
399 * preceding the completion. All items of a completion group share the
400 * same parsing state.
403 * The completion group.
405 * The parsing state of the completion group.
407 const struct ec_dict *
408 ec_comp_group_get_attrs(const struct ec_comp_group *grp);
412 * Default node completion callback
414 * This function is the default completion method for nodes that do
417 * This helper adds a completion item of type EC_COMP_UNKNOWN if the
418 * input string vector contains one element, to indicate that everything
419 * before the last element of the string vector has been parsed
420 * successfully, but the node doesn't know how to complete the last
424 * The completion node.
426 * The completion list to update.
428 * The input string vector.
430 * 0 on succes, or -1 on error (errno is set).
433 ec_complete_unknown(const struct ec_node *node,
434 struct ec_comp *comp,
435 const struct ec_strvec *strvec);
438 * Get the number of completion items.
440 * Return the number of completion items that match a given type in a
444 * The completion list.
446 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
447 * EC_COMP_FULL, to select the type to match.
449 * The number of matching items.
451 size_t ec_comp_count(const struct ec_comp *comp, enum ec_comp_type type);
454 * Get the first completion item matching the type.
456 * Also see EC_COMP_FOREACH().
459 * The completion list.
461 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
462 * EC_COMP_FULL, to select the type to iterate.
466 struct ec_comp_item *
467 ec_comp_iter_first(const struct ec_comp *comp, enum ec_comp_type type);
470 * Get the first completion item matching the type.
472 * Also see EC_COMP_FOREACH().
475 * The completion list.
477 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
478 * EC_COMP_FULL, to select the type to iterate.
482 struct ec_comp_item *
483 ec_comp_iter_next(struct ec_comp_item *item, enum ec_comp_type type);
486 * Iterate items matching a given type.
489 * The item that will be set at each iteration.
491 * The completion list.
493 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
494 * EC_COMP_FULL, to select the type to iterate.
496 #define EC_COMP_FOREACH(item, comp, type) \
497 for (item = ec_comp_iter_first(comp, type); \
499 item = ec_comp_iter_next(item, type))