From a5447dc2febfea0d2ce2c322ea76bd50228fc95e Mon Sep 17 00:00:00 2001
From: pgen <p.gen.progs@gmail.com>
Date: Sun, 19 Jul 2020 23:25:51 +0200
Subject: [PATCH] Allow ctxopt to activate a debug mode

Any non-empty value set in the CTXOPT_DEBUG environment variable tells
ctxopt to display informational messages as it analyses the command line.
---
 ctxopt.3   |  9 +++++++++
 ctxopt.c   | 43 +++++++++++++++++++++++++++++++++++++++++++
 ctxopt.rst | 11 +++++++++++
 3 files changed, 63 insertions(+)

diff --git a/ctxopt.3 b/ctxopt.3
index 4951d91..7c5fb14 100644
--- a/ctxopt.3
+++ b/ctxopt.3
@@ -945,6 +945,15 @@ each options, if any, one after the other.
 .sp
 This function frees the memory used internally by \fBctxopt\fP\&.
 .UNINDENT
+.SH ENVIRONMENT
+.sp
+\fBctxopt\fP is able to switch to debug mode if the variable CTXOPT_DEBUG
+is set to any not\-empty value.
+.sp
+If this is the case, informational messages about how \fBctxopt\fP
+analyses the command line are printed on the error output.
+.sp
+Each of them are prefixed with "CTXOPT_DEBUG: ".
 .SH AUTHOR
 Pierre Gentile p.gen.progs@gmail.com
 .SH COPYRIGHT
diff --git a/ctxopt.c b/ctxopt.c
index c703a47..f73ff7c 100644
--- a/ctxopt.c
+++ b/ctxopt.c
@@ -3191,6 +3191,10 @@ void
 ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
                char *** rem_args)
 {
+  char * ctxopt_debug_env; /* Environment variable CTXOPT_DEBUG content.  */
+  int    ctxopt_debug;     /* 1 if ctxopt_debug_env is set and not empty. *
+                            | 0 if ctxopt_debug_env is unset or empty.    */
+
   ctx_t *      ctx;
   opt_t *      opt;
   par_t *      par;
@@ -3219,6 +3223,14 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
   /* """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" */
   bst_walk(options_bst, bst_check_opt_cb);
 
+  /* CTXOPT debug setting */
+  /* """""""""""""""""""" */
+  ctxopt_debug_env = getenv("CTXOPT_DEBUG");
+  if (ctxopt_debug_env != NULL && *ctxopt_debug_env != '\0')
+    ctxopt_debug = 1;
+  else
+    ctxopt_debug = 0;
+
   /* Create the first ctx_inst record. */
   /* """"""""""""""""""""""""""""""""" */
   ctx = main_ctx;
@@ -3265,6 +3277,12 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
         /* """""""""""""""""""""  */
         cur_state->ctx_name     = ctx->name;
         cur_state->ctx_par_name = ctx_inst->par_name;
+
+        if (ctxopt_debug)
+          fprintf(stderr,
+                  "CTXOPT_DEBUG: Context forced backtrack, "
+                  "new current context: %s.\n",
+                  ctx->name);
       }
       else
       {
@@ -3284,6 +3302,10 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
       cur_state->ctx_name         = ctx->name;
       cur_state->ctx_par_name     = ctx_inst->par_name;
 
+      if (ctxopt_debug)
+        fprintf(stderr, "CTXOPT_DEBUG: Parameter: %s. Current context: %s.\n",
+                par_name, cur_state->ctx_name);
+
       /* An expected parameter has been seen. */
       /* """""""""""""""""""""""""""""""""""" */
       if ((par = locate_par(par_name, ctx)) == NULL)
@@ -3314,6 +3336,12 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
         prefix = look_for_valid_prefix_in_word(par_name, ctx, &pos, &popt);
         if (prefix != NULL && pos != 0)
         {
+          if (ctxopt_debug)
+            fprintf(stderr,
+                    "CTXOPT_DEBUG: Found a valid parameter "
+                    "as a prefix of %s: %s.\n",
+                    par_name, prefix);
+
           cli_node->data = prefix; /* prefix contains le name of a valid *
                                     | parameter in this context.         */
 
@@ -3387,6 +3415,12 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
             ctx_inst = ctx_inst->prev_ctx_inst;
             ctx      = ctx_inst->ctx;
 
+            if (ctxopt_debug)
+              fprintf(stderr,
+                      "CTXOPT_DEBUG: Context backtrack, "
+                      "new current context: %s.\n",
+                      ctx->name);
+
             /* Update current_state. */
             /* """"""""""""""""""""" */
             cur_state->ctx_name     = ctx->name;
@@ -3564,6 +3598,12 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
           ctx_inst->par_name                 = xstrdup(par_name);
 
           ll_append(ctx_inst_list, ctx_inst);
+
+          if (ctxopt_debug)
+            fprintf(stderr,
+                    "CTXOPT_DEBUG: Context change, "
+                    "new current context: %s.\n",
+                    ctx->name);
         }
 
         /* Look is we must expect some arguments. */
@@ -3614,6 +3654,9 @@ ctxopt_analyze(int nb_words, char ** words, int * nb_rem_args,
       ll_node_t *    cstr_node;
       constraint_t * cstr;
 
+      if (ctxopt_debug)
+        fprintf(stderr, "CTXOPT_DEBUG: Argument: %s.\n", par_name);
+
       /* Check if the arguments of the option respects */
       /* the attached constraints if any.              */
       /* """"""""""""""""""""""""""""""""""""""""""""" */
diff --git a/ctxopt.rst b/ctxopt.rst
index 19dea2c..facdc79 100644
--- a/ctxopt.rst
+++ b/ctxopt.rst
@@ -804,3 +804,14 @@ The API consists in the following functions:
 * **ctxopt_free_memory(void)**
 
   This function frees the memory used internally by **ctxopt**.
+
+ENVIRONMENT
+===========
+
+**ctxopt** is able to switch to debug mode if the variable CTXOPT_DEBUG
+is set to any not-empty value.
+
+If this is the case, informational messages about how **ctxopt**
+analyses the command line are printed on the error output.
+
+Each of them are prefixed with "CTXOPT_DEBUG: ".
-- 
2.11.4.GIT