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 graph.
  10  *
  11  * This file provides helpers to list and manipulate the possible
  12  * completions for a given input.
  13  *
  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.
  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,    /**< The item is fully completed. */
  46         EC_COMP_PARTIAL = 0x4, /**< The item is partially completed. */
  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_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.
  58  *
  59  * See @ec_complete_strvec() for more details.
  60  *
  61  * @param node
  62  *   The grammar graph.
  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_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 graph. 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 graph.
  90  * @param strvec
  91  *   The input string vector.
  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_complete_strvec(const struct ec_node *node,
  97         const struct ec_strvec *strvec);
  98
  99 /**
 100  * Get the list of completions of a child node.
 101  *
 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.
 105  *
 106  * @param node
 107  *   The grammar graph.
 108  * @param comp
 109  *   The current completion list to be filled.
 110  * @param strvec
 111  *   The input string vector.
 112  * @return
 113  *   0 on success, or -1 on error (errno is set).
 114  */
 115 int ec_complete_child(const struct ec_node *node,
 116                         struct ec_comp *comp,
 117                         const struct ec_strvec *strvec);
 118
 119 /**
 120  * Create an empty completion object (list of completion items).
 121  *
 122  * @return
 123  *   A pointer to the completion structure on success, or NULL on error
 124  *   (errno is set).
 125  */
 126 struct ec_comp *ec_comp(void);
 127
 128 /**
 129  * Free a completion object and all its items.
 130  *
 131  * @param comp
 132  *   The pointer to the completion structure to free.
 133  */
 134 void ec_comp_free(struct ec_comp *comp);
 135
 136 /**
 137  * Dump the content of a completions list.
 138  *
 139  * @param out
 140  *   The stream where the dump is sent.
 141  * @param comp
 142  *   The pointer to the completion list structure.
 143  */
 144 void ec_comp_dump(FILE *out, const struct ec_comp *comp);
 145
 146 /**
 147  * Merge items contained in 'from' into 'to'.
 148  *
 149  * The 'from' comp struct is freed.
 150  *
 151  * @param to
 152  *   The destination completion list.
 153  * @param from
 154  *   The source completion list.
 155  * @return
 156  *   0 on success, or -1 on error (errno is set).
 157  */
 158 int ec_comp_merge(struct ec_comp *to, struct ec_comp *from);
 159
 160 /**
 161  * Get current parsing state of completion.
 162  *
 163  * This function can be called by a node during the completion process.
 164  *
 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.
 171  *
 172  * @param comp
 173  *   The current completion list.
 174  * @return
 175  *   The current parsing state (cannot be NULL).
 176  */
 177 struct ec_pnode *ec_comp_get_cur_pstate(const struct ec_comp *comp);
 178
 179 /**
 180  * Get current completion group.
 181  *
 182  * This function can be called by a node during the completion process.
 183  *
 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.
 188  *
 189  * @param comp
 190  *   The current completion list.
 191  * @return
 192  *   The current completion group (can be NULL).
 193  */
 194 struct ec_comp_group *ec_comp_get_cur_group(const struct ec_comp *comp);
 195
 196 /**
 197  * Get completion attributes.
 198  *
 199  * Arbitrary attributes (stored in a dictionary) can be attached to a
 200  * completion state.
 201  *
 202  * @param comp
 203  *   The completion list.
 204  * @return
 205  *   The associated attributes.
 206  */
 207 struct ec_dict *ec_comp_get_attrs(const struct ec_comp *comp);
 208
 209 /**
 210  * Add an item in competion list.
 211  *
 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.
 215  *
 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).
 225  *
 226  * @param comp
 227  *   The current completion list.
 228  * @param node
 229  *   The node issuing the completion item.
 230  * @param type
 231  *   The type of the item.
 232  * @param start
 233  *   The incomplete string being completed.
 234  * @param full
 235  *   The string fully completed.
 236  * @return
 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().
 241  */
 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);
 245
 246 /**
 247  * Get the string value of a completion item.
 248  *
 249  * @param item
 250  *   The completion item..
 251  * @return
 252  *   The completion string of this item.
 253  */
 254 const char *
 255 ec_comp_item_get_str(const struct ec_comp_item *item);
 256
 257 /**
 258  * Get the display string value of a completion item.
 259  *
 260  * The display string corresponds to what is displayed when
 261  * listing the possible completions.
 262  *
 263  * @param item
 264  *   The completion item..
 265  * @return
 266  *   The display string of this item.
 267  */
 268 const char *
 269 ec_comp_item_get_display(const struct ec_comp_item *item);
 270
 271 /**
 272  * Get the completion string value of a completion item.
 273  *
 274  * The completion string corresponds to what should be added to
 275  * the incomplete token to complete it.
 276  *
 277  * @param item
 278  *   The completion item.
 279  * @return
 280  *   The completion string of this item.
 281  */
 282 const char *
 283 ec_comp_item_get_completion(const struct ec_comp_item *item);
 284
 285 /**
 286  * Get the group of a completion item.
 287  *
 288  * The completion group corresponds to the list of items that share
 289  * the same parsing state and are issued by the same node.
 290  *
 291  * @param item
 292  *   The completion item.
 293  * @return
 294  *   The completion group of this item.
 295  */
 296 const struct ec_comp_group *
 297 ec_comp_item_get_grp(const struct ec_comp_item *item);
 298
 299 /**
 300  * Get the type of a completion item.
 301  *
 302  * @param item
 303  *   The completion item.
 304  * @return
 305  *   The type of this item (EC_COMP_UNKNOWN, EC_COMP_PARTIAL or
 306  *   EC_COMP_FULL).
 307  */
 308 enum ec_comp_type
 309 ec_comp_item_get_type(const struct ec_comp_item *item);
 310
 311 /**
 312  * Get the node associated to a completion item.
 313  *
 314  * @param item
 315  *   The completion item.
 316  * @return
 317  *   The node that issued the completion item.
 318  */
 319 const struct ec_node *
 320 ec_comp_item_get_node(const struct ec_comp_item *item);
 321
 322 /**
 323  * Set the completion item string.
 324  *
 325  * Some intermediate nodes like sh_lex modify the completion string of
 326  * items generated by their children, for instance to add quotes.
 327  *
 328  * @param item
 329  *   The completion item to update.
 330  * @param str
 331  *   The new item string.
 332  * @return
 333  *   0 on success, or -1 on error (errno is set).
 334  */
 335 int ec_comp_item_set_str(struct ec_comp_item *item, const char *str);
 336
 337 /**
 338  * Set the display value of an item.
 339  *
 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.
 343  *
 344  * @param item
 345  *   The completion item to update.
 346  * @param str
 347  *   The new display string.
 348  * @return
 349  *   0 on success, or -1 on error (errno is set).
 350  */
 351 int ec_comp_item_set_display(struct ec_comp_item *item,
 352                                 const char *display);
 353
 354 /**
 355  * Set the completion value of an item.
 356  *
 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.
 361  *
 362  * @param item
 363  *   The completion item to update.
 364  * @param str
 365  *   The new completion string.
 366  * @return
 367  *   0 on success, or -1 on error (errno is set).
 368  */
 369 int ec_comp_item_set_completion(struct ec_comp_item *item,
 370                                 const char *completion);
 371
 372 /**
 373  * Get the completion group node.
 374  *
 375  * @param grp
 376  *   The completion group.
 377  */
 378 const struct ec_node *
 379 ec_comp_group_get_node(const struct ec_comp_group *grp);
 380
 381 /**
 382  * Get the completion group parsing state.
 383  *
 384  * All items of a completion group are issued by the same node.
 385  * This function returns a pointer to this node.
 386  *
 387  * @param grp
 388  *   The completion group.
 389  * @return
 390  *   The node that issued the completion group.
 391  */
 392 const struct ec_pnode *
 393 ec_comp_group_get_pstate(const struct ec_comp_group *grp);
 394
 395 /**
 396  * Get the completion group attributes.
 397  *
 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.
 401  *
 402   * @param grp
 403  *   The completion group.
 404  * @return
 405  *   The parsing state of the completion group.
 406  */
 407 const struct ec_dict *
 408 ec_comp_group_get_attrs(const struct ec_comp_group *grp);
 409
 410
 411 /**
 412  * Default node completion callback
 413  *
 414  * This function is the default completion method for nodes that do
 415  * not define one.
 416  *
 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
 421  * element.
 422  *
 423  * @param node
 424  *   The completion node.
 425  * @param comp
 426  *   The completion list to update.
 427  * @param strvec
 428  *   The input string vector.
 429  * @return
 430  *   0 on succes, or -1 on error (errno is set).
 431  */
 432 int
 433 ec_complete_unknown(const struct ec_node *node,
 434                         struct ec_comp *comp,
 435                         const struct ec_strvec *strvec);
 436
 437 /**
 438  * Get the number of completion items.
 439  *
 440  * Return the number of completion items that match a given type in a
 441  * completion list.
 442  *
 443  * @param comp
 444  *   The completion list.
 445  * @param type
 446  *   A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
 447  *   EC_COMP_FULL, to select the type to match.
 448  * @return
 449  *   The number of matching items.
 450  */
 451 size_t ec_comp_count(const struct ec_comp *comp, enum ec_comp_type type);
 452
 453 /**
 454  * Get the first completion item matching the type.
 455  *
 456  * Also see EC_COMP_FOREACH().
 457  *
 458  * @param comp
 459  *   The completion list.
 460  * @param type
 461  *   A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
 462  *   EC_COMP_FULL, to select the type to iterate.
 463  * @return
 464  *   A completion item.
 465  */
 466 struct ec_comp_item *
 467 ec_comp_iter_first(const struct ec_comp *comp, enum ec_comp_type type);
 468
 469 /**
 470  * Get the first completion item matching the type.
 471  *
 472  * Also see EC_COMP_FOREACH().
 473  *
 474  * @param comp
 475  *   The completion list.
 476  * @param type
 477  *   A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
 478  *   EC_COMP_FULL, to select the type to iterate.
 479  * @return
 480  *   A completion item.
 481  */
 482 struct ec_comp_item *
 483 ec_comp_iter_next(struct ec_comp_item *item, enum ec_comp_type type);
 484
 485 /**
 486  * Iterate items matching a given type.
 487  *
 488  * @param item
 489  *   The item that will be set at each iteration.
 490  * @param comp
 491  *   The completion list.
 492  * @param type
 493  *   A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and
 494  *   EC_COMP_FULL, to select the type to iterate.
 495  */
 496 #define EC_COMP_FOREACH(item, comp, type)               \
 497         for (item = ec_comp_iter_first(comp, type);     \
 498              item != NULL;                              \
 499              item = ec_comp_iter_next(item, type))
 500
 501 #endif