[COMMITTED] poke: offer an user friendlier prompt by default

[Jose E. Marchesi]

2024-09-16  Jose E. Marchesi  <jemarch@gnu.org>

        * poke/pk-cmd-ios.c (file_cmd): Add flags to command synopsis.
        (proc_cmd): Likewise.
---
 doc/poke.texi | 106 +++++++++++++++++++++++++++++++++++++++++++-------
 poke/poke.pk  |  40 ++++++++++++++++++-
 2 files changed, 130 insertions(+), 16 deletions(-)

diff --git a/doc/poke.texi b/doc/poke.texi
index 4da695db..8ad3941f 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -68,7 +68,7 @@ Customizing poke
 * pokerc::                     User's initialization file.
 * Load Path::                  Determining location of modules.
 * Styling::                    Changing the appearance of poke's output.
-* Changing the Prompt::         The prompt can be made more useful.
+* The Prompt::                  Customize and create your own prompt.
 
 Pickles
 * IOS::                         Functions to work with IO spaces.
@@ -7436,34 +7436,109 @@ time.
 
 XXX
 
-@node Changing the Prompt
-@chapter Changing the Prompt
+@node The Prompt
+@chapter The Prompt
 @cindex prompt, changing the
 
-By default the poke command line interface uses a very simple prompt
-when waiting for commands:
+@section The default prompt
+
+By default the poke prompt shows the following information:
 
 @example
-(poke) _
+(@var{flags}:@var{endianness}:@var{ios})
 @end example
 
 @noindent
-This prompt never changes.
+Where @var{flags} is a set of letters denoting certain settings are
+switched on:
+
+@table @code
+@item p
+Pretty printing is switched on.
+@item 0
+@itemx x
+@itemx o
+@itemx 2
+Output base is decimal, hexadecimal octal or binary respectively.
+@end table
+
+@var{endianness} denotes the currently enabled byte endianness,
+@code{big} for big-endian and @code{little} for little-endian.
+
+@var{ios} is either the handler of the currently selected IO space, or
+@code{poke} if no IO space is opened.
+
+This is an example of a typical prompt:
 
-However, it is possible to customize the prompt by defining a function
+@example
+(p0:big:/bin/ls) _
+@end example
+
+@noindent
+Which tells us that pretty-printing is switched on (the @code{p}
+flag), that the output mode is base 10 (the @code{0} flag), that the
+current endianness is big endian, and that we are currently editing
+@file{/bin/ls}.
+
+Note that if poke has been set to be in ``quiet'' mode (like when
+using the @option{--quiet} command line option, or by setting
+@code{pk_u} then a very simple prompt will be used:
+
+@example
+(poke) _
+@end example
+
+@section Simple customization of the prompt
+
+The information shown by the prompt can be changed at any time by
+simply setting the values of a few variables, all of which are
+booleans:
+
+@table @code
+@item pk_prompt_show_ios
+Whether the currently selected IO space should be shown in the prompt.
+Defaults to 1.
+@item pk_prompt_show_endian
+Whether the current endianness should be shown in the prompt.
+Defaults to 1.
+@item pk_prompt_show_pp
+Whether a @code{p} flag should be shown in the prompt when pretty
+printing is enabled.  Defaults to 1.
+@item pk_prompt_show_obase
+Whether a flag should be shown in the prompt indicating the currently
+selected output numeration base.  Defaults to 1.
+@item pk_prompt_comment
+Whether the prompt shall use @code{#!} and @code{!#} delimiters
+instead of @code{(} and @code{)}.  This makes the prompt a comment in
+Poke and therefore makes it easier to copy code from interactive
+sessions and evaluate it as code.  Defaults to 0.
+@end table
+
+You can customize your poke by setting these variables in your
+@file{.pokerc} file, or at any time by setting the values of the
+variables in the prompt:
+
+@example
+(poke) pk_prompt_comment = 1
+#!poke!# _
+@end example
+
+@section Advanced customization of the prompt
+
+Is possible to further customize the prompt by defining a function
 called @code{pk_prompt}, that gets no arguments and returns a string.
 @command{poke} invokes that function every time it needs to print the
-prompt; the default version of the function just returns @code{"(poke)
-")}.
+prompt; the default version of the function implements what has been
+described in the previous section.
 
-This is an example of customization:
+This is an example of customization of a simple prompt that included
+the current IO space but little else:
 
 @example
 fun pk_prompt = string:
 @{
-  var prompt = "(";
+  var prompt = pk_prompt_comment ? "#!" : "(";
 
-  prompt += get_endian == ENDIAN_BIG ? "big:" : "little:";
   try
     prompt += iohandler (get_ios);
   catch if E_no_ios
@@ -7471,7 +7546,7 @@ fun pk_prompt = string:
       prompt += "poke";
     @};
 
-  return prompt + ") ";
+  return prompt + (pk_prompt_comment ? "#!" : ") ");
 @}
 @end example
 
@@ -7485,6 +7560,9 @@ any:
 (big:/bin/ls)
 @end example
 
+If you write your own @code{pk_prompt} and share it with other people,
+it is a good practice to acknowledge @code{pk_prompt_comment}.
+
 @node IOS
 @chapter IOS
 
diff --git a/poke/poke.pk b/poke/poke.pk
index f80d72c0..765bcd0d 100644
--- a/poke/poke.pk
+++ b/poke/poke.pk
@@ -94,11 +94,47 @@ load "pk-cmd-set.pk";
 load "pk-cmd-misc.pk";
 load "pk-tracer.pk";
 
-/* Default value for poke_prompt.  */
+/* Default machinery for the poke prompt.  */
+
+var pk_prompt_comment = 0;
+var pk_prompt_show_ios = 1;
+var pk_prompt_show_endian = 1;
+var pk_prompt_show_pp = 1;
+var pk_prompt_show_obase = 1;
 
 fun pk_prompt = string:
 {
-  return "(poke) ";
+  if (pk_quiet_p)
+    return pk_prompt_comment ? "#!poke!# " : "(poke) ";
+
+  var prompt = pk_prompt_comment ? "#!" : "(";
+  var flags = "";
+
+  if (pk_prompt_show_pp && vm_opprint)
+    flags += "p";
+
+  if (pk_prompt_show_obase)
+    flags += (vm_obase == 10 ? "0"
+              : vm_obase == 16 ? "x"
+              : vm_obase == 8 ? "o"
+              : vm_obase == 2 ? "2"
+              : "");
+
+  if (flags != "")
+    prompt += flags + ":";
+
+  if (pk_prompt_show_endian)
+    prompt += get_endian == ENDIAN_BIG ? "big:" : "little:";
+
+  if (pk_prompt_show_ios)
+    {
+      try prompt += iohandler (get_ios);
+      catch if E_no_ios { prompt += "poke"; };
+   }
+  else
+    prompt += "poke";
+
+  return prompt + (pk_prompt_comment ? "!# " : ") ");
 }
 
 /* Add the current working directory to the load path.  */
-- 
2.30.2