8b798bfb7f66

Fix Markdown
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Tue, 21 May 2019 22:55:18 -0400
parents a37d95a0d868
children 8115d14339b3
branches/tags (none)
files docs/02-reference.markdown src/main.lisp

Changes

diff -r a37d95a0d868 -r 8b798bfb7f66 docs/02-reference.markdown
--- a/docs/02-reference.markdown	Tue May 21 22:51:55 2019 -0400
+++ b/docs/02-reference.markdown	Tue May 21 22:55:18 2019 -0400
@@ -18,9 +18,9 @@
 
 Return a list of the program name and command line arguments.
 
-  This is not implemented for every Common Lisp implementation.  You can always
-  pass your own values to `parse-options` and `print-help` if it's not
-  implemented for your particular Lisp.
+  This is not implemented for every Common Lisp implementation.  You can pass
+  your own values to `parse-options` and `print-help` if it's not implemented
+  for your particular Lisp.
 
   
 
@@ -62,6 +62,14 @@
 
     (EXIT &OPTIONAL (CODE 0))
 
+Exit the program with status `code`.
+
+  This is not implemented for every Common Lisp implementation.  You can write
+  your own version of it and pass it to `print-help-and-exit` and
+  `print-error-and-exit` if it's not implemented for your particular Lisp.
+
+  
+
 ### `FIRST` (function)
 
     (FIRST OLD NEW)
@@ -106,14 +114,74 @@
 
     (MAKE-GROUP NAME &KEY TITLE HELP MANUAL OPTIONS)
 
+Create and return an option group, suitable for use in an interface.
+
+  This function takes a number of arguments that define how the group is
+  presented to the user:
+
+  * `name` (**required**): a symbol naming the group.
+  * `title` (optional): a title for the group for use in the help text.
+  * `help` (optional): a short summary of this group of options for use in the help text.
+  * `manual` (optional): used in place of `help` when rendering a man page.
+  * `options` (**required**): the options to include in the group.
+
+  See the full documentation for more information.
+
+  
+
 ### `MAKE-INTERFACE` (function)
 
     (MAKE-INTERFACE &KEY NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS)
 
+Create and return a command line interface.
+
+  This function takes a number of arguments that define how the interface is
+  presented to the user:
+
+  * `name` (**required**): a symbol naming the interface.
+  * `summary` (**required**): a string of a concise, one-line summary of what the program does.
+  * `usage` (**required**): a string of a UNIX-style usage summary, e.g. "[OPTIONS] PATTERN [FILE...]".
+  * `help` (**required**): a string of a longer description of the program.
+  * `manual` (optional): a string to use in place of `help` when rendering a man page.
+  * `examples` (optional): an alist of `(prose . command)` conses to render as a list of examples.
+  * `contents` (optional): a list of options and groups.  Ungrouped options will be collected into a single top-level group.
+
+  See the full documentation for more information.
+
+  
+
 ### `MAKE-OPTION` (function)
 
-    (MAKE-OPTION NAME &KEY LONG SHORT HELP MANUAL PARAMETER REDUCE (RESULT-KEY NAME)
-                 (INITIAL-VALUE NIL INITIAL-VALUE?) (KEY #'IDENTITY) (FINALLY #'IDENTITY))
+    (MAKE-OPTION NAME &KEY LONG SHORT HELP MANUAL PARAMETER REDUCE
+                 (INITIAL-VALUE NIL INITIAL-VALUE?) (RESULT-KEY NAME) (KEY #'IDENTITY)
+                 (FINALLY #'IDENTITY))
+
+Create and return an option, suitable for use in an interface.
+
+  This function takes a number of arguments, some required, that define how the
+  option interacts with the user.
+
+  * `name` (**required**): a symbol naming the option.
+  * `help` (**required**): a short string describing what the option does.
+  * `result-key` (optional): a symbol to use as the key for this option in the hash table of results.
+  * `long` (optional): a string for the long form of the option (e.g. `--foo`).
+  * `short` (optional): a character for the short form of the option (e.g. `-f`).  At least one of `short` and `long` must be given.
+  * `manual` (optional): a string to use in place of `help` when rendering a man page.
+  * `parameter` (optional): a string.  If given, it will turn this option into a parameter-taking option (e.g. `--foo=bar`) and will be used as a placeholder
+  in the help text.
+  * `reduce` (**required**): a function designator that will be called every time the option is specified by the user.
+  * `initial-value` (optional): a value to use as the initial value of the option.
+  * `key` (optional): a function designator, only allowed for parameter-taking options, to be called on the values given by the user before they are passed along to the reducing function.  It will not be called on the initial value.
+  * `finally` (optional): a function designator to be called on the final result after all parsing is complete. 
+
+  The manner in which the reducer is called depends on whether the option takes a parameter:
+
+  * For options that don't take parameters, it will be called with the old value.
+  * For options that take parameters, it will be called with the old value and the value given by the user.
+
+  See the full documentation for more information.
+
+  
 
 ### `PARSE-OPTIONS` (function)
 
@@ -133,7 +201,8 @@
 
 ### `PRINT-ERROR-AND-EXIT` (function)
 
-    (PRINT-ERROR-AND-EXIT ERROR &KEY (STREAM *ERROR-OUTPUT*) (EXIT-CODE 1) (PREFIX error: ))
+    (PRINT-ERROR-AND-EXIT ERROR &KEY (STREAM *ERROR-OUTPUT*) (EXIT-FUNCTION #'EXIT) (EXIT-CODE 1)
+                          (PREFIX error: ))
 
 Print `prefix` and `error` to `stream` and exit.
 
@@ -192,7 +261,8 @@
 ### `PRINT-HELP-AND-EXIT` (function)
 
     (PRINT-HELP-AND-EXIT INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV)))
-                         (WIDTH 80) (OPTION-WIDTH 20) (INCLUDE-EXAMPLES T) (EXIT-CODE 0))
+                         (WIDTH 80) (OPTION-WIDTH 20) (INCLUDE-EXAMPLES T) (EXIT-FUNCTION #'EXIT)
+                         (EXIT-CODE 0))
 
 Print a pretty help document for `interface` to `stream` and exit.
 
@@ -202,12 +272,24 @@
       (when (gethash 'help options)
         (print-help-and-exit *ui*))
       (run arguments options))
+
   
 
 ### `PRINT-MANUAL` (function)
 
     (PRINT-MANUAL INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (MANUAL-SECTION 1))
 
+Print a troff-formatted man page for `interface` to `stream`.
+
+  Example:
+
+    (with-open-file (manual "man/man1/foo.1"
+                            :direction :output
+                            :if-exists :supersede)
+      (print-manual *ui* manual))
+
+  
+
 ### `SUPPLY-NEW-VALUE` (function)
 
     (SUPPLY-NEW-VALUE CONDITION VALUE)
diff -r a37d95a0d868 -r 8b798bfb7f66 src/main.lisp
--- a/src/main.lisp	Tue May 21 22:51:55 2019 -0400
+++ b/src/main.lisp	Tue May 21 22:55:18 2019 -0400
@@ -271,7 +271,7 @@
 
   * `name` (**required**): a symbol naming the interface.
   * `summary` (**required**): a string of a concise, one-line summary of what the program does.
-  * `usage` (**required**): a string of a UNIX-style usage summary, e.g. \"[OPTIONS] PATTERN [FILE...]\".
+  * `usage` (**required**): a string of a UNIX-style usage summary, e.g. `\"[OPTIONS] PATTERN [FILE...]\"`.
   * `help` (**required**): a string of a longer description of the program.
   * `manual` (optional): a string to use in place of `help` when rendering a man page.
   * `examples` (optional): an alist of `(prose . command)` conses to render as a list of examples.