Add std/cli, move std/getopt there (#1057)

Import a bunch of CLI utilities from gerbil-utils into std/cli; tweak
them, document them, test them:
  - multicall to support multiple subcommands in a more modular way
  - getopt translation to Scheme calling convention
  - print-exit to print results of Scheme computation at the CLI
  - shell to support escaping strings for the shell

Add a few corresponding utilities to std/error.

Move std/getopt to std/cli/getopt with its brothers; leave a
compatibility shim at std/getopt.

Use std/cli/getopt everywhere instead of std/getopt.

Update documentation.

doc/.vuepress/config.js

@@ -121,6 +121,17 @@ module.exports = {
                         ]
                       },
 
+                      { title: "Unix Command Line Interface",
+                        path: "/reference/std/cli/",
+                        children: [
+                            "cli/",
+                            "cli/getopt",
+                            "cli/shell",
+                            "cli/print-exit",
+                            "cli/multicall",
+                        ]
+                      },
+
                       { title: "Databases and Key-Value Stores",
                         path: "/reference/std/db/",
                         children: [

doc/guide/getting-started.md

@@ -180,7 +180,7 @@ $ cat hello/lib.ss
 $ cat hello/main.ss
 ;;; -*- Gerbil -*-
 (import :std/sugar
-        :std/getopt
+        :std/cli/getopt
         ./lib)
 (export main)
 
@@ -192,7 +192,7 @@ $ cat hello/main.ss
   (call-with-getopt hello-main args
     program: "hello"
     help: "A one line description of your program"
-    ;; commands/options/flags for your program; see :std/getopt
+    ;; commands/options/flags for your program; see :std/cli/getopt
     ;; ...
     ))
 
@@ -268,12 +268,12 @@ $ cat hello/lib.ss
   (displayln greeting ", " who))
 ```
 
-And in the generated `hello/main.ss` file, we add a [getopt](/reference/std/getopt.md) option for a single argument and implement `hello-main/options` to greet:
+And in the generated `hello/main.ss` file, we add a [getopt](/reference/std/cli/getopt.md) option for a single argument and implement `hello-main/options` to greet:
 ```scheme
 $ cat hello/main.ss
 ;;; -*- Gerbil -*-
 (import :std/sugar
-        :std/getopt
+        :std/cli/getopt
         ./lib)
 (export main)
 

doc/reference/dev/build.md

@@ -212,7 +212,7 @@ $ cat scraper/main.ss
 ;;; -*- Gerbil -*-
 (import :std/error
         :std/sugar
-        :std/getopt
+        :std/cli/getopt
         :gerbil/gambit
         ./lib)
 (export main)
@@ -494,7 +494,7 @@ $ cat scraper/main.ss
 ;;; -*- Gerbil -*-
 (import :std/error
         :std/sugar
-        :std/getopt
+        :std/cli/getopt
         :gerbil/gambit
         ./lib)
 (export main)

doc/reference/gerbil/expander/README.md

@@ -681,7 +681,7 @@ Please document me!
 
 Please document me!
 
-### core-module-export->import
+### core-module-export->import
 ```
 (core-module-export->import ...)
 ```

doc/reference/gerbil/runtime/MOP.md

@@ -294,7 +294,7 @@ Accesses *obj*'s field with absolute offset *off*; there is no type check.
 
 Mutates *obj*'s field with absolute offset *off* to *val*; there is no type check.
 
-## struct->list
+## struct->list
 ``` scheme
 (struct->list obj) -> list
 
@@ -482,7 +482,7 @@ Returns the value associated with slot *slot* in *obj*, without any checks.
 
 Sets the value associated with slot *slot* in *obj* to *val*, without any checks.
 
-## class->list
+## class->list
 ``` scheme
 (class->list obj)
 

doc/reference/gerbil/runtime/hash-tables.md

@@ -240,7 +240,7 @@ Merges *more* hash tables into *hash*. Entries in hash tables on the left take p
 ((a . 1) (z . 6) (b . 2) (c . 3))
 ```
 
-## hash->list
+## hash->list
 ``` scheme
 (hash->list hash) -> list
 
@@ -249,7 +249,7 @@ Merges *more* hash tables into *hash*. Entries in hash tables on the left take p
 
 Returns the bindings of *hash* as an alist.
 
-## list->hash-table
+## list->hash-table
 ``` scheme
 (list->hash-table lst . options) -> hash table
 
@@ -258,7 +258,7 @@ Returns the bindings of *hash* as an alist.
 
 Creates a hash table from an alist *lst*.
 
-## list->hash-table-eq
+## list->hash-table-eq
 ``` scheme
 (list->hash-table-eq lst . options) -> hash table
 
@@ -267,7 +267,7 @@ Creates a hash table from an alist *lst*.
 
 Same as `list->hash-table`, but using `eq?` as the test function for the table.
 
-## list->hash-table-eqv
+## list->hash-table-eqv
 ``` scheme
 (list->hash-table-eqv lst . options) -> hash table
 
@@ -276,7 +276,7 @@ Same as `list->hash-table`, but using `eq?` as the test function for the table.
 
 Same as `list->hash-table`, but using `eqv?` as the test function for the table.
 
-## hash->plist
+## hash->plist
 ``` scheme
 (hash->plist hash) -> list
 
@@ -285,7 +285,7 @@ Same as `list->hash-table`, but using `eqv?` as the test function for the table.
 
 Returns the bindings of *hash* as a plist.
 
-## plist->hash-table
+## plist->hash-table
 ``` scheme
 (plist->hash-table lst) -> hash table
 
@@ -294,7 +294,7 @@ Returns the bindings of *hash* as a plist.
 
 Creates a hash table from a plist *lst*.
 
-## plist->hash-table-eq
+## plist->hash-table-eq
 ``` scheme
 (plist->hash-table-eq lst) -> hash table
 
@@ -303,7 +303,7 @@ Creates a hash table from a plist *lst*.
 
 Same as `plist->hash-table`, but using `eq?` as the test function for the table.
 
-## plist->hash-table-eqv
+## plist->hash-table-eqv
 ``` scheme
 (plist->hash-table-eqv lst) -> hash table
 

doc/reference/gerbil/runtime/misc-procedures.md

@@ -20,7 +20,7 @@ it is considered a single value.
 Returns the *n*th value in the object *obj*. If the object is not multiple `values`,
 it returns the object itself.
 
-### values->list
+### values->list
 ``` scheme
 (values->list obj) -> list
 
@@ -30,7 +30,7 @@ it returns the object itself.
 Converts multiple `values` to a list. If the object *obj* is not multiple `values`,
 it returns a list containing the object.
 
-### subvector->list
+### subvector->list
 ``` scheme
 (subvector->list obj [start = 0]) -> list
 

doc/reference/gerbil/runtime/strings.md

@@ -1,6 +1,6 @@
 # Strings
 
-## bytes->string
+## bytes->string
 ```
 (bytes->string bstr [encoding = 'UTF-8]) -> string
 
@@ -12,7 +12,7 @@ Decodes a byte vector *bstr* to a string.
 Note: if you are decoding UTF-8, then you should consider using `string->utf8`
 from `:std/text/utf8` which is considerably faster.
 
-## string->bytes
+## string->bytes
 ``` scheme
 (string->bytes str [encoding = 'UTF-8]) -> u8vector
 
@@ -25,7 +25,7 @@ Note: if you are encoding UTF-8, then you should consider using `utf8->string`
 from `:std/text/utf8` which is considerably faster.
 
 
-## substring->bytes
+## substring->bytes
 ``` scheme
 (substring->bytes str start end [encoding = 'UTF-8]) -> u8vector
 

doc/reference/gerbil/runtime/symbols.md

@@ -32,7 +32,7 @@ Returns true if the object *obj* is an interned symbol.
 
 Returns true if the object *obj* is an interned keyword.
 
-## symbol->keyword
+## symbol->keyword
 ``` scheme
 (symbol->keyword sym) -> keyword
 
@@ -41,7 +41,7 @@ Returns true if the object *obj* is an interned keyword.
 
 Converts a symbol *sym* to a keyword.
 
-## keyword->symbol
+## keyword->symbol
 ``` scheme
 (keyword->symbol kw) -> symbol
 

doc/reference/std/cli/README.md

@@ -0,0 +1,7 @@
+# Command Line Interface
+
+The following libraries are provided to support the Command Line Interface (CLI):
+- [:std/cli/getopt](getopt.md)
+- [:std/cli/shell](shell.md)
+- [:std/cli/print-exit](print-exit.md)
+- [:std/cli/multicall](multicall.md)