From b76f12a18544f19e79fbcdcd4bc276fcae2f0b62 Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <fare@tunes.org>
Date: Sat, 28 Oct 2023 13:14:39 +0000
Subject: [PATCH] more tweaks

---
 doc/reference/std/cli/getopt.md | 79 +++++++++++++++++++++++++++++++++
 doc/reference/std/cli/shell.md  | 22 ---------
 2 files changed, 79 insertions(+), 22 deletions(-)

diff --git a/doc/reference/std/cli/getopt.md b/doc/reference/std/cli/getopt.md
index 9df281bc61..f37565f8fb 100644
--- a/doc/reference/std/cli/getopt.md
+++ b/doc/reference/std/cli/getopt.md
@@ -188,3 +188,82 @@ For an example, here the a command line parser for the `gxpkg` program:
       ((search)
        (search-pkgs .keywords)))))
 ```
+
+### getopt-parse-&gt;function-arguments
+```scheme
+(getopt-parse->function-arguments getopt h) => list-of-arguments
+```
+
+This function takes a `getopt` specification and table `h` of arguments
+resulting from calling `getopt-parse`, and returns a list of argument
+with which to call a Scheme function that has an analogous call convention:
+  - supplied positional arguments are passed in order
+  - they are followed by all the rest arguments
+  - they are followed by the remaining specified keyword arguments.
+
+Omitted option arguments without default will be omitted.
+Omitted option arguments with a default will be included with the default value;
+the programmer must ensure that this default value is the same as
+the default value from the Scheme function being called, or there will be
+a semantic discrepancy between the CLI interface and the underlying Scheme function.
+
+NB: `h` will be modified in place, removing positional and rest arguments.
+Make sure to use `hash-copy` if you want to preserve the original data.
+
+TODO: add examples
+
+### call-with-getopt-parse
+```scheme
+(call-with-getopt-parse gopt hash fun) => results-of-fun
+```
+
+Given a getopt specification `gopt`, the `hash` resulting from calling
+`getopt-parse` on some provided command-line arguments, and a function `fun`
+that has a calling convention analogous to that specified by `gopt`,
+call the function with arguments that correspond to those provided by `hash`,
+as per `getopt-parse->function-arguments`.
+
+TODO: add examples, discuss abort-on-error behavior,
+lack of automatic help, etc.
+
+### call-with-processed-command-line
+```scheme
+(call-with-processed-command-line processor command-line function) => results-of-function
+```
+
+Generic function of three arguments:
+  - a `processor` that describes a `getopt` specification,
+  - a `command-line`, list of strings as provided by the invoking process, and
+  - a `function` to be called with the results of processing the command-line.
+
+The function is generic in the first argument.
+The default method recognizes a `getopt` specification as first argument,
+and appropriately calls `getopt-parse` and `call-with-getopt-parse`
+to process the command-line. It also recognizes a list as being arguments
+to which to apply `getopt` to obtain a specification,
+with which to proceed as above.
+
+You may define more methods, to work with your own variant of `getopt`,
+or with innovative ways to incrementally compose `getopt` specifications
+e.g. with prototype objects like `gerbil-poo`.
+
+TODO: add examples, discuss abort-on-error behavior,
+lack of automatic help, etc.
+
+### -&gt;getopt-spec
+```scheme
+(->getopt-spec arg) => list-of-getopt-arguments
+```
+Given an argument `arg`, return a list *lst* of getopt arguments
+to which one can `(apply getopt lst)` to specify a getopt object to parse with.
+
+Default behavior:
+  - If `arg` is a list, `flatten` it.
+  - If `arg` is a natural integer *n*,
+    specify a list of *n* positional `argument`s.
+  - If `arg` is `#f`, specify a single `rest-argument` named `rest`,
+    i.e. let it be a passthrough to be processed by the function being called.
+  - Otherwise, raise an error.
+
+This function is useful for calls not just to `getopt` directly,
+but also to `command` that itself calls `getopt`, etc.
diff --git a/doc/reference/std/cli/shell.md b/doc/reference/std/cli/shell.md
index b3b61f2962..4f89128d1a 100644
--- a/doc/reference/std/cli/shell.md
+++ b/doc/reference/std/cli/shell.md
@@ -70,25 +70,3 @@ when included in a Unix shell command, will expand into the input `string`.
 ```
 :::
 
-### -&gt;envvar
-```scheme
-(->envvar . str) => environment-variable-name
-```
-Given a list of arguments `str`, return a string to be used as
-a shell environment variable name following the convention of having
-only upper-case ASCII letters and digits and underscores.
-
-The arguments are passed to `as-string` then uppercased, and
-any non-empty sequence of characters other than letters and digits
-are replaced by a single underscore.
-
-::: tip Examples:
-``` scheme
-> (->envvar "foo")
-"FOO"
-> (->envvar "bar baz")
-"BAR_BAZ"
-> (->envvar '("bar " "+!@#$") #(#\@ #\! "#") "baz")
-"BAR_BAZ"
-```
-:::