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 tree
11 * This file provide 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 you grammar tree has a lexer that will tokenize
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,
46 EC_COMP_PARTIAL = 0x4,
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 tree 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 tree. 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.
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 when called from a node completion.
102 * This function is to be used by ecoli nodes.
105 int ec_complete_child(const struct ec_node *node,
106 struct ec_comp *comp,
107 const struct ec_strvec *strvec);
110 * Create a completion object (list of completion items).
114 struct ec_comp *ec_comp(struct ec_pnode *state);
117 * Free a completion object and all its items.
121 void ec_comp_free(struct ec_comp *comp);
128 void ec_comp_dump(FILE *out,
129 const struct ec_comp *comp);
132 * Merge items contained in 'from' into 'to'
134 * The 'from' comp struct is freed.
136 int ec_comp_merge(struct ec_comp *to,
137 struct ec_comp *from);
140 * Get current completion state.
143 struct ec_pnode *ec_comp_get_state(const struct ec_comp *comp);
146 * Get current completion group.
149 struct ec_comp_group *ec_comp_get_group(const struct ec_comp *comp);
152 * Get completion group attributes.
155 struct ec_dict *ec_comp_get_attrs(const struct ec_comp *comp);
157 /* shortcut for ec_comp_item() + ec_comp_item_add() */
158 int ec_comp_add_item(struct ec_comp *comp,
159 const struct ec_node *node,
160 struct ec_comp_item **p_item,
161 enum ec_comp_type type,
162 const char *start, const char *full);
167 int ec_comp_item_set_str(struct ec_comp_item *item,
171 * Get the string value of a completion item.
176 ec_comp_item_get_str(const struct ec_comp_item *item);
179 * Get the display string value of a completion item.
184 ec_comp_item_get_display(const struct ec_comp_item *item);
187 * Get the completion string value of a completion item.
192 ec_comp_item_get_completion(const struct ec_comp_item *item);
195 * Get the group of a completion item.
199 const struct ec_comp_group *
200 ec_comp_item_get_grp(const struct ec_comp_item *item);
203 * Get the type of a completion item.
208 ec_comp_item_get_type(const struct ec_comp_item *item);
211 * Get the node associated to a completion item.
215 const struct ec_node *
216 ec_comp_item_get_node(const struct ec_comp_item *item);
219 * Set the display value of an item.
223 int ec_comp_item_set_display(struct ec_comp_item *item,
224 const char *display);
227 * Set the completion value of an item.
231 int ec_comp_item_set_completion(struct ec_comp_item *item,
232 const char *completion);
235 * Get the completion group node.
239 const struct ec_node *
240 ec_comp_group_get_node(const struct ec_comp_group *grp);
243 * Get the completion group parsed state.
247 const struct ec_pnode *
248 ec_comp_group_get_state(const struct ec_comp_group *grp);
251 * Get the completion group attributes.
255 const struct ec_dict *
256 ec_comp_group_get_attrs(const struct ec_comp_group *grp);
265 ec_complete_unknown(const struct ec_node *gen_node,
266 struct ec_comp *comp,
267 const struct ec_strvec *strvec);
274 unsigned int ec_comp_count(
275 const struct ec_comp *comp,
276 enum ec_comp_type flags);
285 * Get the first completion item matching the type.
287 * Also see EC_COMP_FOREACH().
290 * The completion list.
292 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
293 * EC_COMP_FULL, to select the type to iterate.
297 struct ec_comp_item *
298 ec_comp_iter_first(const struct ec_comp *comp, enum ec_comp_type type);
301 * Get the first completion item matching the type.
303 * Also see EC_COMP_FOREACH().
306 * The completion list.
308 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
309 * EC_COMP_FULL, to select the type to iterate.
313 struct ec_comp_item *
314 ec_comp_iter_next(struct ec_comp_item *item, enum ec_comp_type type);
317 * Iterate items matching a given type.
320 * The item that will be set at each iteration.
322 * The completion list.
324 * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
325 * EC_COMP_FULL, to select the type to iterate.
327 #define EC_COMP_FOREACH(item, comp, type) \
328 for (item = ec_comp_iter_first(comp, type); \
330 item = ec_comp_iter_next(item, type))