X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=include%2Fecoli_complete.h;h=ebb5ad0d074da28a23ecb25ed1fd77e6d4b6765a;hb=70ebe6bd8740d8cb32cd0b0a21ca28a4fa74a2a5;hp=b28aa4a873ef77525591398df382a63a0cd77898;hpb=e18710da81b4c53b357dde2ca55005344edc314f;p=protos%2Flibecoli.git

diff --git a/include/ecoli_complete.h b/include/ecoli_complete.h
index b28aa4a..ebb5ad0 100644
--- a/include/ecoli_complete.h
+++ b/include/ecoli_complete.h
@@ -11,7 +11,16 @@
  * This file provide helpers to list and manipulate the possible
  * completions for a given input.
  *
- * XXX comp vs item
+ * 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.
+ *
+ * These 2 functions return a pointer to an @ec_comp structure, that
+ * lists the possible completions. The completions are grouped into
+ * @ec_group. All completions items of a group shares the same parsing
+ * state and are issued by the same node.
  *
  * @}
  */
@@ -24,50 +33,76 @@
 #include <stdio.h>
 
 struct ec_node;
+struct ec_comp_item;
+struct ec_comp_group;
+struct ec_comp;
 
-enum ec_comp_type { /* XXX should be a define */
+/**
+ * Completion item type.
+ */
+enum ec_comp_type {
 	EC_COMP_UNKNOWN = 0x1,
 	EC_COMP_FULL = 0x2,
 	EC_COMP_PARTIAL = 0x4,
 	EC_COMP_ALL = 0x7,
 };
 
-struct ec_comp_item;
-
-TAILQ_HEAD(ec_comp_item_list, ec_comp_item);
-
-struct ec_comp_group {
-	TAILQ_ENTRY(ec_comp_group) next;
-	const struct ec_node *node;
-	struct ec_comp_item_list items;
-	struct ec_parse *state;
-	struct ec_dict *attrs;
-};
-
-TAILQ_HEAD(ec_comp_group_list, ec_comp_group);
-
-struct ec_comp {
-	unsigned count;
-	unsigned count_full;
-	unsigned count_partial;
-	unsigned count_unknown;
-	struct ec_parse *cur_state;
-	struct ec_comp_group *cur_group;
-	struct ec_comp_group_list groups;
-	struct ec_dict *attrs;
-};
-
-/*
- * return a comp object filled with items
- * return NULL on error (nomem?)
+/**
+ * Get the list of completions from a string input.
+ *
+ * It is equivalent that calling @ec_complete_strvec() with a
+ * 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.
+ *
+ * See @ec_complete_strvec() for more details.
+ *
+ * @param node
+ *   The grammar tree.
+ * @param str
+ *   The input string.
+ * @return
+ *   A pointer to the completion list on success, or NULL
+ *   on error (errno is set).
  */
-struct ec_comp *ec_node_complete(const struct ec_node *node,
+struct ec_comp *ec_complete(const struct ec_node *node,
 	const char *str);
-struct ec_comp *ec_node_complete_strvec(const struct ec_node *node,
+
+/**
+ * Get the list of completions from a string vector input.
+ *
+ * This function tries to complete the last element of the given string
+ * vector. For instance, to complete with file names in an equivalent of
+ * the "cat" shell command, the passed vector should be ["cat", ""] (and
+ * not ["cat"]). To complete with files starting with "x", the passed
+ * 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
+ * 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.
+ * @return
+ *   A pointer to the completion list on success, or NULL
+ *   on error (errno is set).
+ */
+struct ec_comp *ec_complete_strvec(const struct ec_node *node,
 	const struct ec_strvec *strvec);
 
-/* internal: used by nodes */
-int ec_node_complete_child(const struct ec_node *node,
+/**
+ * Get the list of completions when called from a node completion.
+ *
+ * This function is to be used by ecoli nodes.
+ *
+ */
+int ec_complete_child(const struct ec_node *node,
 			struct ec_comp *comp,
 			const struct ec_strvec *strvec);
 
@@ -76,7 +111,7 @@ int ec_node_complete_child(const struct ec_node *node,
  *
  *
  */
-struct ec_comp *ec_comp(struct ec_parse *state);
+struct ec_comp *ec_comp(struct ec_pnode *state);
 
 /**
  * Free a completion object and all its items.
@@ -101,7 +136,23 @@ void ec_comp_dump(FILE *out,
 int ec_comp_merge(struct ec_comp *to,
 		struct ec_comp *from);
 
-struct ec_parse *ec_comp_get_state(struct ec_comp *comp);
+/**
+ * Get current completion state.
+ *
+ */
+struct ec_pnode *ec_comp_get_state(const struct ec_comp *comp);
+
+/**
+ * Get current completion group.
+ *
+ */
+struct ec_comp_group *ec_comp_get_group(const struct ec_comp *comp);
+
+/**
+ * Get completion group 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,
@@ -180,13 +231,38 @@ int ec_comp_item_set_display(struct ec_comp_item *item,
 int ec_comp_item_set_completion(struct ec_comp_item *item,
 				const char *completion);
 
+/**
+ * Get the completion group node.
+ *
+ *
+ */
+const struct ec_node *
+ec_comp_group_get_node(const struct ec_comp_group *grp);
+
+/**
+ * Get the completion group parsed state.
+ *
+ *
+ */
+const struct ec_pnode *
+ec_comp_group_get_state(const struct ec_comp_group *grp);
+
+/**
+ * Get the completion group attributes.
+ *
+ *
+ */
+const struct ec_dict *
+ec_comp_group_get_attrs(const struct ec_comp_group *grp);
+
+
 /**
  *
  *
  *
  */
 int
-ec_node_complete_unknown(const struct ec_node *gen_node,
+ec_complete_unknown(const struct ec_node *gen_node,
 			struct ec_comp *comp,
 			const struct ec_strvec *strvec);