--- a/adopt/_dmedia/style.less Wed Jun 21 15:21:12 2023 -0400
+++ b/adopt/_dmedia/style.less Thu Jun 13 13:05:28 2024 -0400
@@ -8,7 +8,7 @@
body {
font-size: 16px;
line-height: 1.4;
- font-family: Georgia, Palatino, "Palatino Linotype", serif;
+ font-family: serif;
color: #111111;
}
a {
@@ -16,7 +16,7 @@
color: #0069d6;
}
h1, h2, h3, h4, h5 {
- font-family: Palatino, "Palatino Linotype", serif;
+ font-family: serif;
a {
color: #111111;
@@ -99,6 +99,12 @@
padding: 1px 4px;
font-family: Menlo, Monaco, Consolas, monospace;
}
+
+pre code {
+ border: none;
+ padding: 0px;
+ background: none;
+}
ol, ul {
margin-bottom: 9px;
}
--- a/adopt/reference/index.html Wed Jun 21 15:21:12 2023 -0400
+++ b/adopt/reference/index.html Thu Jun 13 13:05:28 2024 -0400
@@ -1,10 +1,10 @@
<!DOCTYPE html>
<html>
<head>
- <meta charset="utf-8"/>
+ <meta charset="utf-8">
<title> API Reference / Adopt</title>
- <link rel="stylesheet" href="../_dmedia/tango.css"/>
- <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
+ <link rel="stylesheet" href="../_dmedia/tango.css">
+ <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less">
<script src="../_dmedia/less.js" type="text/javascript">
</script>
</head>
@@ -12,7 +12,8 @@
<div class="wrap">
<header><h1><a href="..">Adopt</a></h1></header>
<div class="markdown">
-<h1 id="api-reference"><a href="">API Reference</a></h1><p>The following is a list of all user-facing parts of adopt.</p>
+<h1 id="api-reference"><a href="">API Reference</a></h1>
+<p>The following is a list of all user-facing parts of adopt.</p>
<p>If there are backwards-incompatible changes to anything listed here, they will
be noted in the changelog and the author will feel bad.</p>
<p>Anything not listed here is subject to change at any time with no warning, so
@@ -47,38 +48,31 @@
</li>
</ul>
</li>
-</ul></div>
+</ul>
+</div>
<h2 id="package-adopt">Package <code>ADOPT</code></h2>
<h3 id="argv-function"><code>ARGV</code> (function)</h3>
-<div class="codehilite"><pre><span/>(ARGV)
-</pre></div>
-
-
+<pre><code>(ARGV)
+</code></pre>
<p>Return a list of the program name and command line arguments.</p>
<p>This is not implemented for every Common Lisp implementation. You can pass
your own values to <code>parse-options</code> and <code>print-help</code> if it's not implemented
for your particular Lisp.</p>
<h3 id="collect-function"><code>COLLECT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(COLLECT LIST EL)
-</pre></div>
-
-
+<pre><code>(COLLECT LIST EL)
+</code></pre>
<p>Append element <code>el</code> to the end of <code>list</code>.</p>
<p>It is useful as a <code>:reduce</code> function when you want to collect all values given
for an option.</p>
<p>This is implemented as <code>(append list (list el))</code>. It is not particularly
fast. If you can live with reversed output consider <code>(flip #'cons)</code> instead.</p>
<h3 id="define-string-macro"><code>DEFINE-STRING</code> (macro)</h3>
-<div class="codehilite"><pre><span/>(DEFINE-STRING VAR STRING &REST ARGS)
-</pre></div>
-
-
+<pre><code>(DEFINE-STRING VAR STRING &REST ARGS)
+</code></pre>
<p>Convenience macro for <code>(defparameter ,var (format nil ,string ,@args))</code>.</p>
<h3 id="defparameters-macro"><code>DEFPARAMETERS</code> (macro)</h3>
-<div class="codehilite"><pre><span/>(DEFPARAMETERS PARAMETERS VALUES-FORM)
-</pre></div>
-
-
+<pre><code>(DEFPARAMETERS PARAMETERS VALUES-FORM)
+</code></pre>
<p>Convenience macro for <code>defparameter</code>ing multiple variables at once.</p>
<p><code>parameters</code> must be a list of special variable names suitable for giving to
<code>defparameter</code>.</p>
@@ -87,7 +81,7 @@
<p>This can be handy when using <code>make-boolean-options</code> to create two <code>option</code>s at
once and assign them to special variables.</p>
<p>Examples:</p>
-<div class="codehilite"><pre><span/>(defparameters (*a* *b*) (truncate 100 3))
+<pre><code>(defparameters (*a* *b*) (truncate 100 3))
(list *a* *b*)
; =>
; (33 1)
@@ -98,72 +92,54 @@
:help-no "Do not foo the widgets during the run (the default)."
:long "foo"
:short #f))
-</pre></div>
-
-
+</code></pre>
<h3 id="discard-option-function"><code>DISCARD-OPTION</code> (function)</h3>
-<div class="codehilite"><pre><span/>(DISCARD-OPTION CONDITION)
-</pre></div>
-
-
+<pre><code>(DISCARD-OPTION CONDITION)
+</code></pre>
<p>Invoke the <code>discard-option</code> restart properly.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(handler-bind ((unrecognized-option 'discard-option))
+<pre><code>(handler-bind ((unrecognized-option 'discard-option))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
-</pre></div>
-
-
+</code></pre>
<h3 id="exit-function"><code>EXIT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(EXIT &OPTIONAL (CODE 0))
-</pre></div>
-
-
+<pre><code>(EXIT &OPTIONAL (CODE 0))
+</code></pre>
<p>Exit the program with status <code>code</code>.</p>
<p>This is not implemented for every Common Lisp implementation. You can write
your own version of it and pass it to <code>print-help-and-exit</code> and
<code>print-error-and-exit</code> if it's not implemented for your particular Lisp.</p>
<h3 id="first-function"><code>FIRST</code> (function)</h3>
-<div class="codehilite"><pre><span/>(FIRST OLD NEW)
-</pre></div>
-
-
+<pre><code>(FIRST OLD NEW)
+</code></pre>
<p>Return <code>new</code> if <code>old</code> is <code>nil</code>, otherwise return <code>old</code>.</p>
<p>It is useful as a <code>:reduce</code> function when you want to just keep the
first-given value for an option.</p>
<h3 id="flip-function"><code>FLIP</code> (function)</h3>
-<div class="codehilite"><pre><span/>(FLIP FUNCTION)
-</pre></div>
-
-
+<pre><code>(FLIP FUNCTION)
+</code></pre>
<p>Return a function of two arguments X and Y that calls <code>function</code> with Y and X.</p>
<p>Useful for wrapping existing functions that expect their arguments in the
opposite order.</p>
<p>Examples:</p>
-<div class="codehilite"><pre><span/>(funcall #'cons 1 2) ; => (1 . 2)
+<pre><code>(funcall #'cons 1 2) ; => (1 . 2)
(funcall (flip #'cons) 1 2) ; => (2 . 1)
(reduce (flip #'cons) '(1 2 3) :initial-value nil)
; => (3 2 1)
-</pre></div>
-
-
+</code></pre>
<h3 id="last-function"><code>LAST</code> (function)</h3>
-<div class="codehilite"><pre><span/>(LAST OLD NEW)
-</pre></div>
-
-
+<pre><code>(LAST OLD NEW)
+</code></pre>
<p>Return <code>new</code>.</p>
<p>It is useful as a <code>:reduce</code> function when you want to just keep the last-given
value for an option.</p>
<h3 id="make-boolean-options-function"><code>MAKE-BOOLEAN-OPTIONS</code> (function)</h3>
-<div class="codehilite"><pre><span/>(MAKE-BOOLEAN-OPTIONS NAME &KEY
+<pre><code>(MAKE-BOOLEAN-OPTIONS NAME &KEY
(NAME-NO (INTERN (CONCATENATE 'STRING (STRING 'NO-) (STRING NAME)))) LONG
(LONG-NO (WHEN LONG (FORMAT NIL no-~A LONG))) SHORT
(SHORT-NO (WHEN SHORT (CHAR-UPCASE SHORT))) (RESULT-KEY NAME) HELP
HELP-NO MANUAL MANUAL-NO INITIAL-VALUE)
-</pre></div>
-
-
+</code></pre>
<p>Create and return a pair of boolean options, suitable for use in an interface.</p>
<p>This function reduces some of the boilerplate when creating two <code>option</code>s for
boolean values, e.g. <code>--foo</code> and <code>--no-foo</code>. It will try to guess at an
@@ -173,7 +149,7 @@
<code>defparameters</code> to conveniently bind them to two separate variables if
desired.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(defparameters (*option-debug* *option-no-debug*)
+<pre><code>(defparameters (*option-debug* *option-no-debug*)
(make-boolean-options 'debug
:long "debug"
:short #d
@@ -196,14 +172,10 @@
:short #D
:help "Disable the Lisp debugger (the default)."
:reduce (constantly nil))
-</pre></div>
-
-
+</code></pre>
<h3 id="make-group-function"><code>MAKE-GROUP</code> (function)</h3>
-<div class="codehilite"><pre><span/>(MAKE-GROUP NAME &KEY TITLE HELP MANUAL OPTIONS)
-</pre></div>
-
-
+<pre><code>(MAKE-GROUP NAME &KEY TITLE HELP MANUAL OPTIONS)
+</code></pre>
<p>Create and return an option group, suitable for use in an interface.</p>
<p>This function takes a number of arguments that define how the group is
presented to the user:</p>
@@ -216,10 +188,8 @@
</ul>
<p>See the full documentation for more information.</p>
<h3 id="make-interface-function"><code>MAKE-INTERFACE</code> (function)</h3>
-<div class="codehilite"><pre><span/>(MAKE-INTERFACE &KEY NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS)
-</pre></div>
-
-
+<pre><code>(MAKE-INTERFACE &KEY NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS)
+</code></pre>
<p>Create and return a command line interface.</p>
<p>This function takes a number of arguments that define how the interface is
presented to the user:</p>
@@ -234,12 +204,10 @@
</ul>
<p>See the full documentation for more information.</p>
<h3 id="make-option-function"><code>MAKE-OPTION</code> (function)</h3>
-<div class="codehilite"><pre><span/>(MAKE-OPTION NAME &KEY LONG SHORT HELP MANUAL PARAMETER REDUCE
+<pre><code>(MAKE-OPTION NAME &KEY LONG SHORT HELP MANUAL PARAMETER REDUCE
(INITIAL-VALUE NIL INITIAL-VALUE?) (RESULT-KEY NAME) (KEY #'IDENTITY)
(FINALLY #'IDENTITY))
-</pre></div>
-
-
+</code></pre>
<p>Create and return an option, suitable for use in an interface.</p>
<p>This function takes a number of arguments, some required, that define how the
option interacts with the user.</p>
@@ -264,10 +232,8 @@
</ul>
<p>See the full documentation for more information.</p>
<h3 id="parse-options-function"><code>PARSE-OPTIONS</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PARSE-OPTIONS INTERFACE &OPTIONAL (ARGUMENTS (REST (ARGV))))
-</pre></div>
-
-
+<pre><code>(PARSE-OPTIONS INTERFACE &OPTIONAL (ARGUMENTS (REST (ARGV))))
+</code></pre>
<p>Parse <code>arguments</code> according to <code>interface</code>.</p>
<p>Two values are returned:</p>
<ol>
@@ -277,10 +243,8 @@
</ol>
<p>See the full documentation for more information.</p>
<h3 id="parse-options-or-exit-function"><code>PARSE-OPTIONS-OR-EXIT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PARSE-OPTIONS-OR-EXIT INTERFACE &OPTIONAL (ARGUMENTS (REST (ARGV))))
-</pre></div>
-
-
+<pre><code>(PARSE-OPTIONS-OR-EXIT INTERFACE &OPTIONAL (ARGUMENTS (REST (ARGV))))
+</code></pre>
<p>Parse <code>arguments</code> according to <code>interface</code>, exiting if any error occurs.</p>
<p>Two values are returned:</p>
<ol>
@@ -292,27 +256,21 @@
<code>adopt:print-error-and-exit</code>.</p>
<p>See the full documentation for more information.</p>
<h3 id="print-error-and-exit-function"><code>PRINT-ERROR-AND-EXIT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PRINT-ERROR-AND-EXIT ERROR &KEY (STREAM *ERROR-OUTPUT*) (EXIT-FUNCTION #'EXIT) (EXIT-CODE 1)
+<pre><code>(PRINT-ERROR-AND-EXIT ERROR &KEY (STREAM *ERROR-OUTPUT*) (EXIT-FUNCTION #'EXIT) (EXIT-CODE 1)
(PREFIX error: ))
-</pre></div>
-
-
+</code></pre>
<p>Print <code>prefix</code> and <code>error</code> to <code>stream</code> and exit.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(handler-case
+<pre><code>(handler-case
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options))
(unrecognized-option (c)
(print-error-and-exit c)))
-</pre></div>
-
-
+</code></pre>
<h3 id="print-help-function"><code>PRINT-HELP</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PRINT-HELP INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV))) (WIDTH 80)
+<pre><code>(PRINT-HELP INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV))) (WIDTH 80)
(OPTION-WIDTH 20) (INCLUDE-EXAMPLES T))
-</pre></div>
-
-
+</code></pre>
<p>Print a pretty help document for <code>interface</code> to <code>stream</code>.</p>
<p><code>width</code> should be the total width (in characters) for line-wrapping purposes.
Care will be taken to ensure lines are no longer than this, though some edge
@@ -323,7 +281,7 @@
help string will start on the same line. Otherwise the option's help string
will start on the next line.</p>
<p>The result will look something like:</p>
-<div class="codehilite"><pre><span/>(print-help *program-interface* :width 60 :option-width 15)
+<pre><code>(print-help *program-interface* :width 60 :option-width 15)
; =>
; foo - do some things and meow
;
@@ -343,66 +301,48 @@
; -m, --meow Meow.
; 0.........1.... option-width
; 0........1.........2.........3.........4.........5.........6
-</pre></div>
-
-
+</code></pre>
<h3 id="print-help-and-exit-function"><code>PRINT-HELP-AND-EXIT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PRINT-HELP-AND-EXIT INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV)))
+<pre><code>(PRINT-HELP-AND-EXIT INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV)))
(WIDTH 80) (OPTION-WIDTH 20) (INCLUDE-EXAMPLES T) (EXIT-FUNCTION #'EXIT)
(EXIT-CODE 0))
-</pre></div>
-
-
+</code></pre>
<p>Print a pretty help document for <code>interface</code> to <code>stream</code> and exit.</p>
<p>Handy for easily providing --help:</p>
-<div class="codehilite"><pre><span/>(multiple-value-bind (arguments options) (parse-options *ui*)
+<pre><code>(multiple-value-bind (arguments options) (parse-options *ui*)
(when (gethash 'help options)
(print-help-and-exit *ui*))
(run arguments options))
-</pre></div>
-
-
+</code></pre>
<h3 id="print-manual-function"><code>PRINT-MANUAL</code> (function)</h3>
-<div class="codehilite"><pre><span/>(PRINT-MANUAL INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (MANUAL-SECTION 1))
-</pre></div>
-
-
+<pre><code>(PRINT-MANUAL INTERFACE &KEY (STREAM *STANDARD-OUTPUT*) (MANUAL-SECTION 1))
+</code></pre>
<p>Print a troff-formatted man page for <code>interface</code> to <code>stream</code>.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(with-open-file (manual "man/man1/foo.1"
+<pre><code>(with-open-file (manual "man/man1/foo.1"
:direction :output
:if-exists :supersede)
(print-manual *ui* manual))
-</pre></div>
-
-
+</code></pre>
<h3 id="supply-new-value-function"><code>SUPPLY-NEW-VALUE</code> (function)</h3>
-<div class="codehilite"><pre><span/>(SUPPLY-NEW-VALUE CONDITION VALUE)
-</pre></div>
-
-
+<pre><code>(SUPPLY-NEW-VALUE CONDITION VALUE)
+</code></pre>
<p>Invoke the <code>supply-new-value</code> restart properly.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(handler-bind
+<pre><code>(handler-bind
((unrecognized-option (alexandria:rcurry 'supply-new-value "--foo"))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
-</pre></div>
-
-
+</code></pre>
<h3 id="treat-as-argument-function"><code>TREAT-AS-ARGUMENT</code> (function)</h3>
-<div class="codehilite"><pre><span/>(TREAT-AS-ARGUMENT CONDITION)
-</pre></div>
-
-
+<pre><code>(TREAT-AS-ARGUMENT CONDITION)
+</code></pre>
<p>Invoke the <code>treat-as-argument</code> restart properly.</p>
<p>Example:</p>
-<div class="codehilite"><pre><span/>(handler-bind ((unrecognized-option 'treat-as-argument))
+<pre><code>(handler-bind ((unrecognized-option 'treat-as-argument))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
-</pre></div>
-
-
+</code></pre>
<h3 id="unrecognized-option-class"><code>UNRECOGNIZED-OPTION</code> (class)</h3>
<h4 id="slot-problematic-option">Slot <code>PROBLEMATIC-OPTION</code></h4>
<ul>
@@ -411,8 +351,7 @@
<li>Accessor: <code>PROBLEMATIC-OPTION</code></li>
</ul>
</div>
- <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a>.</i></p>
-<p><a href="http://rochestermade.com" title="Rochester Made"><img src="https://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
+ <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a>.</i></p></footer>
</div>
</body>
</html>
\ No newline at end of file
--- a/adopt/usage/index.html Wed Jun 21 15:21:12 2023 -0400
+++ b/adopt/usage/index.html Thu Jun 13 13:05:28 2024 -0400
@@ -1,10 +1,10 @@
<!DOCTYPE html>
<html>
<head>
- <meta charset="utf-8"/>
+ <meta charset="utf-8">
<title>Usage / Adopt</title>
- <link rel="stylesheet" href="../_dmedia/tango.css"/>
- <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
+ <link rel="stylesheet" href="../_dmedia/tango.css">
+ <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less">
<script src="../_dmedia/less.js" type="text/javascript">
</script>
</head>
@@ -12,7 +12,8 @@
<div class="wrap">
<header><h1><a href="..">Adopt</a></h1></header>
<div class="markdown">
-<h1 id="usage"><a href="">Usage</a></h1><p>Adopt is a library for parsing UNIX-style command line arguments in Common Lisp.
+<h1 id="usage"><a href="">Usage</a></h1>
+<p>Adopt is a library for parsing UNIX-style command line arguments in Common Lisp.
It was made because none of the other libraries did what I needed.</p>
<div class="toc">
<ul>
@@ -45,7 +46,8 @@
<li><a href="#clozurecl">ClozureCL</a></li>
</ul>
</li>
-</ul></div>
+</ul>
+</div>
<h2 id="package">Package</h2>
<p>All core Adopt functions are in the <code>adopt</code> package. Several of the symbols in
adopt shadow those in the <code>common-lisp</code> package, so you should probably use
@@ -58,15 +60,14 @@
<p>Let's say you're developing a program to search the contents of files (because
the world certainly needs <em>another</em> <code>grep</code> replacement). You might start with
something like:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="s">"Search the contents of each FILE for the regular expression PATTERN. If no files are specified, searches standard input instead."</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help "Search the contents of each FILE for the regular expression PATTERN. If no files are specified, searches standard input instead."))
+</code></pre>
<p><code>make-interface</code> takes several required arguments:</p>
<ul>
<li><code>:name</code> is the name of the program.</li>
@@ -76,17 +77,16 @@
<li><code>:help</code> is a longer description of the program.</li>
</ul>
<p>You can now print some pretty help text for the CLI with <code>adopt:print-help</code>:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:print-help</span> <span class="vg">*ui*</span><span class="p">)</span>
-<span class="c1">; =></span>
-<span class="c1">; search - search files for a regular expression</span>
-<span class="c1">;</span>
-<span class="c1">; USAGE: /path/to/binary [OPTIONS] PATTERN [FILE]...</span>
-<span class="c1">;</span>
-<span class="c1">; Search the contents of each FILE for the regular expression PATTERN. If no</span>
-<span class="c1">; files are specified, searches standard input instead.</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:print-help *ui*)
+; =>
+; search - search files for a regular expression
+;
+; USAGE: /path/to/binary [OPTIONS] PATTERN [FILE]...
+;
+; Search the contents of each FILE for the regular expression PATTERN. If no
+; files are specified, searches standard input instead.
+</code></pre>
<h3 id="line-wrapping">Line Wrapping</h3>
<p>Adopt will handle line-wrapping your help text, so you don't need to (and
shouldn't) add extra line breaks when creating your interface.</p>
@@ -94,138 +94,132 @@
text editor, remember that <code>adopt:make-interface</code> is just a function — you can
use <code>format</code> (possibly with its <a href="http://www.lispworks.com/documentation/lw71/CLHS/Body/22_cic.htm"><code>~Newline</code> directive</a>) to
preprocess the help text argument:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="p">(</span><span class="nb">format</span> <span class="no">nil</span> <span class="s">"Search the contents of each FILE for ~</span>
-<span class="s"> the regular expression PATTERN. If ~</span>
-<span class="s"> no files are specified, searches ~</span>
-<span class="s"> standard input instead."</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help (format nil "Search the contents of each FILE for ~
+ the regular expression PATTERN. If ~
+ no files are specified, searches ~
+ standard input instead.")))
+</code></pre>
<p>If you want to pull out the documentation string into its own variable to keep
that <code>make-interface</code> call from getting too unwieldy, you can certainly do that:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*help-text*</span>
- <span class="p">(</span><span class="nb">format</span> <span class="no">nil</span> <span class="s">"Search the contents of each FILE for the ~</span>
-<span class="s"> regular expression PATTERN. If no files ~</span>
-<span class="s"> are specified, searches standard input ~</span>
-<span class="s"> instead."</span><span class="p">))</span>
+<pre><code>:::lisp
+(defparameter *help-text*
+ (format nil "Search the contents of each FILE for the ~
+ regular expression PATTERN. If no files ~
+ are specified, searches standard input ~
+ instead."))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="vg">*help-text*</span><span class="p">))</span>
-</pre></div>
-
-
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help *help-text*))
+</code></pre>
<p>The <code>(defparameter … (format nil …))</code> pattern can be tedious to write, so Adopt
provides a helper macro <code>define-string</code> that does exactly that:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:define-string</span> <span class="vg">*help-text*</span>
- <span class="s">"Search the contents of each FILE for the regular ~</span>
-<span class="s"> expression PATTERN. If no files are specified, ~</span>
-<span class="s"> searches standard input instead."</span><span class="p">)</span>
+<pre><code>:::lisp
+(adopt:define-string *help-text*
+ "Search the contents of each FILE for the regular ~
+ expression PATTERN. If no files are specified, ~
+ searches standard input instead.")
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="vg">*help-text*</span><span class="p">))</span>
-</pre></div>
-
-
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help *help-text*))
+</code></pre>
<p>Adopt's line-wrapping library <a href="https://docs.stevelosh.com/bobbin/">Bobbin</a> will only ever <em>add</em> line breaks, never
remove them, which means you can include breaks in the output if you want to
have multiple paragraphs in your help text. Once again, <code>format</code> is your
friend:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:define-string</span> <span class="vg">*help-text*</span>
- <span class="s">"Search the contents of each FILE for the regular ~</span>
-<span class="s"> expression PATTERN.~@</span>
-<span class="s"> ~@</span>
-<span class="s"> If no files are specified (or if - is given as a ~</span>
-<span class="s"> file name), standard input will be searched instead."</span><span class="p">)</span>
+<pre><code>:::lisp
+(adopt:define-string *help-text*
+ "Search the contents of each FILE for the regular ~
+ expression PATTERN.~@
+ ~@
+ If no files are specified (or if - is given as a ~
+ file name), standard input will be searched instead.")
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="vg">*help-text*</span><span class="p">))</span>
-</pre></div>
-
-
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help *help-text*))
+</code></pre>
<p>If you want to control the width of the help text lines when they are printed,
<code>adopt:print-help</code> takes a <code>:width</code> argument:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:print-help</span> <span class="vg">*ui*</span> <span class="ss">:width</span> <span class="mi">50</span><span class="p">)</span>
-<span class="c1">; =></span>
-<span class="c1">; search - search files for a regular expression</span>
-<span class="c1">;</span>
-<span class="c1">; USAGE: … [OPTIONS] PATTERN [FILE]...</span>
-<span class="c1">;</span>
-<span class="c1">; Search the contents of each FILE for the regular</span>
-<span class="c1">; expression PATTERN.</span>
-<span class="c1">;</span>
-<span class="c1">; If no files are specified (or if - is given as a</span>
-<span class="c1">; file name), standard input will be searched</span>
-<span class="c1">; instead.</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:print-help *ui* :width 50)
+; =>
+; search - search files for a regular expression
+;
+; USAGE: … [OPTIONS] PATTERN [FILE]...
+;
+; Search the contents of each FILE for the regular
+; expression PATTERN.
+;
+; If no files are specified (or if - is given as a
+; file name), standard input will be searched
+; instead.
+</code></pre>
<p><code>adopt:print-help</code> takes a number of other options — see the API Reference for
more information.</p>
<h3 id="adding-examples">Adding Examples</h3>
<p>Describing the CLI in detail is helpful, but users can often learn a lot more by
seeing a few examples of its usage. <code>make-interface</code> can take an <code>:examples</code>
argument, which should be an alist of <code>(description . example)</code> conses:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="vg">*help-text*</span>
- <span class="ss">:examples</span>
- <span class="o">'</span><span class="p">((</span><span class="s">"Search foo.txt for the string 'hello':"</span>
- <span class="o">.</span> <span class="s">"search hello foo.txt"</span><span class="p">)</span>
- <span class="p">(</span><span class="s">"Search standard input for lines starting with x:"</span>
- <span class="o">.</span> <span class="s">"search '^x' -"</span><span class="p">)</span>
- <span class="p">(</span><span class="s">"Watch the file log.txt for lines containing the username steve.losh:"</span>
- <span class="o">.</span> <span class="s">"tail foo/bar/baz/log.txt | search --literal steve.losh -"</span><span class="p">))))</span>
+<pre><code>:::lisp
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help *help-text*
+ :examples
+ '(("Search foo.txt for the string 'hello':"
+ . "search hello foo.txt")
+ ("Search standard input for lines starting with x:"
+ . "search '^x' -")
+ ("Watch the file log.txt for lines containing the username steve.losh:"
+ . "tail foo/bar/baz/log.txt | search --literal steve.losh -"))))
-<span class="p">(</span><span class="nv">adopt:print-help</span> <span class="vg">*ui*</span> <span class="ss">:width</span> <span class="mi">50</span><span class="p">)</span>
-<span class="c1">; =></span>
-<span class="c1">; search - search files for a regular expression</span>
-<span class="c1">;</span>
-<span class="c1">; USAGE: … [OPTIONS] PATTERN [FILE]...</span>
-<span class="c1">;</span>
-<span class="c1">; Search the contents of each FILE for the regular</span>
-<span class="c1">; expression PATTERN.</span>
-<span class="c1">;</span>
-<span class="c1">; If no files are specified (or if - is given as a</span>
-<span class="c1">; file name) standard input will be searched</span>
-<span class="c1">; instead.</span>
-<span class="c1">;</span>
-<span class="c1">; Examples:</span>
-<span class="c1">;</span>
-<span class="c1">; Search foo.txt for the string 'hello':</span>
-<span class="c1">;</span>
-<span class="c1">; search hello foo.txt</span>
-<span class="c1">;</span>
-<span class="c1">; Search standard input for lines starting with x:</span>
-<span class="c1">;</span>
-<span class="c1">; search '^x' -</span>
-<span class="c1">;</span>
-<span class="c1">; Watch the file log.txt for lines containing the</span>
-<span class="c1">; username steve.losh:</span>
-<span class="c1">;</span>
-<span class="c1">; tail foo/bar/baz/log.txt | search --literal steve.losh -</span>
-</pre></div>
-
-
+(adopt:print-help *ui* :width 50)
+; =>
+; search - search files for a regular expression
+;
+; USAGE: … [OPTIONS] PATTERN [FILE]...
+;
+; Search the contents of each FILE for the regular
+; expression PATTERN.
+;
+; If no files are specified (or if - is given as a
+; file name) standard input will be searched
+; instead.
+;
+; Examples:
+;
+; Search foo.txt for the string 'hello':
+;
+; search hello foo.txt
+;
+; Search standard input for lines starting with x:
+;
+; search '^x' -
+;
+; Watch the file log.txt for lines containing the
+; username steve.losh:
+;
+; tail foo/bar/baz/log.txt | search --literal steve.losh -
+</code></pre>
<p>Notice how Adopt line wraps the prose explaining each example, but leaves the
example itself untouched for easier copying and pasting. In general Adopt tries
to do the right thing for your users (even when that means making a little more
@@ -233,78 +227,75 @@
<h2 id="exiting">Exiting</h2>
<p>Adopt provides some helpful utility functions to exit out of your program with
a UNIX exit code. These do what you think they do:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:exit</span><span class="p">)</span>
+<pre><code>:::lisp
+(adopt:exit)
-<span class="p">(</span><span class="nv">adopt:exit</span> <span class="mi">1</span><span class="p">)</span>
+(adopt:exit 1)
-<span class="p">(</span><span class="nv">adopt:print-help-and-exit</span> <span class="vg">*ui*</span><span class="p">)</span>
+(adopt:print-help-and-exit *ui*)
-<span class="p">(</span><span class="nv">adopt:print-help-and-exit</span> <span class="vg">*ui*</span>
- <span class="ss">:stream</span> <span class="vg">*error-output*</span>
- <span class="ss">:exit-code</span> <span class="mi">1</span><span class="p">)</span>
+(adopt:print-help-and-exit *ui*
+ :stream *error-output*
+ :exit-code 1)
-<span class="p">(</span><span class="nb">handler-case</span> <span class="p">(</span><span class="nb">assert</span> <span class="p">(</span><span class="nb">=</span> <span class="mi">1</span> <span class="mi">0</span><span class="p">))</span>
- <span class="p">(</span><span class="nb">error</span> <span class="p">(</span><span class="nv">err</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-error-and-exit</span> <span class="nv">err</span><span class="p">)))</span>
-</pre></div>
-
-
+(handler-case (assert (= 1 0))
+ (error (err)
+ (adopt:print-error-and-exit err)))
+</code></pre>
<p>These functions are not implemented for every Lisp implementation. PRs are
welcome, or you can just write the implementation-specific calls in your program
yourself if you prefer.</p>
<h2 id="options">Options</h2>
<p>Now that you know how to create an interface, you can create some options to use
inside it with <code>adopt:make-option</code>:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-version*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'version</span>
- <span class="ss">:long</span> <span class="s">"version"</span>
- <span class="ss">:help</span> <span class="s">"Display version and exit."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+<pre><code>:::lisp
+(defparameter *option-version*
+ (adopt:make-option 'version
+ :long "version"
+ :help "Display version and exit."
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-help*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'help</span>
- <span class="ss">:long</span> <span class="s">"help"</span>
- <span class="ss">:short</span> <span class="sc">#\h</span>
- <span class="ss">:help</span> <span class="s">"Display help and exit."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+(defparameter *option-help*
+ (adopt:make-option 'help
+ :long "help"
+ :short #\h
+ :help "Display help and exit."
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-literal*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'literal</span>
- <span class="ss">:long</span> <span class="s">"literal"</span>
- <span class="ss">:short</span> <span class="sc">#\l</span>
- <span class="ss">:help</span> <span class="s">"Treat PATTERN as a literal string instead of a regular expression."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+(defparameter *option-literal*
+ (adopt:make-option 'literal
+ :long "literal"
+ :short #\l
+ :help "Treat PATTERN as a literal string instead of a regular expression."
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:summary</span> <span class="s">"search files for a regular expression"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS] PATTERN [FILE]..."</span>
- <span class="ss">:help</span> <span class="s">"Search the contents of …"</span>
- <span class="ss">:contents</span> <span class="p">(</span><span class="nb">list</span>
- <span class="vg">*option-version*</span>
- <span class="vg">*option-help*</span>
- <span class="vg">*option-literal*</span><span class="p">)))</span>
-</pre></div>
-
-
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :summary "search files for a regular expression"
+ :usage "[OPTIONS] PATTERN [FILE]..."
+ :help "Search the contents of …"
+ :contents (list
+ *option-version*
+ *option-help*
+ *option-literal*)))
+</code></pre>
<p>Adopt will automatically add the options to the help text:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:print-help</span> <span class="vg">*ui*</span><span class="p">)</span>
-<span class="c1">; =></span>
-<span class="c1">; search - search files for a regular expression</span>
-<span class="c1">;</span>
-<span class="c1">; USAGE: /usr/local/bin/sbcl [OPTIONS] PATTERN [FILE]...</span>
-<span class="c1">;</span>
-<span class="c1">; Search the contents of …</span>
-<span class="c1">;</span>
-<span class="c1">; Options:</span>
-<span class="c1">; --version Display version and exit.</span>
-<span class="c1">; -h, --help Display help and exit.</span>
-<span class="c1">; -l, --literal Treat PATTERN as a literal string instead of a regular</span>
-<span class="c1">; expression.</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:print-help *ui*)
+; =>
+; search - search files for a regular expression
+;
+; USAGE: /usr/local/bin/sbcl [OPTIONS] PATTERN [FILE]...
+;
+; Search the contents of …
+;
+; Options:
+; --version Display version and exit.
+; -h, --help Display help and exit.
+; -l, --literal Treat PATTERN as a literal string instead of a regular
+; expression.
+</code></pre>
<p>The first argument to <code>make-option</code> is the name of the option, which we'll see
put to use shortly. At least one of <code>:short</code> and <code>:long</code> is required, and
<code>:help</code> text must be specified. We'll talk more about <code>:reduce</code> in a little
@@ -316,36 +307,33 @@
<p>I prefer to define each option as its own global variable to keep the call to
<code>make-interface</code> from getting too large and unwieldy, but feel free to do
something like this if you prefer to avoid cluttering your package:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="err">…</span>
- <span class="ss">:contents</span>
- <span class="p">(</span><span class="nb">list</span> <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'foo</span> <span class="err">…</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'bar</span> <span class="err">…</span><span class="p">)</span>
- <span class="err">…</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *ui*
+ (adopt:make-interface
+ …
+ :contents
+ (list (adopt:make-option 'foo …)
+ (adopt:make-option 'bar …)
+ …)))
+</code></pre>
<h2 id="parsing">Parsing</h2>
<p>At this point we've got an interface with some options, so we can use it to
parse a list of strings we've received as command line arguments with
<code>adopt:parse-options</code>:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"foo.*"</span> <span class="s">"--literal"</span> <span class="s">"a.txt"</span> <span class="s">"b.txt"</span><span class="p">))</span>
-<span class="c1">; =></span>
-<span class="c1">; ("foo.*" "a.txt" "b.txt")</span>
-<span class="c1">; #<HASH-TABLE :TEST EQL :COUNT 3 {10103142A3}></span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
+; =>
+; ("foo.*" "a.txt" "b.txt")
+; #<HASH-TABLE :TEST EQL :COUNT 3 {10103142A3}>
+</code></pre>
<p>From now on I'll use a special pretty printer for hash tables to make it easier
to see what's inside them:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"foo.*"</span> <span class="s">"--literal"</span> <span class="s">"a.txt"</span> <span class="s">"b.txt"</span><span class="p">))</span>
-<span class="c1">; =></span>
-<span class="c1">; ("foo.*" "a.txt" "b.txt")</span>
-<span class="c1">; {LITERAL: T, VERSION: NIL, HELP: NIL}</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
+; =>
+; ("foo.*" "a.txt" "b.txt")
+; {LITERAL: T, VERSION: NIL, HELP: NIL}
+</code></pre>
<p><code>parse-options</code> returns two values:</p>
<ol>
<li>A list of non-option arguments.</li>
@@ -355,23 +343,22 @@
hash table are (by default) the option names given as the first argument to
<code>make-option</code>. You can specify a different key for a particular option with the
<code>:result-key</code> argument to <code>make-option</code>:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-literal*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'literal</span>
- <span class="ss">:result-key</span> <span class="ss">'pattern-is-literal</span>
- <span class="ss">:long</span> <span class="s">"literal"</span>
- <span class="ss">:short</span> <span class="sc">#\l</span>
- <span class="ss">:help</span> <span class="s">"Treat PATTERN as a literal string instead of a regular expression."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+<pre><code>:::lisp
+(defparameter *option-literal*
+ (adopt:make-option 'literal
+ :result-key 'pattern-is-literal
+ :long "literal"
+ :short #\l
+ :help "Treat PATTERN as a literal string instead of a regular expression."
+ :reduce (constantly t)))
-<span class="c1">;; …</span>
+;; …
-<span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"foo.*"</span> <span class="s">"--literal"</span> <span class="s">"a.txt"</span> <span class="s">"b.txt"</span><span class="p">))</span>
-<span class="c1">; =></span>
-<span class="c1">; ("foo.*" "a.txt" "b.txt")</span>
-<span class="c1">; {PATTERN-IS-LITERAL: T, VERSION: NIL, HELP: NIL}</span>
-</pre></div>
-
-
+(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
+; =>
+; ("foo.*" "a.txt" "b.txt")
+; {PATTERN-IS-LITERAL: T, VERSION: NIL, HELP: NIL}
+</code></pre>
<p>This can come in useful if you want multiple options that affect the same result
(e.g. <code>--verbose</code> and <code>--silent</code> flags that toggle extra log output on and off).</p>
<h2 id="option-formats">Option Formats</h2>
@@ -388,30 +375,29 @@
<h2 id="top-level-structure">Top-Level Structure</h2>
<p>We'll look at how the option values are computed shortly, but first let's see
the overall structure of the programs you'll typically create with Adopt:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defun</span> <span class="nv">run</span> <span class="p">(</span><span class="nv">pattern</span> <span class="nv">files</span> <span class="k">&key</span> <span class="nv">literal</span><span class="p">)</span>
- <span class="c1">;; Actually do something here.</span>
- <span class="p">)</span>
+<pre><code>:::lisp
+(defun run (pattern files &key literal)
+ ;; Actually do something here.
+ )
-<span class="p">(</span><span class="nb">defun</span> <span class="nv">toplevel</span> <span class="p">()</span>
- <span class="p">(</span><span class="nb">handler-case</span>
- <span class="p">(</span><span class="nb">multiple-value-bind</span> <span class="p">(</span><span class="nv">arguments</span> <span class="nv">options</span><span class="p">)</span> <span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">when</span> <span class="p">(</span><span class="nb">gethash</span> <span class="ss">'help</span> <span class="nv">options</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-help-and-exit</span> <span class="vg">*ui*</span><span class="p">))</span>
- <span class="p">(</span><span class="nb">when</span> <span class="p">(</span><span class="nb">gethash</span> <span class="ss">'version</span> <span class="nv">options</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">format</span> <span class="no">t</span> <span class="s">"1.0.0~%"</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:exit</span><span class="p">))</span>
- <span class="p">(</span><span class="nb">destructuring-bind</span> <span class="p">(</span><span class="nv">pattern</span> <span class="o">.</span> <span class="nv">files</span><span class="p">)</span> <span class="nv">arguments</span>
- <span class="p">(</span><span class="nv">run</span> <span class="nv">pattern</span>
- <span class="nv">files</span>
- <span class="ss">:literal</span> <span class="p">(</span><span class="nb">gethash</span> <span class="ss">'literal</span> <span class="nv">options</span><span class="p">))))</span>
- <span class="p">(</span><span class="nb">error</span> <span class="p">(</span><span class="nv">c</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-error-and-exit</span> <span class="nv">c</span><span class="p">))))</span>
+(defun toplevel ()
+ (handler-case
+ (multiple-value-bind (arguments options) (adopt:parse-options *ui*)
+ (when (gethash 'help options)
+ (adopt:print-help-and-exit *ui*))
+ (when (gethash 'version options)
+ (format t "1.0.0~%")
+ (adopt:exit))
+ (destructuring-bind (pattern . files) arguments
+ (run pattern
+ files
+ :literal (gethash 'literal options))))
+ (error (c)
+ (adopt:print-error-and-exit c))))
-<span class="p">(</span><span class="nb">defun</span> <span class="nv">build</span> <span class="p">()</span>
- <span class="p">(</span><span class="nv">sb-ext:save-lisp-and-die</span> <span class="s">"search"</span> <span class="ss">:executable</span> <span class="no">t</span> <span class="ss">:toplevel</span> <span class="nf">#'</span><span class="nv">toplevel</span><span class="p">))</span>
-</pre></div>
-
-
+(defun build ()
+ (sb-ext:save-lisp-and-die "search" :executable t :toplevel #'toplevel))
+</code></pre>
<p>This is a typical way to use Adopt. There are three important functions here:</p>
<ul>
<li>The <code>toplevel</code> function takes care of parsing arguments and exiting with an
@@ -474,80 +460,74 @@
<h3 id="simple-options">Simple Options</h3>
<p>To define an option that just tracks whether it's ever been given, you can do
something like:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-help*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'help</span>
- <span class="ss">:long</span> <span class="s">"help"</span>
- <span class="ss">:short</span> <span class="sc">#\h</span>
- <span class="ss">:help</span> <span class="s">"Display help and exit."</span>
- <span class="ss">:initial-value</span> <span class="no">nil</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nv">current-value</span><span class="p">)</span>
- <span class="p">(</span><span class="k">declare</span> <span class="p">(</span><span class="k">ignore</span> <span class="nv">current-value</span><span class="p">))</span>
- <span class="no">t</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-help*
+ (adopt:make-option 'help
+ :long "help"
+ :short #\h
+ :help "Display help and exit."
+ :initial-value nil
+ :reduce (lambda (current-value)
+ (declare (ignore current-value))
+ t)))
+</code></pre>
<p>But since <code>nil</code> is the default initial value and Common Lisp provides the handy
<a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_cons_1.htm"><code>constantly</code></a>
function, you can do this more concisely:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-help*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'help</span>
- <span class="ss">:long</span> <span class="s">"help"</span>
- <span class="ss">:short</span> <span class="sc">#\h</span>
- <span class="ss">:help</span> <span class="s">"Display help and exit."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-help*
+ (adopt:make-option 'help
+ :long "help"
+ :short #\h
+ :help "Display help and exit."
+ :reduce (constantly t)))
+</code></pre>
<h3 id="boolean-options">Boolean Options</h3>
<p>If you want to have multiple options that both affect the same key in the
results, you can use <code>:result-key</code> to do this:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-paginate*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'paginate</span>
- <span class="ss">:long</span> <span class="s">"paginate"</span>
- <span class="ss">:short</span> <span class="sc">#\p</span>
- <span class="ss">:help</span> <span class="s">"Turn pagination on."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+<pre><code>:::lisp
+(defparameter *option-paginate*
+ (adopt:make-option 'paginate
+ :long "paginate"
+ :short #\p
+ :help "Turn pagination on."
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-no-paginate*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'no-paginate</span>
- <span class="ss">:result-key</span> <span class="ss">'paginate</span>
- <span class="ss">:long</span> <span class="s">"no-paginate"</span>
- <span class="ss">:short</span> <span class="sc">#\P</span>
- <span class="ss">:help</span> <span class="s">"Turn pagination off (the default)."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">nil</span><span class="p">)))</span>
-</pre></div>
-
-
+(defparameter *option-no-paginate*
+ (adopt:make-option 'no-paginate
+ :result-key 'paginate
+ :long "no-paginate"
+ :short #\P
+ :help "Turn pagination off (the default)."
+ :reduce (constantly nil)))
+</code></pre>
<p>The way we've written this, if the user gives multiple options the last-given
one will take precedence. This is generally what you want, because it allows
someone to add a shell alias with these options like this:</p>
-<div class="codehilite"><pre><span/><span class="nb">alias</span> <span class="nv">g</span><span class="o">=</span><span class="s1">'git --paginate --color=always'</span>
-</pre></div>
-
-
+<pre><code>:::bash
+alias g='git --paginate --color=always'
+</code></pre>
<p>but still lets them override an option at runtime for a single invocation:</p>
-<div class="codehilite"><pre><span/>g --no-paginate log
-<span class="c1"># expands to: git --paginate --color=always --no-paginate log</span>
-</pre></div>
-
-
+<pre><code>:::bash
+g --no-paginate log
+# expands to: git --paginate --color=always --no-paginate log
+</code></pre>
<p>If the last-given option didn't take precedence, they'd have to fall back to the
non-alias version of the command, and type out all the options they <em>do</em> want by
hand. This is annoying, so it's usually better to let the last one win.</p>
<p>Making two separate options by hand can be tedious if you have a lot of boolean
options, so Adopt provides a <code>make-boolean-options</code> function that will do some
of the boilerplate for you:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:make-boolean-options</span> <span class="ss">'paginate</span>
- <span class="ss">:long</span> <span class="s">"paginate"</span>
- <span class="ss">:short</span> <span class="sc">#\p</span>
- <span class="ss">:help</span> <span class="s">"Turn pagination on."</span>
- <span class="ss">:help-no</span> <span class="s">"Turn pagination off (the default)."</span><span class="p">)</span>
-<span class="c1">;; =></span>
-<span class="err">#</span><span class="nv"><ADOPT::OPTION</span> <span class="nv">PAGINATE</span> <span class="nv">p/paginate></span>
-<span class="err">#</span><span class="nv"><ADOPT::OPTION</span> <span class="nv">NO-PAGINATE</span> <span class="nv">P/no-paginate></span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:make-boolean-options 'paginate
+ :long "paginate"
+ :short #\p
+ :help "Turn pagination on."
+ :help-no "Turn pagination off (the default).")
+;; =>
+#<ADOPT::OPTION PAGINATE p/paginate>
+#<ADOPT::OPTION NO-PAGINATE P/no-paginate>
+</code></pre>
<p><code>make-boolean-options</code> will try to guess at sensible values to reduce the
boilerplate you need to type:</p>
<ul>
@@ -563,130 +543,121 @@
<p>The two options are returned as separate <code>values</code>. Adopt also provides
a <code>defparameters</code> convenience macro to create special variables for them more
easily:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">defparameters</span> <span class="p">(</span><span class="vg">*option-paginate*</span> <span class="vg">*option-no-paginate*</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:make-boolean-options</span> <span class="ss">'paginate</span>
- <span class="ss">:long</span> <span class="s">"paginate"</span>
- <span class="ss">:short</span> <span class="sc">#\p</span>
- <span class="ss">:help</span> <span class="s">"Turn pagination on."</span>
- <span class="ss">:help-no</span> <span class="s">"Turn pagination off (the default)."</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameters (*option-paginate* *option-no-paginate*)
+ (adopt:make-boolean-options 'paginate
+ :long "paginate"
+ :short #\p
+ :help "Turn pagination on."
+ :help-no "Turn pagination off (the default)."))
+</code></pre>
<h3 id="counting-options">Counting Options</h3>
<p>To define an option that counts how many times it's been given, like SSH's <code>-v</code>,
you can use something like this:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-verbosity*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'verbosity</span>
- <span class="ss">:short</span> <span class="sc">#\v</span>
- <span class="ss">:help</span> <span class="s">"Output more verbose logs."</span>
- <span class="ss">:initial-value</span> <span class="mi">0</span>
- <span class="ss">:reduce</span> <span class="nf">#'</span><span class="nb">1+</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-verbosity*
+ (adopt:make-option 'verbosity
+ :short #\v
+ :help "Output more verbose logs."
+ :initial-value 0
+ :reduce #'1+))
+</code></pre>
<h3 id="single-parameter-options">Single-Parameter Options</h3>
<p>To define an option that takes a parameter and only keeps the last one given,
you can do something like:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-repository*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'repository</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:long</span> <span class="s">"repository"</span>
- <span class="ss">:short</span> <span class="sc">#\R</span>
- <span class="ss">:help</span> <span class="s">"Path to the repository (default .)."</span>
- <span class="ss">:initial-value</span> <span class="s">"."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nv">prev</span> <span class="nv">new</span><span class="p">)</span>
- <span class="p">(</span><span class="k">declare</span> <span class="p">(</span><span class="k">ignore</span> <span class="nv">prev</span><span class="p">))</span>
- <span class="nv">new</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-repository*
+ (adopt:make-option 'repository
+ :parameter "PATTERN"
+ :long "repository"
+ :short #\R
+ :help "Path to the repository (default .)."
+ :initial-value "."
+ :reduce (lambda (prev new)
+ (declare (ignore prev))
+ new)))
+</code></pre>
<p>Specifying the <code>:parameter</code> argument makes this option a parameter-taking
option, which means the <code>:reduce</code> function will be called with the current value
and the given parameter each time.</p>
<p>Writing that <code>lambda</code> out by hand every time would be tedious. Adopt provides
a function called <code>last</code> (as in "keep the <em>last</em> parameter given") that does
exactly that:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-repository*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'repository</span>
- <span class="ss">:long</span> <span class="s">"repository"</span>
- <span class="ss">:short</span> <span class="sc">#\R</span>
- <span class="ss">:help</span> <span class="s">"Path to the repository (default .)."</span>
- <span class="ss">:initial-value</span> <span class="s">"."</span>
- <span class="ss">:reduce</span> <span class="nf">#'</span><span class="nv">adopt:last</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-repository*
+ (adopt:make-option 'repository
+ :long "repository"
+ :short #\R
+ :help "Path to the repository (default .)."
+ :initial-value "."
+ :reduce #'adopt:last))
+</code></pre>
<h3 id="multiple-parameter-options">Multiple-Parameter Options</h3>
<p>Collecting every parameter given can be done in a number of different ways. One
strategy could be:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN (may be given multiple times)."</span>
- <span class="ss">:initial-value</span> <span class="no">nil</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nv">patterns</span> <span class="nv">new</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">cons</span> <span class="nv">new</span> <span class="nv">patterns</span><span class="p">))))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN (may be given multiple times)."
+ :initial-value nil
+ :reduce (lambda (patterns new)
+ (cons new patterns))))
+</code></pre>
<p>You might notice that the <code>:reduce</code> function here is just <code>cons</code> with its
arguments flipped. Common Lisp doesn't have a function like Haskell's
<a href="https://en.wikibooks.org/wiki/Haskell/Higher-order_functions#Flipping_arguments">flip</a>,
so Adopt provides it:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN (may be given multiple times)."</span>
- <span class="ss">:initial-value</span> <span class="no">nil</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nv">adopt:flip</span> <span class="nf">#'</span><span class="nb">cons</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN (may be given multiple times)."
+ :initial-value nil
+ :reduce (adopt:flip #'cons)))
+</code></pre>
<p>Note that the result of this will be a fresh list of all the given parameters,
but their order will be reversed because <code>cons</code> adds each new parameter to the
front of the list. If the order doesn't matter for what you're going to do with
it, you're all set. Otherwise, there are several ways to get around this
problem. The first is to add the parameter to the end of the list in the
<code>:reduce</code> function:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN (may be given multiple times)."</span>
- <span class="ss">:initial-value</span> <span class="no">nil</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nv">patterns</span> <span class="nv">new</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">append</span> <span class="nv">patterns</span> <span class="p">(</span><span class="nb">list</span> <span class="nv">new</span><span class="p">)))))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN (may be given multiple times)."
+ :initial-value nil
+ :reduce (lambda (patterns new)
+ (append patterns (list new)))))
+</code></pre>
<p>This is tedious and inefficient if you have a lot of arguments. If you don't
care much about argument parsing speed, Adopt provides a function called
<code>collect</code> that does exactly this, so you don't have to type out that <code>lambda</code>
yourself (and <code>nil</code> is the default initial value, so you don't need that
either):</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN (may be given multiple times)."</span>
- <span class="ss">:reduce</span> <span class="nf">#'</span><span class="nv">adopt:collect</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN (may be given multiple times)."
+ :reduce #'adopt:collect))
+</code></pre>
<p>A more efficient (though slightly uglier) solution would be to use <code>nreverse</code> at
the end:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN (may be given multiple times)."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nv">adopt:flip</span> <span class="nf">#'</span><span class="nb">cons</span><span class="p">)</span>
- <span class="ss">:finally</span> <span class="nf">#'</span><span class="nb">nreverse</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN (may be given multiple times)."
+ :reduce (adopt:flip #'cons)
+ :finally #'nreverse))
+</code></pre>
<p>If you really need maximum efficiency when parsing command line options (you
probably don't) you could use a queue library, or use a vector and
<code>vector-push-extend</code>, or anything else you might dream up. The combination of
@@ -697,252 +668,245 @@
<code>foo --help</code> they shouldn't get an error about a missing required option.</p>
<p>In cases where you really do need to require an option (perhaps only if some
other one is also given) you can check it yourself:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defun</span> <span class="nv">toplevel</span> <span class="p">()</span>
- <span class="p">(</span><span class="nb">handler-case</span>
- <span class="p">(</span><span class="nb">multiple-value-bind</span> <span class="p">(</span><span class="nv">arguments</span> <span class="nv">options</span><span class="p">)</span> <span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">when</span> <span class="p">(</span><span class="nb">gethash</span> <span class="ss">'help</span> <span class="nv">options</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-help-and-exit</span> <span class="vg">*ui*</span><span class="p">))</span>
- <span class="p">(</span><span class="nb">unless</span> <span class="p">(</span><span class="nb">gethash</span> <span class="ss">'some-required-option</span> <span class="nv">options</span><span class="p">)</span>
- <span class="p">(</span><span class="nb">error</span> <span class="s">"Required option foo is missing."</span><span class="p">))</span>
- <span class="p">(</span><span class="nv">run</span> <span class="err">…</span><span class="p">))</span>
- <span class="p">(</span><span class="nb">error</span> <span class="p">(</span><span class="nv">c</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-error-and-exit</span> <span class="nv">c</span><span class="p">))))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defun toplevel ()
+ (handler-case
+ (multiple-value-bind (arguments options) (adopt:parse-options *ui*)
+ (when (gethash 'help options)
+ (adopt:print-help-and-exit *ui*))
+ (unless (gethash 'some-required-option options)
+ (error "Required option foo is missing."))
+ (run …))
+ (error (c)
+ (adopt:print-error-and-exit c))))
+</code></pre>
<h2 id="option-groups">Option Groups</h2>
<p>Related options can be grouped together in the help text to make them easier for
users to understand. Groups can have their own name, title, and help text.</p>
<p>Here's a example of how this works. It's fairly long, but shows how Adopt can
help you make a command line interface with all the fixins:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-help*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'help</span>
- <span class="ss">:help</span> <span class="s">"Display help and exit."</span>
- <span class="ss">:long</span> <span class="s">"help"</span>
- <span class="ss">:short</span> <span class="sc">#\h</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+<pre><code>:::lisp
+(defparameter *option-help*
+ (adopt:make-option 'help
+ :help "Display help and exit."
+ :long "help"
+ :short #\h
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-literal*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'literal</span>
- <span class="ss">:help</span> <span class="s">"Treat PATTERN as a literal string instead of a regex."</span>
- <span class="ss">:long</span> <span class="s">"literal"</span>
- <span class="ss">:short</span> <span class="sc">#\l</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+(defparameter *option-literal*
+ (adopt:make-option 'literal
+ :help "Treat PATTERN as a literal string instead of a regex."
+ :long "literal"
+ :short #\l
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-no-literal*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'no-literal</span>
- <span class="ss">:result-key</span> <span class="ss">'literal</span>
- <span class="ss">:help</span> <span class="s">"Treat PATTERN as a regex (the default)."</span>
- <span class="ss">:long</span> <span class="s">"no-literal"</span>
- <span class="ss">:short</span> <span class="sc">#\L</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">nil</span><span class="p">)))</span>
+(defparameter *option-no-literal*
+ (adopt:make-option 'no-literal
+ :result-key 'literal
+ :help "Treat PATTERN as a regex (the default)."
+ :long "no-literal"
+ :short #\L
+ :reduce (constantly nil)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-case-sensitive*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'case-sensitive</span>
- <span class="ss">:help</span> <span class="s">"Match case-sensitively (the default)."</span>
- <span class="ss">:long</span> <span class="s">"case-sensitive"</span>
- <span class="ss">:short</span> <span class="sc">#\c</span>
- <span class="ss">:initial-value</span> <span class="no">t</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+(defparameter *option-case-sensitive*
+ (adopt:make-option 'case-sensitive
+ :help "Match case-sensitively (the default)."
+ :long "case-sensitive"
+ :short #\c
+ :initial-value t
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-case-insensitive*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'case-insensitive</span>
- <span class="ss">:help</span> <span class="s">"Ignore case when matching."</span>
- <span class="ss">:long</span> <span class="s">"case-insensitive"</span>
- <span class="ss">:short</span> <span class="sc">#\C</span>
- <span class="ss">:result-key</span> <span class="ss">'case-sensitive</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">nil</span><span class="p">)))</span>
+(defparameter *option-case-insensitive*
+ (adopt:make-option 'case-insensitive
+ :help "Ignore case when matching."
+ :long "case-insensitive"
+ :short #\C
+ :result-key 'case-sensitive
+ :reduce (constantly nil)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-color*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'color</span>
- <span class="ss">:help</span> <span class="s">"Highlight matches with color."</span>
- <span class="ss">:long</span> <span class="s">"color"</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">t</span><span class="p">)))</span>
+(defparameter *option-color*
+ (adopt:make-option 'color
+ :help "Highlight matches with color."
+ :long "color"
+ :reduce (constantly t)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-no-color*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'no-color</span>
- <span class="ss">:help</span> <span class="s">"Don't highlight matches (the default)."</span>
- <span class="ss">:long</span> <span class="s">"no-color"</span>
- <span class="ss">:result-key</span> <span class="ss">'color</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nb">constantly</span> <span class="no">nil</span><span class="p">)))</span>
+(defparameter *option-no-color*
+ (adopt:make-option 'no-color
+ :help "Don't highlight matches (the default)."
+ :long "no-color"
+ :result-key 'color
+ :reduce (constantly nil)))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-context*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'context</span>
- <span class="ss">:parameter</span> <span class="s">"N"</span>
- <span class="ss">:help</span> <span class="s">"Show N lines of context (default 0)."</span>
- <span class="ss">:long</span> <span class="s">"context"</span>
- <span class="ss">:short</span> <span class="sc">#\U</span>
- <span class="ss">:initial-value</span> <span class="mi">0</span>
- <span class="ss">:reduce</span> <span class="nf">#'</span><span class="nv">adopt:last</span>
- <span class="ss">:key</span> <span class="nf">#'</span><span class="nb">parse-integer</span><span class="p">))</span>
+(defparameter *option-context*
+ (adopt:make-option 'context
+ :parameter "N"
+ :help "Show N lines of context (default 0)."
+ :long "context"
+ :short #\U
+ :initial-value 0
+ :reduce #'adopt:last
+ :key #'parse-integer))
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*group-matching*</span>
- <span class="p">(</span><span class="nv">adopt:make-group</span> <span class="ss">'matching-options</span>
- <span class="ss">:title</span> <span class="s">"Matching Options"</span>
- <span class="ss">:options</span> <span class="p">(</span><span class="nb">list</span> <span class="vg">*option-literal*</span>
- <span class="vg">*option-no-literal*</span>
- <span class="vg">*option-case-sensitive*</span>
- <span class="vg">*option-case-insensitive*</span><span class="p">)))</span>
-
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*group-output*</span>
- <span class="p">(</span><span class="nv">adopt:make-group</span> <span class="ss">'output-options</span>
- <span class="ss">:title</span> <span class="s">"Output Options"</span>
- <span class="ss">:help</span> <span class="s">"These options affect how matching lines are printed. The defaults are ideal for piping into other programs."</span>
- <span class="ss">:options</span> <span class="p">(</span><span class="nb">list</span> <span class="vg">*option-color*</span>
- <span class="vg">*option-no-color*</span>
- <span class="vg">*option-context*</span><span class="p">)))</span>
-
+(defparameter *group-matching*
+ (adopt:make-group 'matching-options
+ :title "Matching Options"
+ :options (list *option-literal*
+ *option-no-literal*
+ *option-case-sensitive*
+ *option-case-insensitive*)))
-<span class="p">(</span><span class="nv">adopt:define-string</span> <span class="vg">*help-text*</span>
- <span class="s">"Search FILEs for lines that match the regular expression ~</span>
-<span class="s"> PATTERN and print them to standard out. Several options ~</span>
-<span class="s"> are available to control how the matching lines are printed.~@</span>
-<span class="s"> ~@</span>
-<span class="s"> If no files are given (or if - is given as a filename) ~</span>
-<span class="s"> standard input will be searched."</span><span class="p">)</span>
-
-<span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"search"</span>
- <span class="ss">:usage</span> <span class="s">"PATTERN [FILE...]"</span>
- <span class="ss">:summary</span> <span class="s">"print lines that match a regular expression"</span>
- <span class="ss">:help</span> <span class="vg">*help-text*</span>
- <span class="ss">:contents</span> <span class="p">(</span><span class="nb">list</span> <span class="vg">*option-help*</span>
- <span class="vg">*group-matching*</span>
- <span class="vg">*group-output*</span><span class="p">)))</span>
-</pre></div>
+(defparameter *group-output*
+ (adopt:make-group 'output-options
+ :title "Output Options"
+ :help "These options affect how matching lines are printed. The defaults are ideal for piping into other programs."
+ :options (list *option-color*
+ *option-no-color*
+ *option-context*)))
+(adopt:define-string *help-text*
+ "Search FILEs for lines that match the regular expression ~
+ PATTERN and print them to standard out. Several options ~
+ are available to control how the matching lines are printed.~@
+ ~@
+ If no files are given (or if - is given as a filename) ~
+ standard input will be searched.")
+
+(defparameter *ui*
+ (adopt:make-interface
+ :name "search"
+ :usage "PATTERN [FILE...]"
+ :summary "print lines that match a regular expression"
+ :help *help-text*
+ :contents (list *option-help*
+ *group-matching*
+ *group-output*)))
+</code></pre>
<p>And with all that out of the way, you've got some nicely-organized help text
for your users:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">adopt:print-help</span> <span class="vg">*ui*</span> <span class="ss">:width</span> <span class="mi">60</span> <span class="ss">:option-width</span> <span class="mi">16</span><span class="p">)</span>
-<span class="c1">; =></span>
-<span class="c1">; search - print lines that match a regular expression</span>
-<span class="c1">;</span>
-<span class="c1">; USAGE: /usr/local/bin/sbcl PATTERN [FILE...]</span>
-<span class="c1">;</span>
-<span class="c1">; Search FILEs for lines that match the regular expression</span>
-<span class="c1">; PATTERN and print them to standard out. Several options are</span>
-<span class="c1">; available to control how the matching lines are printed.</span>
-<span class="c1">;</span>
-<span class="c1">; If no files are given (or if - is given as a filename)</span>
-<span class="c1">; standard input will be searched.</span>
-<span class="c1">;</span>
-<span class="c1">; Options:</span>
-<span class="c1">; -h, --help display help and exit</span>
-<span class="c1">;</span>
-<span class="c1">; Matching Options:</span>
-<span class="c1">; -l, --literal treat PATTERN as a literal string</span>
-<span class="c1">; instead of a regex</span>
-<span class="c1">; -L, --no-literal treat PATTERN as a regex (the default)</span>
-<span class="c1">; -c, --case-sensitive</span>
-<span class="c1">; match case-sensitively (the default)</span>
-<span class="c1">; -C, --case-insensitive</span>
-<span class="c1">; ignore case when matching</span>
-<span class="c1">;</span>
-<span class="c1">; Output Options:</span>
-<span class="c1">;</span>
-<span class="c1">; These options affect how matching lines are printed. The</span>
-<span class="c1">; defaults are ideal for piping into other programs.</span>
-<span class="c1">;</span>
-<span class="c1">; --color highlight matches with color</span>
-<span class="c1">; --no-color don't highlight matches (the default)</span>
-<span class="c1">; -u N, --context N show N lines of context (default 0)</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(adopt:print-help *ui* :width 60 :option-width 16)
+; =>
+; search - print lines that match a regular expression
+;
+; USAGE: /usr/local/bin/sbcl PATTERN [FILE...]
+;
+; Search FILEs for lines that match the regular expression
+; PATTERN and print them to standard out. Several options are
+; available to control how the matching lines are printed.
+;
+; If no files are given (or if - is given as a filename)
+; standard input will be searched.
+;
+; Options:
+; -h, --help display help and exit
+;
+; Matching Options:
+; -l, --literal treat PATTERN as a literal string
+; instead of a regex
+; -L, --no-literal treat PATTERN as a regex (the default)
+; -c, --case-sensitive
+; match case-sensitively (the default)
+; -C, --case-insensitive
+; ignore case when matching
+;
+; Output Options:
+;
+; These options affect how matching lines are printed. The
+; defaults are ideal for piping into other programs.
+;
+; --color highlight matches with color
+; --no-color don't highlight matches (the default)
+; -u N, --context N show N lines of context (default 0)
+</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>For the most part Adopt doesn't try to be too smart about error handling and
leaves it up to you.</p>
<p>However, when Adopt is parsing the command line options it <em>will</em> signal an
error of type <code>adopt:unrecognized-option</code> if the user passes a command line
option that wasn't defined in the interface:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*ui*</span>
- <span class="p">(</span><span class="nv">adopt:make-interface</span>
- <span class="ss">:name</span> <span class="s">"meow"</span>
- <span class="ss">:summary</span> <span class="s">"say meow"</span>
- <span class="ss">:usage</span> <span class="s">"[OPTIONS]"</span>
- <span class="ss">:help</span> <span class="s">"Say meow. Like a cat."</span>
- <span class="ss">:contents</span> <span class="p">(</span><span class="nb">list</span> <span class="p">(</span><span class="nv">make-option</span> <span class="ss">'times</span>
- <span class="ss">:parameter</span> <span class="s">"N"</span>
- <span class="ss">:long</span> <span class="s">"times"</span>
- <span class="ss">:initial-value</span> <span class="mi">1</span>
- <span class="ss">:help</span> <span class="s">"Say meow N times (default 1)."</span>
- <span class="ss">:reduce</span> <span class="nf">#'</span><span class="nv">adopt:last</span>
- <span class="ss">:key</span> <span class="nf">#'</span><span class="nb">parse-integer</span><span class="p">))))</span>
+<pre><code>:::lisp
+(defparameter *ui*
+ (adopt:make-interface
+ :name "meow"
+ :summary "say meow"
+ :usage "[OPTIONS]"
+ :help "Say meow. Like a cat."
+ :contents (list (make-option 'times
+ :parameter "N"
+ :long "times"
+ :initial-value 1
+ :help "Say meow N times (default 1)."
+ :reduce #'adopt:last
+ :key #'parse-integer))))
-<span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"--times"</span> <span class="s">"5"</span><span class="p">))</span>
-<span class="c1">; =></span>
-<span class="c1">; NIL</span>
-<span class="c1">; {TIMES: 5}</span>
+(adopt:parse-options *ui* '("--times" "5"))
+; =>
+; NIL
+; {TIMES: 5}
-<span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"--bark"</span><span class="p">))</span>
-<span class="c1">; =></span>
-<span class="c1">; No such option "--bark".</span>
-<span class="c1">; [Condition of type UNRECOGNIZED-OPTION]</span>
-<span class="c1">;</span>
-<span class="c1">; Restarts:</span>
-<span class="c1">; R 0. DISCARD-OPTION - Discard the unrecognized option.</span>
-<span class="c1">; R 1. TREAT-AS-ARGUMENT - Treat the unrecognized option as a plain argument.</span>
-<span class="c1">; R 2. SUPPLY-NEW-VALUE - Supply a new value to parse.</span>
-<span class="c1">; R 3. RETRY - Retry SLIME REPL evaluation request.</span>
-<span class="c1">; R 4. *ABORT - Return to SLIME's top level.</span>
-<span class="c1">; R 5. ABORT - abort thread (#<THREAD "repl-thread" RUNNING {100AF48413}>)</span>
-</pre></div>
-
-
+(adopt:parse-options *ui* '("--bark"))
+; =>
+; No such option "--bark".
+; [Condition of type UNRECOGNIZED-OPTION]
+;
+; Restarts:
+; R 0. DISCARD-OPTION - Discard the unrecognized option.
+; R 1. TREAT-AS-ARGUMENT - Treat the unrecognized option as a plain argument.
+; R 2. SUPPLY-NEW-VALUE - Supply a new value to parse.
+; R 3. RETRY - Retry SLIME REPL evaluation request.
+; R 4. *ABORT - Return to SLIME's top level.
+; R 5. ABORT - abort thread (#<THREAD "repl-thread" RUNNING {100AF48413}>)
+</code></pre>
<p>Adopt provides three possible restarts for this condition as seen above. Adopt
also provides functions with the same names that invoke the restarts properly,
to make it easier to use them programatically with <code>handler-bind</code>. For example:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">handler-bind</span>
- <span class="p">((</span><span class="nv">adopt:unrecognized-option</span> <span class="ss">'adopt:discard-option</span><span class="p">))</span>
- <span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"--bark"</span><span class="p">)))</span>
-<span class="c1">; =></span>
-<span class="c1">; NIL</span>
-<span class="c1">; {TIMES: 1}</span>
+<pre><code>:::lisp
+(handler-bind
+ ((adopt:unrecognized-option 'adopt:discard-option))
+ (adopt:parse-options *ui* '("--bark")))
+; =>
+; NIL
+; {TIMES: 1}
-<span class="p">(</span><span class="nb">handler-bind</span>
- <span class="p">((</span><span class="nv">adopt:unrecognized-option</span> <span class="ss">'adopt:treat-as-argument</span><span class="p">))</span>
- <span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"--bark"</span><span class="p">)))</span>
-<span class="c1">; =></span>
-<span class="c1">; ("--bark")</span>
-<span class="c1">; {TIMES: 1}</span>
+(handler-bind
+ ((adopt:unrecognized-option 'adopt:treat-as-argument))
+ (adopt:parse-options *ui* '("--bark")))
+; =>
+; ("--bark")
+; {TIMES: 1}
-<span class="p">(</span><span class="nb">handler-bind</span>
- <span class="p">((</span><span class="nv">adopt:unrecognized-option</span>
- <span class="p">(</span><span class="nv">alexandria:rcurry</span> <span class="ss">'adopt:supply-new-value</span> <span class="s">"--times"</span><span class="p">)))</span>
- <span class="p">(</span><span class="nv">adopt:parse-options</span> <span class="vg">*ui*</span> <span class="o">'</span><span class="p">(</span><span class="s">"--bark"</span> <span class="s">"5"</span><span class="p">)))</span>
-<span class="c1">; =></span>
-<span class="c1">; NIL</span>
-<span class="c1">; {TIMES: 5}</span>
-</pre></div>
-
-
+(handler-bind
+ ((adopt:unrecognized-option
+ (alexandria:rcurry 'adopt:supply-new-value "--times")))
+ (adopt:parse-options *ui* '("--bark" "5")))
+; =>
+; NIL
+; {TIMES: 5}
+</code></pre>
<h2 id="generating-man-pages">Generating Man Pages</h2>
<p>We've already seen that Adopt can print a pretty help document, but it can also
render <code>man</code> pages for you:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">with-open-file</span> <span class="p">(</span><span class="nv">out</span> <span class="s">"man/man1/search.1"</span>
- <span class="ss">:direction</span> <span class="ss">:output</span>
- <span class="ss">:if-exists</span> <span class="ss">:supersede</span><span class="p">)</span>
- <span class="p">(</span><span class="nv">adopt:print-manual</span> <span class="vg">*ui*</span> <span class="ss">:stream</span> <span class="nv">out</span><span class="p">))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(with-open-file (out "man/man1/search.1"
+ :direction :output
+ :if-exists :supersede)
+ (adopt:print-manual *ui* :stream out))
+</code></pre>
<p>The generated <code>man</code> page will contain the same information as the help text by
default. If you want to override this (e.g. to provide a short summary of an
option in the help text, but elaborate more in the manual), you can use the
<code>:manual</code> argument to <code>make-interface</code> and <code>make-option</code>:</p>
-<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*option-exclude*</span>
- <span class="p">(</span><span class="nv">adopt:make-option</span> <span class="ss">'exclude</span>
- <span class="ss">:long</span> <span class="s">"exclude"</span>
- <span class="ss">:parameter</span> <span class="s">"PATTERN"</span>
- <span class="ss">:help</span> <span class="s">"Exclude PATTERN."</span>
- <span class="ss">:manual</span> <span class="s">"Exclude lines that match PATTERN (a PERL-compatible regular expression) from the search results. Multiple PATTERNs can be specified by giving this option multiple times."</span>
- <span class="ss">:reduce</span> <span class="p">(</span><span class="nv">adopt:flip</span> <span class="nf">#'</span><span class="nb">cons</span><span class="p">)))</span>
-</pre></div>
-
-
+<pre><code>:::lisp
+(defparameter *option-exclude*
+ (adopt:make-option 'exclude
+ :long "exclude"
+ :parameter "PATTERN"
+ :help "Exclude PATTERN."
+ :manual "Exclude lines that match PATTERN (a PERL-compatible regular expression) from the search results. Multiple PATTERNs can be specified by giving this option multiple times."
+ :reduce (adopt:flip #'cons)))
+</code></pre>
<p>In order for <code>man</code> to find the pages, they need to be in the correct place. By
default <code>man</code> is usually smart enough to look next to every directory in your
<code>$PATH</code> to find a directory called <code>man</code>. So if you put your binaries in
@@ -956,8 +920,7 @@
<h3 id="clozurecl">ClozureCL</h3>
<p>See <a href="https://github.com/Clozure/ccl/issues/177">https://github.com/Clozure/ccl/issues/177</a>.</p>
</div>
- <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a>.</i></p>
-<p><a href="http://rochestermade.com" title="Rochester Made"><img src="https://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
+ <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a>.</i></p></footer>
</div>
</body>
</html>
\ No newline at end of file