X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_cmdline%2Fcmdline_parse.h;h=13e086f2d934f9da12f22d852b87230f5bc1582c;hb=844514c73569067061bb32388732e7ac3e977f90;hp=dae53ba79066c7a4e1eb64e0af8fd86a36ebdd37;hpb=a0547e0a751100e6d1a783e69f5bfad85890845f;p=dpdk.git

diff --git a/lib/librte_cmdline/cmdline_parse.h b/lib/librte_cmdline/cmdline_parse.h
index dae53ba790..13e086f2d9 100644
--- a/lib/librte_cmdline/cmdline_parse.h
+++ b/lib/librte_cmdline/cmdline_parse.h
@@ -113,12 +113,14 @@ typedef struct cmdline_token_hdr cmdline_parse_token_hdr_t;
  * -1 on error and 0 on success.
  */
 struct cmdline_token_ops {
-	/** parse(token ptr, buf, res pts) */
-	int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *);
+	/** parse(token ptr, buf, res pts, buf len) */
+	int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *,
+		unsigned int);
 	/** return the num of possible choices for this token */
 	int (*complete_get_nb)(cmdline_parse_token_hdr_t *);
 	/** return the elt x for this token (token, idx, dstbuf, size) */
-	int (*complete_get_elt)(cmdline_parse_token_hdr_t *, int, char *, unsigned int);
+	int (*complete_get_elt)(cmdline_parse_token_hdr_t *, int, char *,
+		unsigned int);
 	/** get help for this token (token, dstbuf, size) */
 	int (*get_help)(cmdline_parse_token_hdr_t *, char *, unsigned int);
 };
@@ -128,6 +130,57 @@ struct cmdline;
  * Store a instruction, which is a pointer to a callback function and
  * its parameter that is called when the instruction is parsed, a help
  * string, and a list of token composing this instruction.
+ *
+ * When no tokens are defined (tokens[0] == NULL), they are retrieved
+ * dynamically by calling f() as follows:
+ *
+ * @code
+ *
+ * f((struct cmdline_token_hdr **)&token_p,
+ *   NULL,
+ *   (struct cmdline_token_hdr **)&inst->tokens[num]);
+ *
+ * @endcode
+ *
+ * The address of the resulting token is expected at the location pointed by
+ * the first argument. Can be set to NULL to end the list.
+ *
+ * The cmdline argument (struct cmdline *) is always NULL.
+ *
+ * The last argument points to the inst->tokens[] entry to retrieve, which
+ * is not necessarily inside allocated memory and should neither be read nor
+ * written. Its sole purpose is to deduce the token entry index of interest
+ * as described in the example below.
+ *
+ * Note about constraints:
+ *
+ * - Only the address of these tokens is dynamic, their storage should be
+ *   static like normal tokens.
+ * - Dynamic token lists that need to maintain an internal context (e.g. in
+ *   order to determine the next token) must store it statically also. This
+ *   context must be reinitialized when the first token is requested, that
+ *   is, when &inst->tokens[0] is provided as the third argument.
+ * - Dynamic token lists must be NULL-terminated to generate usable
+ *   commands.
+ *
+ * @code
+ *
+ * // Assuming first and third arguments are respectively named "token_p"
+ * // and "token":
+ *
+ * int index = token - inst->tokens;
+ *
+ * if (!index) {
+ *     [...] // Clean up internal context if any.
+ * }
+ * [...] // Then set up dyn_token according to index.
+ *
+ * if (no_more_tokens)
+ *     *token_p = NULL;
+ * else
+ *     *token_p = &dyn_token;
+ *
+ * @endcode
  */
 struct cmdline_inst {
 	/* f(parsed_struct, data) */
@@ -182,6 +235,9 @@ int cmdline_complete(struct cmdline *cl, const char *buf, int *state,
  * isendofline(c)) */
 int cmdline_isendoftoken(char c);
 
+/* return true if(!c || iscomment(c) || isendofline(c)) */
+int cmdline_isendofcommand(char c);
+
 #ifdef __cplusplus
 }
 #endif