X-Git-Url: http://git.droids-corp.org/?p=protos%2Flibecoli.git;a=blobdiff_plain;f=include%2Fecoli_complete.h;fp=include%2Fecoli_complete.h;h=8cc28e12fdf152ce9a1fbf87acf5b3a08dc03a95;hp=c36019ad3d1e820abd9905ef3978eacceb4f11a3;hb=331d87b8f34493ea7eb4db75fa9d90b2e3ed503b;hpb=67b4d8d2b2593e3e64a848ce548bc0fd76bc440a diff --git a/include/ecoli_complete.h b/include/ecoli_complete.h index c36019a..8cc28e1 100644 --- a/include/ecoli_complete.h +++ b/include/ecoli_complete.h @@ -6,16 +6,16 @@ * @defgroup complete Complete * @{ * - * @brief Complete string input using a grammar tree + * @brief Complete string input using a grammar graph. * - * This file provide helpers to list and manipulate the possible + * 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 you grammar tree has a lexer that will tokenize - * the input. + * 1. This is common if your grammar graph includes a lexer that + * will tokenize the input. * * These 2 functions return a pointer to an @ec_comp structure, that * lists the possible completions. The completions are grouped into @@ -42,8 +42,8 @@ struct ec_comp; */ enum ec_comp_type { EC_COMP_UNKNOWN = 0x1, - EC_COMP_FULL = 0x2, - EC_COMP_PARTIAL = 0x4, + EC_COMP_FULL = 0x2, /**< The item is fully completed. */ + EC_COMP_PARTIAL = 0x4, /**< The item is partially completed. */ EC_COMP_ALL = 0x7, }; @@ -54,12 +54,12 @@ enum ec_comp_type { * 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 tree that will tokenize the input. + * you have a lexer in your grammar graph that will tokenize the input. * * See @ec_complete_strvec() for more details. * * @param node - * The grammar tree. + * The grammar graph. * @param str * The input string. * @return @@ -79,16 +79,16 @@ struct ec_comp *ec_complete(const struct ec_node *node, * vector should be ["cat", "x"]. * * To get the completion list, the engine parses the beginning of the - * input using the grammar tree. The resulting parsing tree is saved and + * 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. * * @param node - * The grammar tree. - * @param str - * The input string. + * The grammar graph. + * @param strvec + * The input string vector. * @return * A pointer to the completion list on success, or NULL * on error (errno is set). @@ -97,80 +97,159 @@ struct ec_comp *ec_complete_strvec(const struct ec_node *node, const struct ec_strvec *strvec); /** - * Get the list of completions when called from a node completion. + * Get the list of completions of a child node. * - * This function is to be used by ecoli nodes. + * This function is to be used by intermediate ecoli nodes, i.e. nodes + * which have children (ex: ec_node_seq, ec_node_or, ...). It fills an + * existing @ec_comp structure, passed by the parent node. * + * @param node + * The grammar graph. + * @param comp + * The current completion list to be filled. + * @param strvec + * The input string vector. + * @return + * 0 on success, or -1 on error (errno is set). */ int ec_complete_child(const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec); /** - * Create a completion object (list of completion items). - * + * Create an empty completion object (list of completion items). * + * @return + * A pointer to the completion structure on success, or NULL on error + * (errno is set). */ -struct ec_comp *ec_comp(struct ec_pnode *state); +struct ec_comp *ec_comp(void); /** * Free a completion object and all its items. * - * + * @param comp + * The pointer to the completion structure to free. */ void ec_comp_free(struct ec_comp *comp); /** + * Dump the content of a completions list. * - * - * + * @param out + * The stream where the dump is sent. + * @param comp + * The pointer to the completion list structure. */ -void ec_comp_dump(FILE *out, - const struct ec_comp *comp); +void ec_comp_dump(FILE *out, const struct ec_comp *comp); /** - * Merge items contained in 'from' into 'to' + * Merge items contained in 'from' into 'to'. * * The 'from' comp struct is freed. + * + * @param to + * The destination completion list. + * @param from + * The source completion list. + * @return + * 0 on success, or -1 on error (errno is set). */ -int ec_comp_merge(struct ec_comp *to, - struct ec_comp *from); +int ec_comp_merge(struct ec_comp *to, struct ec_comp *from); /** - * Get current completion state. + * 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 "once" + * node checks in the parsing tree if the node is already parsed. + * In this case, no completion is issued. + * + * @param comp + * The current completion list. + * @return + * The current parsing state (cannot be NULL). */ -struct ec_pnode *ec_comp_get_state(const struct ec_comp *comp); +struct ec_pnode *ec_comp_get_cur_pstate(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. + * + * @param comp + * The current completion list. + * @return + * The current completion group (can be NULL). */ -struct ec_comp_group *ec_comp_get_group(const struct ec_comp *comp); +struct ec_comp_group *ec_comp_get_cur_group(const struct ec_comp *comp); /** - * Get completion group attributes. + * Get completion attributes. + * + * Arbitrary attributes (stored in a dictionary) can be attached to a + * completion state. * + * @param comp + * The completion list. + * @return + * The associated attributes. */ struct ec_dict *ec_comp_get_attrs(const struct ec_comp *comp); -/* shortcut for ec_comp_item() + ec_comp_item_add() */ -int ec_comp_add_item(struct ec_comp *comp, - const struct ec_node *node, - struct ec_comp_item **p_item, - enum ec_comp_type type, - const char *start, const char *full); - /** + * Add an item in competion 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 + * how to complete it (ex: the int node). * + * @param comp + * The current completion list. + * @param node + * The node issuing the completion item. + * @param type + * The type of the item. + * @param start + * The incomplete string being completed. + * @param full + * The string fully completed. + * @return + * The item that was added in the list on success, or NULL + * on error. Note: don't 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(). */ -int ec_comp_item_set_str(struct ec_comp_item *item, - const char *str); +struct ec_comp_item *ec_comp_add_item(struct ec_comp *comp, + const struct ec_node *node, enum ec_comp_type type, + const char *start, const char *full); /** * Get the string value of a completion item. * - * + * @param item + * The completion item.. + * @return + * The completion string of this item. */ const char * ec_comp_item_get_str(const struct ec_comp_item *item); @@ -178,7 +257,13 @@ ec_comp_item_get_str(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. * + * @param item + * The completion item.. + * @return + * The display string of this item. */ const char * ec_comp_item_get_display(const struct ec_comp_item *item); @@ -186,7 +271,13 @@ ec_comp_item_get_display(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. * + * @param item + * The completion item. + * @return + * The completion string of this item. */ const char * ec_comp_item_get_completion(const struct ec_comp_item *item); @@ -194,7 +285,13 @@ ec_comp_item_get_completion(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. * + * @param item + * The completion item. + * @return + * The completion group of this item. */ const struct ec_comp_group * ec_comp_item_get_grp(const struct ec_comp_item *item); @@ -202,7 +299,11 @@ ec_comp_item_get_grp(const struct ec_comp_item *item); /** * Get the type of a completion item. * - * + * @param item + * The completion item. + * @return + * The type of this item (EC_COMP_UNKNOWN, EC_COMP_PARTIAL or + * EC_COMP_FULL). */ enum ec_comp_type ec_comp_item_get_type(const struct ec_comp_item *item); @@ -210,15 +311,42 @@ ec_comp_item_get_type(const struct ec_comp_item *item); /** * Get the node associated to a completion item. * - * + * @param item + * The completion item. + * @return + * The node that issued the completion item. */ const struct ec_node * ec_comp_item_get_node(const struct ec_comp_item *item); +/** + * 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. + * + * @param item + * The completion item to update. + * @param str + * The new item string. + * @return + * 0 on success, or -1 on error (errno is set). + */ +int ec_comp_item_set_str(struct ec_comp_item *item, const char *str); + /** * 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 display the base name instead of the full path. * + * @param item + * The completion item to update. + * @param str + * The new display string. + * @return + * 0 on success, or -1 on error (errno is set). */ int ec_comp_item_set_display(struct ec_comp_item *item, const char *display); @@ -226,7 +354,17 @@ int ec_comp_item_set_display(struct ec_comp_item *item, /** * 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. * + * @param item + * The completion item to update. + * @param str + * The new completion string. + * @return + * 0 on success, or -1 on error (errno is set). */ int ec_comp_item_set_completion(struct ec_comp_item *item, const char *completion); @@ -234,52 +372,83 @@ int ec_comp_item_set_completion(struct ec_comp_item *item, /** * Get the completion group node. * - * + * @param grp + * The completion group. */ const struct ec_node * ec_comp_group_get_node(const struct ec_comp_group *grp); /** - * Get the completion group parsed state. + * Get the completion group parsing state. * + * All items of a completion group are issued by the same node. + * This function returns a pointer to this node. * + * @param grp + * The completion group. + * @return + * The node that issued the completion group. */ const struct ec_pnode * -ec_comp_group_get_state(const struct ec_comp_group *grp); +ec_comp_group_get_pstate(const struct ec_comp_group *grp); /** * Get the completion group attributes. * + * 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. * + * @param grp + * The completion group. + * @return + * The parsing state of the completion group. */ const struct ec_dict * ec_comp_group_get_attrs(const struct ec_comp_group *grp); /** + * 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. * + * @param node + * The completion node. + * @param comp + * The completion list to update. + * @param strvec + * The input string vector. + * @return + * 0 on succes, or -1 on error (errno is set). */ int -ec_complete_unknown(const struct ec_node *gen_node, +ec_complete_unknown(const struct ec_node *node, struct ec_comp *comp, const struct ec_strvec *strvec); /** + * Get the number of completion items. * + * Return the number of completion items that match a given type in a + * completion list. * - * - */ -unsigned int ec_comp_count( - const struct ec_comp *comp, - enum ec_comp_type flags); - -/** - * - * - * + * @param comp + * The completion list. + * @param type + * A logical OR of flags among EC_COMP_UNKNOWN, EC_COMP_PARTIAL and + * EC_COMP_FULL, to select the type to match. + * @return + * The number of matching items. */ +size_t ec_comp_count(const struct ec_comp *comp, enum ec_comp_type type); /** * Get the first completion item matching the type.