Sync with github's ctxopt commit 30ba991

1 files changed, 730 insertions, 599 deletions

diff --git a/ctxopt.c b/ctxopt.c
index 1c6e55e..0032c89 100644
--- a/ctxopt.c
+++ b/ctxopt.c
@@ -15,9 +15,9 @@
 #include <string.h>
 #include "ctxopt.h"
 
-/* *********************** */
-/* Static global variables */
-/* *********************** */
+/* ************************ */
+/* Static global variables. */
+/* ************************ */
 
 static void * contexts_bst;
 static void * options_bst;
@@ -26,9 +26,9 @@ state_t * cur_state;
 
 /* Prototypes */
 
-/* ************************* */
-/* Fatal messages prototypes */
-/* ************************* */
+/* ************************** */
+/* Fatal messages prototypes. */
+/* ************************** */
 
 static void (**err_functions)(errors e, state_t * state);
 
@@ -44,9 +44,9 @@ static char * user_string;  /* Used by various callback functions */
 static char * user_string2; /* Used by various callback functions */
 static void * user_object;  /* Used by various callback functions */
 
-/* *********************************** */
-/* Memory management static prototypes */
-/* *********************************** */
+/* ************************************ */
+/* Memory management static prototypes. */
+/* ************************************ */
 
 static void *
 xmalloc(size_t size);
@@ -63,9 +63,9 @@ xstrdup(const char * p);
 static char *
 xstrndup(const char * str, size_t len);
 
-/* ********************* */
-/* BST static prototypes */
-/* ********************* */
+/* ********************** */
+/* BST static prototypes. */
+/* ********************** */
 
 typedef struct bst_s bst_t;
 
@@ -99,9 +99,9 @@ bst_walk_recurse(const bst_t * root,
 static void
 bst_walk(const void * vroot, void (*action)(const void *, walk_order_e, int));
 
-/* ***************************** */
-/* Linked list static prototypes */
-/* ***************************** */
+/* ****************************** */
+/* Linked list static prototypes. */
+/* ****************************** */
 
 typedef struct ll_node_s ll_node_t;
 typedef struct ll_s      ll_t;
@@ -144,9 +144,9 @@ ll_destroy(ll_t * const list, void (*)(void *));
 static int
 ll_strarray(ll_t * list, ll_node_t * start_node, int * count, char *** array);
 
-/* ************************* */
-/* Various static prototypes */
-/* ************************* */
+/* ************************** */
+/* Various static prototypes. */
+/* ************************** */
 
 static void
 ltrim(char * str, const char * trim_str);
@@ -160,13 +160,23 @@ strchrcount(char * str, char c);
 static int
 strpref(char * s1, char * s2);
 
+static int
+stricmp(const char * s1, const char * s2);
+
 static char *
 xstrtok_r(char * str, const char * delim, char ** end);
 
-/* ************************ */
-/* ctxopt static prototypes */
-/* ************************ */
+static int
+eval_yes(char * value, int * invalid);
 
+static char *
+get_word(char * str, char * buf, size_t len);
+
+/* ************************* */
+/* ctxopt static prototypes. */
+/* ************************* */
+
+typedef struct flags_s      flags_t;
 typedef struct opt_s        opt_t;
 typedef struct par_s        par_t;
 typedef struct ctx_s        ctx_t;
@@ -269,12 +279,12 @@ new_ctx_inst(ctx_t * ctx, ctx_inst_t * prev_ctx_inst);
 static void
 evaluate_ctx_inst(ctx_inst_t * ctx_inst);
 
-/* ***************************** */
-/* Fatal messages implementation */
-/* ***************************** */
+/* ****************************** */
+/* Fatal messages implementation. */
+/* ****************************** */
 
 /* ================================================================== */
-/* Fatal error function used when an fatal condition was encountered. */
+/* Fatal error function used when a fatal condition is encountered.   */
 /* This function is reserved for the ctxopt internal usage.           */
 /*                                                                    */
 /* format : printf like format                                        */
@@ -298,10 +308,10 @@ fatal_internal(const char * format, ...)
 /* ====================================================================== */
 /* Generic fatal error function. This one uses the global status ctxopt   */
 /* stored in the cur_state structure and can call custom error functions. */
-/* registered by the users for a given error identifier.                  */
+/* registered by the users for a given error identifier if any.           */
 /*                                                                        */
-/* e      : error identifier responsible of the fatal error               */
-/* errmsg : users's provided string specific to the error e               */
+/* e      : Error identifier responsible of the fatal error               */
+/* errmsg : Users's provided string specific to the error e               */
 /*          Note that errmsg is not used in all cases                     */
 /*                                                                        */
 /*          CTXOPTMISPAR Missing parameter                                */
@@ -384,13 +394,13 @@ fatal(errors e, char * errmsg)
       case CTXOPTCTEOPT:
         if (cur_state->ctx_par_name)
           fprintf(stderr,
-                  "%s must appear exactly %u times in the context "
+                  "%s must appear exactly %d times in the context "
                   "introduced by %s.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count,
                   cur_state->ctx_par_name);
         else
           fprintf(stderr,
-                  "%s must appear exactly %u times in "
+                  "%s must appear exactly %d times in "
                   "the main context.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count);
         break;
@@ -398,41 +408,41 @@ fatal(errors e, char * errmsg)
       case CTXOPTCTLOPT:
         if (cur_state->ctx_par_name)
           fprintf(stderr,
-                  "%s must appear less than %u times in the context "
+                  "%s must appear less than %d times in the context "
                   "introduced by %s.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count,
                   cur_state->ctx_par_name);
         else
           fprintf(stderr,
-                  "%s must appear less than %u times in the main context.\n",
+                  "%s must appear less than %d times in the main context.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count);
         break;
 
       case CTXOPTCTGOPT:
         if (cur_state->ctx_par_name)
           fprintf(stderr,
-                  "%s must appear more than %u times in the context "
+                  "%s must appear more than %d times in the context "
                   "introduced by %s.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count,
                   cur_state->ctx_par_name);
         else
           fprintf(stderr,
-                  "%s must appear more than %u times in the main context.\n",
+                  "%s must appear more than %d times in the main context.\n",
                   cur_state->cur_opt_par_name, cur_state->opts_count);
         break;
 
       case CTXOPTCTEARG:
-        fprintf(stderr, "%s must have exactly %u arguments.\n",
+        fprintf(stderr, "%s must have exactly %d arguments.\n",
                 cur_state->cur_opt_par_name, cur_state->opt_args_count);
         break;
 
       case CTXOPTCTLARG:
-        fprintf(stderr, "%s must have less than %u arguments.\n",
+        fprintf(stderr, "%s must have less than %d arguments.\n",
                 cur_state->cur_opt_par_name, cur_state->opt_args_count);
         break;
 
       case CTXOPTCTGARG:
-        fprintf(stderr, "%s must have more than %u arguments.\n",
+        fprintf(stderr, "%s must have more than %d arguments.\n",
                 cur_state->cur_opt_par_name, cur_state->opt_args_count);
         break;
 
@@ -443,16 +453,16 @@ fatal(errors e, char * errmsg)
 
   ctxopt_ctx_disp_usage(cur_state->ctx_name, continue_after);
 
-  exit(e); /* Program exist with the error id e as return code */
+  exit(e); /* Exit with the error id e as return code. */
 }
 
-/* ******************************** */
-/* Memory management implementation */
-/* ******************************** */
+/* ********************************* */
+/* Memory management implementation. */
+/* ********************************* */
 
-/* ================= */
-/* Customized malloc */
-/* ================= */
+/* ================== */
+/* Customized malloc. */
+/* ================== */
 static void *
 xmalloc(size_t size)
 {
@@ -468,9 +478,9 @@ xmalloc(size_t size)
   return allocated;
 }
 
-/* ================= */
-/* Customized calloc */
-/* ================= */
+/* ================== */
+/* Customized calloc. */
+/* ================== */
 static void *
 xcalloc(size_t n, size_t size)
 {
@@ -486,9 +496,9 @@ xcalloc(size_t n, size_t size)
   return allocated;
 }
 
-/* ================== */
-/* Customized realloc */
-/* ================== */
+/* =================== */
+/* Customized realloc. */
+/* =================== */
 static void *
 xrealloc(void * p, size_t size)
 {
@@ -502,9 +512,9 @@ xrealloc(void * p, size_t size)
   return allocated;
 }
 
-/* =================================== */
-/* strdup implementation using xmalloc */
-/* =================================== */
+/* ==================================== */
+/* strdup implementation using xmalloc. */
+/* ==================================== */
 static char *
 xstrdup(const char * p)
 {
@@ -516,10 +526,10 @@ xstrdup(const char * p)
   return allocated;
 }
 
-/* ================================================== */
-/* strndup implementation using xmalloc               */
-/* This version guarantees that there is a final '\0' */
-/* ================================================== */
+/* =================================================== */
+/* strndup implementation using xmalloc.               */
+/* This version guarantees that there is a final '\0'. */
+/* =================================================== */
 static char *
 xstrndup(const char * str, size_t len)
 {
@@ -537,12 +547,12 @@ xstrndup(const char * str, size_t len)
   return p;
 }
 
-/* ************************** */
-/* Linked list implementation */
-/* ************************** */
+/* *************************** */
+/* Linked list implementation. */
+/* *************************** */
 
-/* Linked list node structure */
-/* """""""""""""""""""""""""" */
+/* Linked list node structure. */
+/* """"""""""""""""""""""""""" */
 struct ll_node_s
 {
   void *             data;
@@ -550,8 +560,8 @@ struct ll_node_s
   struct ll_node_s * prev;
 };
 
-/* Linked List structure */
-/* """"""""""""""""""""" */
+/* Linked List structure. */
+/* """""""""""""""""""""" */
 struct ll_s
 {
   ll_node_t * head;
@@ -559,9 +569,9 @@ struct ll_s
   long        len;
 };
 
-/* ======================== */
-/* Create a new linked list */
-/* ======================== */
+/* ========================= */
+/* Create a new linked list. */
+/* ========================= */
 static ll_t *
 ll_new(void)
 {
@@ -572,20 +582,18 @@ ll_new(void)
 }
 
 /* =============================================== */
-/* Free all the elements on a list (make it empty) */
+/* Free all the elements of a list (make it empty) */
 /* NULL or a custom function may be used to free   */
 /* the sub components of the elements.             */
 /* =============================================== */
 static void
 ll_free(ll_t * const list, void (*clean)(void *))
 {
-  ll_node_t * node;
-
   if (list)
     while (list->head)
     {
-      /* Apply a custom cleaner if not NULL */
-      /* """""""""""""""""""""""""""""""""" */
+      /* Apply a custom cleaner if not NULL. */
+      /* """"""""""""""""""""""""""""""""""" */
       if (clean)
         clean(list->head->data);
 
@@ -593,9 +601,9 @@ ll_free(ll_t * const list, void (*clean)(void *))
     }
 }
 
-/* =================================== */
-/* Destroy a list and all its elements */
-/* =================================== */
+/* ==================================== */
+/* Destroy a list and all its elements. */
+/* ==================================== */
 static void
 ll_destroy(ll_t * list, void (*clean)(void *))
 {
@@ -606,9 +614,9 @@ ll_destroy(ll_t * list, void (*clean)(void *))
   }
 }
 
-/* ======================== */
-/* Initialize a linked list */
-/* ======================== */
+/* ========================= */
+/* Initialize a linked list. */
+/* ========================= */
 static void
 ll_init(ll_t * list)
 {
@@ -617,9 +625,9 @@ ll_init(ll_t * list)
   list->len  = 0;
 }
 
-/* ==================================================== */
-/* Allocate the space for a new node in the linked list */
-/* ==================================================== */
+/* ===================================================== */
+/* Allocate the space for a new node in the linked list. */
+/* ===================================================== */
 static ll_node_t *
 ll_new_node(void)
 {
@@ -630,7 +638,7 @@ ll_new_node(void)
 
 /* ==================================================================== */
 /* Append a new node filled with its data at the end of the linked list */
-/* The user is responsible for the memory management of the data        */
+/* The user is responsible for the memory management of the data.       */
 /* ==================================================================== */
 static void
 ll_append(ll_t * const list, void * const data)
@@ -655,10 +663,11 @@ ll_append(ll_t * const list, void * const data)
   ++list->len;
 }
 
-/* =================================================================== */
-/* Put a new node filled with its data at the beginning of the linked  */
-/* list. The user is responsible for the memory management of the data */
-/* =================================================================== */
+/* ================================================================== */
+/* Put a new node filled with its data at the beginning of the linked */
+/* list.                                                              */
+/* The user is responsible for the memory management of the data.     */
+/* ================================================================== */
 static void
 ll_prepend(ll_t * const list, void * const data)
 {
@@ -682,9 +691,9 @@ ll_prepend(ll_t * const list, void * const data)
   ++list->len;
 }
 
-/* ======================================================= */
-/* Insert a new node before the specified node in the list */
-/* ======================================================= */
+/* ======================================================== */
+/* Insert a new node before the specified node in the list. */
+/* ======================================================== */
 static void
 ll_insert_before(ll_t * const list, ll_node_t * node, void * const data)
 {
@@ -696,7 +705,7 @@ ll_insert_before(ll_t * const list, ll_node_t * node, void * const data)
   {
     new_node = ll_new_node(); /* ll_new_node cannot return NULL because it   *
                                | uses xmalloc which does not return if there *
-                               | is an allocation error. */
+                               | is an allocation error.                     */
 
     new_node->data   = data;
     new_node->next   = node;
@@ -708,9 +717,9 @@ ll_insert_before(ll_t * const list, ll_node_t * node, void * const data)
   }
 }
 
-/* ====================================================== */
-/* Insert a new node after the specified node in the list */
-/* ====================================================== */
+/* ======================================================= */
+/* Insert a new node after the specified node in the list. */
+/* ======================================================= */
 static void
 ll_insert_after(ll_t * const list, ll_node_t * node, void * const data)
 {
@@ -722,7 +731,7 @@ ll_insert_after(ll_t * const list, ll_node_t * node, void * const data)
   {
     new_node = ll_new_node(); /* ll_new_node cannot return NULL because it   *
                                | uses xmalloc which does not return if there *
-                               | is an allocation error.                    */
+                               | is an allocation error.                     */
 
     new_node->data   = data;
     new_node->prev   = node;
@@ -734,10 +743,10 @@ ll_insert_after(ll_t * const list, ll_node_t * node, void * const data)
   }
 }
 
-/* ================================================================ */
-/* Remove a node from a linked list                                 */
-/* The memory taken by the deleted node must be freed by the caller */
-/* ================================================================ */
+/* ================================================================= */
+/* Remove a node from a linked list                                  */
+/* The memory taken by the deleted node must be freed by the caller. */
+/* ================================================================= */
 static int
 ll_delete(ll_t * const list, ll_node_t * node)
 {
@@ -772,11 +781,11 @@ ll_delete(ll_t * const list, ll_node_t * node)
 }
 
 #if 0 /* Unused yet */
-/* =========================================================================*/
+/* ======================================================================== */
 /* Find a node in the list containing data. Return the node pointer or NULL */
 /* if not found.                                                            */
 /* A comparison function must be provided to compare a and b (strcmp like). */
-/* =========================================================================*/
+/* ======================================================================== */
 static ll_node_t *
 ll_find(ll_t * const list, void * const data,
         int (*cmpfunc)(const void * a, const void * b))
@@ -797,7 +806,7 @@ ll_find(ll_t * const list, void * const data,
 #endif
 
 /* ==================================================================== */
-/* Allocates and fills an array of strings from a list                  */
+/* Allocate and fill an array of strings from a list.                   */
 /* WARNINGS:                                                            */
 /*   1) The list node must contain strings (char *)                     */
 /*   2) The strings in the resulting array MUST NOT be freed as the are */
@@ -842,7 +851,7 @@ ll_strarray(ll_t * list, ll_node_t * start_node, int * count, char *** array)
 }
 
 /* ******************************************************************* */
-/* BST (search.h compatible) implementation                            */
+/* BST (search.h compatible) implementation.                           */
 /*                                                                     */
 /* Tree search generalized from Knuth (6.2.2) Algorithm T just like    */
 /* the AT&T man page says.                                             */
@@ -860,9 +869,9 @@ struct bst_s
 };
 
 #if 0 /* Unused yet */
-/* ========================== */
-/* delete node with given key */
-/* ========================== */
+/* =========================== */
+/* Delete node with given key. */
+/* =========================== */
 static void *
 bst_delete(const void * vkey, void ** vrootp,
            int (*compar)(const void *, const void *))
@@ -908,9 +917,11 @@ bst_delete(const void * vkey, void ** vrootp,
 }
 #endif
 
-/* ============== */
-/* destroy a tree */
-/* ============== */
+/* ===================================================================== */
+/* Destroy a tree.                                                       */
+/* The clean function pointer can be NULL, in this case the node content */
+/* is not freed.                                                         */
+/* ===================================================================== */
 static void
 bst_destroy(void * vrootp, void (*clean)(void *))
 {
@@ -928,9 +939,9 @@ bst_destroy(void * vrootp, void (*clean)(void *))
   free(root);
 }
 
-/* ======================== */
-/* find a node, or return 0 */
-/* ======================== */
+/* ========================= */
+/* Find a node, or return 0. */
+/* ========================= */
 static void *
 bst_find(const void * vkey, void * const * vrootp,
          int (*compar)(const void *, const void *))
@@ -952,9 +963,9 @@ bst_find(const void * vkey, void * const * vrootp,
   return NULL;
 }
 
-/* ===================================== */
-/* find or insert datum into search tree */
-/* ===================================== */
+/* ======================================= */
+/* Find or inserts datum into search tree. */
+/* ======================================= */
 static void *
 bst_search(void * vkey, void ** vrootp,
            int (*compar)(const void *, const void *))
@@ -986,9 +997,9 @@ bst_search(void * vkey, void ** vrootp,
   return q;
 }
 
-/* ======================== */
-/* Walk the nodes of a tree */
-/* ======================== */
+/* ========================= */
+/* Walk the nodes of a tree. */
+/* ========================= */
 static void
 bst_walk_recurse(const bst_t * root,
                  void (*action)(const void *, walk_order_e, int), int level)
@@ -1014,13 +1025,13 @@ bst_walk(const void * vroot, void (*action)(const void *, walk_order_e, int))
     bst_walk_recurse(vroot, action, 0);
 }
 
-/* *********************** */
-/* Various implementations */
-/* *********************** */
+/* ************************ */
+/* Various implementations. */
+/* ************************ */
 
-/* ======================= */
-/* Trim leading characters */
-/* ======================= */
+/* ======================== */
+/* Trim leading characters. */
+/* ======================== */
 static void
 ltrim(char * str, const char * trim_str)
 {
@@ -1034,7 +1045,7 @@ ltrim(char * str, const char * trim_str)
 }
 
 /* ================================================= */
-/* Trim trailing characters                          */
+/* Trim trailing characters.                         */
 /* The resulting string will have at least min bytes */
 /* even if trailing spaces remain.                   */
 /* ================================================= */
@@ -1049,7 +1060,7 @@ rtrim(char * str, const char * trim_str, size_t min)
 /* ================================================== */
 /* Count the number of occurrences of the character c */
 /* in the string str.                                 */
-/* The str pointer is assumed to be not NULL          */
+/* The str pointer is assumed to be not NULL.         */
 /* ================================================== */
 static int
 strchrcount(char * str, char c)
@@ -1078,8 +1089,26 @@ strpref(char * str1, char * str2)
   return *str2 == '\0';
 }
 
+/* ========================== */
+/* Like strcmp ignoring case. */
+/* ========================== */
+static int
+stricmp(const char * s1, const char * s2)
+{
+  while (tolower((unsigned char)*s1) == tolower((unsigned char)*s2))
+  {
+    if (*s1 == '\0')
+      return 0;
+
+    s1++;
+    s2++;
+  }
+
+  return (int)tolower((unsigned char)*s1) - (int)tolower((unsigned char)*s2);
+}
+
 /* ======================================================================== */
-/* Strings concatenation with dynamic memory allocation                     */
+/* Strings concatenation with dynamic memory allocation.                    */
 /* IN : a variable number of char * arguments with NULL terminating         */
 /*      the sequence.                                                       */
 /*      The first one must have been dynamically allocated and is mandatory */
@@ -1124,7 +1153,7 @@ strappend(char * str, ...)
 }
 
 /* ====================================================================== */
-/*  public domain strtok_r() by Charlie Gordon                            */
+/*  Public domain strtok_r() by Charlie Gordon.                           */
 /*   from comp.lang.c  9/14/2007                                          */
 /*      http://groups.google.com/group/comp.lang.c/msg/2ab1ecbb86646684   */
 /*                                                                        */
@@ -1162,13 +1191,64 @@ xstrtok_r(char * str, const char * delim, char ** end)
   return ret;
 }
 
+/* ===================================================================== */
+/* Put the first word of str, truncated to len characters, in buf.       */
+/* Return a pointer in str pointing just after the word.                 */
+/* buf must have been pre-allocated to accept at least len+1 characters. */
+/* Note that buf can contains a sting full of spaces is str was not      */
+/* trimmed before the call.                                              */
+/* ===================================================================== */
+char *
+get_word(char * str, char * buf, size_t len)
+{
+  char * s = str;
+
+  /* Skip spaces. */
+  /* """""""""""" */
+  while (*s && isspace(*s))
+    s++;
+
+  /* Set the new string start. */
+  /* """"""""""""""""""""""""" */
+  str = s;
+
+  /* Get the word. */
+  /*"""""""""""""" */
+  while (*s && !isspace(*s) && s - str < len)
+    s++;
+
+  strncpy(buf, str, s - str);
+  buf[s - str] = 0;
+
+  return s;
+}
+
+/* ==================================================================== */
+/* Return 1 is value is "1" or "yes" (ignoring case).                   */
+/* Return 0 is value is "0" or "no" (ignoring case).                    */
+/* If value has another value, then set invalid to 1 and also return 0  */
+/* invalid is set to 0i in all the other cases.                         */
+/* ==================================================================== */
+static int
+eval_yes(char * value, int * invalid)
+{
+  *invalid = 0;
+
+  if (strcmp(value, "1") == 0 || stricmp(value, "yes") == 0)
+    return 1;
+  else if (strcmp(value, "0") != 0 && stricmp(value, "no") != 0)
+    *invalid = 1;
+
+  return 0;
+}
+
 /* =========================================================== */
-/* Fills an array of strings from the words composing a string */
+/* Fill an array of strings from the words composing a string. */
 /*                                                             */
-/* str: initial string which will be altered                   */
-/* args: array of pointers to the start of the words in str    */
-/* max: maximum number of words used before giving up          */
-/* return: the number of words (<=max)                         */
+/* str:    initial string which will be altered.               */
+/* args:   array of pointers to the start of the words in str. */
+/* max:    maximum number of words used before giving up.      */
+/* return: the number of words (<=max).                        */
 /* =========================================================== */
 static int
 str2argv(char * str, char ** args, int max)
@@ -1196,20 +1276,28 @@ str2argv(char * str, char ** args, int max)
   return nb_args;
 }
 
-/* ********************* */
-/* ctxopt implementation */
-/* ********************* */
+/* ********************** */
+/* ctxopt implementation. */
+/* ********************** */
 
 static int ctxopt_initialized = 0; /* cap_init has not yet been called */
 
-/* context structure */
-/* """"""""""""""""" */
+/* Flags structure initialized by ctxopt_init. */
+/* """"""""""""""""""""""""""""""""""""""""""" */
+struct flags_s
+{
+  int stop_if_non_option;
+  int allow_abbreviations;
+};
+
+/* Context structure. */
+/* """""""""""""""""" */
 struct ctx_s
 {
   char * name;
-  ll_t * opt_list;    /* list of options allowed in this context       */
+  ll_t * opt_list;    /* list of options allowed in this context.      */
   ll_t * incomp_list; /* list of strings containing incompatible names *
-                       | of options separated by spaces or tabs        */
+                       | of options separated by spaces or tabs.       */
   int (*action)(char * name, int type, char * new_ctx, int ctx_nb_data,
                 void ** ctx_data);
   void *  par_bst;
@@ -1239,107 +1327,106 @@ struct ctx_s
 /*        | ... |                                                */
 /*        +-----+                                                */
 
-/* Option structure */
-/* """""""""""""""" */
+/* Option structure. */
+/* """"""""""""""""" */
 struct opt_s
 {
-  char * name;     /* option name                             */
+  char * name;     /* option name.                            */
   char * next_ctx; /* new context this option may lead to     */
-  ll_t * ctx_list; /* list of contexts allowing this option   */
+  ll_t * ctx_list; /* list of contexts allowing this option.  */
   char * params;   /* string containing all the parameters of *
-                    | the option                              */
-
-  void (*action)(                     /* The option associated action     */
-                 char *  ctx_name,    /* context name                     */
-                 char *  opt_name,    /* option name                      */
-                 char *  par,         /* option parameter                 */
-                 int     nb_args,     /* number of arguments              */
-                 char ** args,        /* option arguments                 */
-                 int     nb_opt_data, /* number of option data pointers   */
-                 void ** opt_data,    /* option data pointers             */
-                 int     nb_ctx_data, /* nb of current  context data ptrs */
-                 void ** ctx_data     /* current context data pointers    */
+                    | the option.                             */
+
+  void (*action)(                     /* The option associated action.     */
+                 char *  ctx_name,    /* context name.                     */
+                 char *  opt_name,    /* option name.                      */
+                 char *  par,         /* option parameter.                 */
+                 int     nb_args,     /* number of arguments.              */
+                 char ** args,        /* option arguments.                 */
+                 int     nb_opt_data, /* number of option data pointers.   */
+                 void ** opt_data,    /* option data pointers.             */
+                 int     nb_ctx_data, /* nb of current  context data ptrs. */
+                 void ** ctx_data     /* current context data pointers.    */
   );
 
-  int nb_data;  /* number of the data pointers passed as argument to   *
-                 | action                                              */
-  void ** data; /* array of data pointers passed as argument to action */
+  int nb_data;  /* number of the data pointers passed as argument to action. */
+  void ** data; /* array of data pointers passed as argument to action.      */
 
-  int args;     /* 1 if this option takes arguments else 0             */
-  int optional; /* 1 if the option is optional, else 0                 */
-  int multiple; /* 1 if the option can appear more than one time in a  *
-                 | context, else 0 */
+  int args;     /* 1 if this option takes arguments else 0.                  */
+  int optional; /* 1 if the option is optional, else 0.                      */
+  int multiple; /* 1 if the option can appear more than one time in a        *
+                 | context, else 0.                                          */
 
-  int      opt_count_matter; /* 1 if we must restrict the count, else 0     */
-  int      occurrences;      /* Number of option occurrences in a context   */
-  char     opt_count_oper;   /* <, = or >                                   */
-  unsigned opt_count_mark;   /* Value to be compared to with opt_count_oper */
+  int      opt_count_matter; /* 1 if we must restrict the count, else 0.     */
+  int      occurrences;      /* Number of option occurrences in a context.   */
+  char     opt_count_oper;   /* <, = or >                                    */
+  unsigned opt_count_mark;   /* Value to be compared to with opt_count_oper. */
 
-  char * arg; /* symbolic text after # describing the option argument */
+  char * arg; /* symbolic text after # describing the option argument.       */
 
-  int optional_args; /* 1 of option is optional else 0                     */
-  int multiple_args; /* 1 is option can appear more than once in a context *
-                      | instance                                           */
+  int optional_args; /* 1 of option is optional else 0.                      */
+  int multiple_args; /* 1 is option can appear more than once in a context   *
+                      | instance.                                            */
 
-  int      opt_args_count_matter; /* 1 if we must restrict the count, else 0 */
+  int      opt_args_count_matter; /* 1 if count is rescticted, else 0.       */
   char     opt_args_count_oper;   /* <, = or >                               */
   unsigned opt_args_count_mark;   /* Value to be compared to with            *
-                                   | opt_count_oper                          */
+                                   | opt_count_oper.                         */
 
-  int eval_first; /* 1 if this option must be evaluated before *
-                   | the options without this mark             */
+  int eval_first; /* 1 if this option must be evaluated before the options   *
+                   | without this mark.                                      */
 
-  ll_t * constraints_list; /* List of constraint checking functions pointers. */
+  ll_t * constraints_list; /* List of constraint check functions pointers.   */
 };
 
-/* Context instance structure */
-/* """""""""""""""""""""""""" */
+/* Context instance structure. */
+/* """"""""""""""""""""""""""" */
 struct ctx_inst_s
 {
   ctx_t *      ctx;           /* the context whose this is an instance of  */
   ctx_inst_t * prev_ctx_inst; /* ctx_inst of the opt_inst which led to the *
                                | creation of this ctx_inst structure.      */
   opt_inst_t * gen_opt_inst;  /* opt_inst which led to the creation of a   *
-                               | instance of this structure                */
-  ll_t * incomp_bst_list;     /* list of seen_opt_t bst                    */
-  void * seen_opt_bst;        /* tree of seen_opt_t                        */
+                               | instance of this structure.               */
+  ll_t * incomp_bst_list;     /* list of seen_opt_t BST.                   */
+  void * seen_opt_bst;        /* tree of seen_opt_t.                       */
   ll_t * opt_inst_list;       /* The list of option instances in this      *
-                               | context instance                          */
-  char * par_name;            /* parameter which created this instance     */
+                               | context instance.                         */
+  char * par_name;            /* parameter which created this instance.    */
 };
 
-/* Option instance structure */
-/* """"""""""""""""""""""""" */
+/* Option instance structure. */
+/* """""""""""""""""""""""""" */
 struct opt_inst_s
 {
-  opt_t *      opt;           /* The option this is an instance of        */
-  char *       opt_name;      /* The option which led to this creation    */
-  char *       par;           /* The parameter which led to this creation */
-  ll_t *       values_list;   /* The list of arguments of this option     */
-  ctx_inst_t * next_ctx_inst; /* The new context instance this option     *
-                               | instance may create                      */
+  opt_t *      opt;           /* The option this is an instance of.        */
+  char *       opt_name;      /* The option which led to this creation.    */
+  char *       par;           /* The parameter which led to this creation. */
+  ll_t *       values_list;   /* The list of arguments of this option.     */
+  ctx_inst_t * next_ctx_inst; /* The new context instance this option.     *
+                               | instance may create.                      */
 };
 
 /* Structure used to check if an option has bee seen or not */
-/* in a context instance                                    */
+/* in a context instance.                                   */
 /* """""""""""""""""""""""""""""""""""""""""""""""""""""""" */
 struct seen_opt_s
 {
-  opt_t * opt;  /* The concerned option                                */
-  char *  par;  /* Parameter which led to the making of this structure */
-  int     seen; /* 1 if seen in the context instances, else 0          */
+  opt_t * opt;  /* The concerned option.                                */
+  char *  par;  /* Parameter which led to the making of this structure. */
+  int     seen; /* 1 if seen in the context instances, else 0.          */
 };
 
-/* Parameter structure which links a parameter to the option it belongs to */
-/* """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" */
+/* Parameter structure which links a parameter to the option it belongs to. */
+/* """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" */
 struct par_s
 {
-  char *  name; /* Parameter name (with the leading - */
-  opt_t * opt;  /* Attached option                    */
+  char *  name; /* Parameter name (with the leading -). */
+  opt_t * opt;  /* Attached option.                     */
 };
 
-/* Constraint structure */
-/* """""""""""""""""""" */
+/* Constraint structure. */
+/* """"""""""""""""""""" */
 struct constraint_s
 {
   int (*constraint)(int nb_args, char ** args, char * value, char * parameter);
@@ -1350,27 +1437,29 @@ struct constraint_s
                     | it to be freed.                                      */
 };
 
-state_t *     cur_state = NULL;            /* Current analysis state        */
-static ll_t * cmdline_list;                /* List of interpreted CLI words *
-                                            | serves as the basis for the   *
-                                            | analysis of the parameters    */
-static ctx_t *      main_ctx       = NULL; /* initial context */
-static ctx_inst_t * first_ctx_inst = NULL; /* Pointer to the fist context   *
-                                            | instance which holds the      *
-                                            | options instances             */
-static ll_t * ctx_inst_list = NULL;        /* List of the context instances */
+sta