include/ecoli_complete.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * @defgroup complete Complete
   7  * @{
   8  *
   9  * @brief Complete string input using a grammar tree
  10  *
  11  * This file provide helpers to list and manipulate the possible
  12  * completions for a given input.
  13  *
  14  * Use @ec_node_complete_strvec() to complete a vector of strings when
  15  * the input is already split into several tokens. You can use
  16  * @ec_node_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
  18  * the input.
  19  *
  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.
  24  *
  25  * @}
  26  */
  27
  28 #ifndef ECOLI_COMPLETE_
  29 #define ECOLI_COMPLETE_
  30
  31 #include <sys/queue.h>
  32 #include <sys/types.h>
  33 #include <stdio.h>
  34
  35 struct ec_node;
  36 struct ec_comp_item;
  37 struct ec_comp_group;
  38 struct ec_comp;
  39
  40 /**
  41  * Completion item type.
  42  */
  43 enum ec_comp_type {
  44         EC_COMP_UNKNOWN = 0x1,
  45         EC_COMP_FULL = 0x2,
  46         EC_COMP_PARTIAL = 0x4,
  47         EC_COMP_ALL = 0x7,
  48 };
  49
  50 /**
  51  * Get the list of completions from a string input.
  52  *
  53  * It is equivalent that calling @ec_node_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.
  58  *
  59  * See @ec_complete_strvec() for more details.
  60  *
  61  * @param node
  62  *   The grammar tree.
  63  * @param str
  64  *   The input string.
  65  * @return
  66  *   A pointer to the completion list on success, or NULL
  67  *   on error (errno is set).
  68  */
  69 struct ec_comp *ec_node_complete(const struct ec_node *node,
  70         const char *str);
  71
  72 /**
  73  * Get the list of completions from a string vector input.
  74  *
  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"].
  80  *
  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.
  84  *
  85  * The result is a @ec_comp structure pointer, which contains several
  86  * groups of completion items.
  87  *
  88  * @param node
  89  *   The grammar tree.
  90  * @param str
  91  *   The input string.
  92  * @return
  93  *   A pointer to the completion list on success, or NULL
  94  *   on error (errno is set).
  95  */
  96 struct ec_comp *ec_node_complete_strvec(const struct ec_node *node,
  97         const struct ec_strvec *strvec);
  98
  99 /**
 100  * Get the list of completions when called from a node completion.
 101  *
 102  * This function is to be used by ecoli nodes.
 103  *
 104  */
 105 int ec_node_complete_child(const struct ec_node *node,
 106                         struct ec_comp *comp,
 107                         const struct ec_strvec *strvec);
 108
 109 /**
 110  * Create a completion object (list of completion items).
 111  *
 112  *
 113  */
 114 struct ec_comp *ec_comp(struct ec_parse *state);
 115
 116 /**
 117  * Free a completion object and all its items.
 118  *
 119  *
 120  */
 121 void ec_comp_free(struct ec_comp *comp);
 122
 123 /**
 124  *
 125  *
 126  *
 127  */
 128 void ec_comp_dump(FILE *out,
 129         const struct ec_comp *comp);
 130
 131 /**
 132  * Merge items contained in 'from' into 'to'
 133  *
 134  * The 'from' comp struct is freed.
 135  */
 136 int ec_comp_merge(struct ec_comp *to,
 137                 struct ec_comp *from);
 138
 139 /**
 140  * Get current completion state.
 141  *
 142  */
 143 struct ec_parse *ec_comp_get_state(const struct ec_comp *comp);
 144
 145 /**
 146  * Get current completion group.
 147  *
 148  */
 149 struct ec_comp_group *ec_comp_get_group(const struct ec_comp *comp);
 150
 151 /**
 152  * Get completion group attributes.
 153  *
 154  */
 155 struct ec_dict *ec_comp_get_attrs(const struct ec_comp *comp);
 156
 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);
 163
 164 /**
 165  *
 166  */
 167 int ec_comp_item_set_str(struct ec_comp_item *item,
 168                         const char *str);
 169
 170 /**
 171  * Get the string value of a completion item.
 172  *
 173  *
 174  */
 175 const char *
 176 ec_comp_item_get_str(const struct ec_comp_item *item);
 177
 178 /**
 179  * Get the display string value of a completion item.
 180  *
 181  *
 182  */
 183 const char *
 184 ec_comp_item_get_display(const struct ec_comp_item *item);
 185
 186 /**
 187  * Get the completion string value of a completion item.
 188  *
 189  *
 190  */
 191 const char *
 192 ec_comp_item_get_completion(const struct ec_comp_item *item);
 193
 194 /**
 195  * Get the group of a completion item.
 196  *
 197  *
 198  */
 199 const struct ec_comp_group *
 200 ec_comp_item_get_grp(const struct ec_comp_item *item);
 201
 202 /**
 203  * Get the type of a completion item.
 204  *
 205  *
 206  */
 207 enum ec_comp_type
 208 ec_comp_item_get_type(const struct ec_comp_item *item);
 209
 210 /**
 211  * Get the node associated to a completion item.
 212  *
 213  *
 214  */
 215 const struct ec_node *
 216 ec_comp_item_get_node(const struct ec_comp_item *item);
 217
 218 /**
 219  * Set the display value of an item.
 220  *
 221  *
 222  */
 223 int ec_comp_item_set_display(struct ec_comp_item *item,
 224                                 const char *display);
 225
 226 /**
 227  * Set the completion value of an item.
 228  *
 229  *
 230  */
 231 int ec_comp_item_set_completion(struct ec_comp_item *item,
 232                                 const char *completion);
 233
 234 /**
 235  * Get the completion group node.
 236  *
 237  *
 238  */
 239 const struct ec_node *
 240 ec_comp_group_get_node(const struct ec_comp_group *grp);
 241
 242 /**
 243  * Get the completion group parsed state.
 244  *
 245  *
 246  */
 247 const struct ec_parse *
 248 ec_comp_group_get_state(const struct ec_comp_group *grp);
 249
 250 /**
 251  * Get the completion group attributes.
 252  *
 253  *
 254  */
 255 const struct ec_dict *
 256 ec_comp_group_get_attrs(const struct ec_comp_group *grp);
 257
 258
 259 /**
 260  *
 261  *
 262  *
 263  */
 264 int
 265 ec_node_complete_unknown(const struct ec_node *gen_node,
 266                         struct ec_comp *comp,
 267                         const struct ec_strvec *strvec);
 268
 269 /**
 270  *
 271  *
 272  *
 273  */
 274 unsigned int ec_comp_count(
 275         const struct ec_comp *comp,
 276         enum ec_comp_type flags);
 277
 278 /**
 279  *
 280  *
 281  *
 282  */
 283 struct ec_comp_iter {
 284         enum ec_comp_type type;
 285         const struct ec_comp *comp;
 286         struct ec_comp_group *cur_node;
 287         struct ec_comp_item *cur_match;
 288 };
 289
 290 /**
 291  *
 292  *
 293  *
 294  */
 295 struct ec_comp_iter *
 296 ec_comp_iter(const struct ec_comp *comp,
 297         enum ec_comp_type type);
 298
 299 /**
 300  *
 301  *
 302  *
 303  */
 304 struct ec_comp_item *ec_comp_iter_next(
 305         struct ec_comp_iter *iter);
 306
 307 /**
 308  *
 309  *
 310  *
 311  */
 312 void ec_comp_iter_free(struct ec_comp_iter *iter);
 313
 314
 315 #endif