hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <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"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <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>
<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
don't touch it.</p>
<div class="toc">
<ul>
<li><a href="#package-adopt">Package ADOPT</a><ul>
<li><a href="#argv-function">ARGV (function)</a></li>
<li><a href="#collect-function">COLLECT (function)</a></li>
<li><a href="#define-string-macro">DEFINE-STRING (macro)</a></li>
<li><a href="#defparameters-macro">DEFPARAMETERS (macro)</a></li>
<li><a href="#discard-option-function">DISCARD-OPTION (function)</a></li>
<li><a href="#exit-function">EXIT (function)</a></li>
<li><a href="#first-function">FIRST (function)</a></li>
<li><a href="#flip-function">FLIP (function)</a></li>
<li><a href="#last-function">LAST (function)</a></li>
<li><a href="#make-boolean-options-function">MAKE-BOOLEAN-OPTIONS (function)</a></li>
<li><a href="#make-group-function">MAKE-GROUP (function)</a></li>
<li><a href="#make-interface-function">MAKE-INTERFACE (function)</a></li>
<li><a href="#make-option-function">MAKE-OPTION (function)</a></li>
<li><a href="#parse-options-function">PARSE-OPTIONS (function)</a></li>
<li><a href="#parse-options-or-exit-function">PARSE-OPTIONS-OR-EXIT (function)</a></li>
<li><a href="#print-error-and-exit-function">PRINT-ERROR-AND-EXIT (function)</a></li>
<li><a href="#print-help-function">PRINT-HELP (function)</a></li>
<li><a href="#print-help-and-exit-function">PRINT-HELP-AND-EXIT (function)</a></li>
<li><a href="#print-manual-function">PRINT-MANUAL (function)</a></li>
<li><a href="#supply-new-value-function">SUPPLY-NEW-VALUE (function)</a></li>
<li><a href="#treat-as-argument-function">TREAT-AS-ARGUMENT (function)</a></li>
<li><a href="#unrecognized-option-class">UNRECOGNIZED-OPTION (class)</a><ul>
<li><a href="#slot-problematic-option">Slot PROBLEMATIC-OPTION</a></li>
</ul>
</li>
</ul>
</li>
</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>


<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>


<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 &amp;REST ARGS)
</pre></div>


<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>


<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>
<p><code>values-form</code> must be an expression that returns as many values as parameters
  in the parameter list.  Each parameter will be set to the corresponding value.</p>
<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))
(list *a* *b*)
; =&gt;
; (33 1)

(defparameters (*option-foo* *option-no-foo*)
  (make-boolean-options 'foo
    :help "Foo the widgets during the run."
    :help-no "Do not foo the widgets during the run (the default)."
    :long "foo"
    :short #f))
</pre></div>


<h3 id="discard-option-function"><code>DISCARD-OPTION</code> (function)</h3>
<div class="codehilite"><pre><span/>(DISCARD-OPTION CONDITION)
</pre></div>


<p>Invoke the <code>discard-option</code> restart properly.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(handler-bind ((unrecognized-option 'discard-option))
  (multiple-value-bind (arguments options) (parse-options *ui*)
    (run arguments options)))
</pre></div>


<h3 id="exit-function"><code>EXIT</code> (function)</h3>
<div class="codehilite"><pre><span/>(EXIT &amp;OPTIONAL (CODE 0))
</pre></div>


<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>


<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>


<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)        ; =&gt; (1 . 2)
(funcall (flip #'cons) 1 2) ; =&gt; (2 . 1)
(reduce (flip #'cons) '(1 2 3) :initial-value nil)
; =&gt; (3 2 1)
</pre></div>


<h3 id="last-function"><code>LAST</code> (function)</h3>
<div class="codehilite"><pre><span/>(LAST OLD NEW)
</pre></div>


<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 &amp;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>


<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
  appropriate name, long option, short option, and result key, but you can
  override them with the <code>…-no</code> keyword options as needed.</p>
<p>The two options will be returned as two separate values — you can use
  <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*)
  (make-boolean-options 'debug
    :long "debug"
    :short #d
    :help "Enable the Lisp debugger."
    :help-no "Disable the Lisp debugger (the default)."))

;; is roughly equivalent to:

(defparameter *option-debug*
  (make-option 'debug
    :long "debug"
    :short #d
    :help "Enable the Lisp debugger."
    :initial-value nil
    :reduce (constantly t))

(defparameter *option-no-debug*
  (make-option 'no-debug
    :long "no-debug"
    :short #D
    :help "Disable the Lisp debugger (the default)."
    :reduce (constantly nil))
</pre></div>


<h3 id="make-group-function"><code>MAKE-GROUP</code> (function)</h3>
<div class="codehilite"><pre><span/>(MAKE-GROUP NAME &amp;KEY TITLE HELP MANUAL OPTIONS)
</pre></div>


<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>
<ul>
<li><code>name</code> (<strong>required</strong>): a symbol naming the group.</li>
<li><code>title</code> (optional): a title for the group for use in the help text.</li>
<li><code>help</code> (optional): a short summary of this group of options for use in the help text.</li>
<li><code>manual</code> (optional): used in place of <code>help</code> when rendering a man page.</li>
<li><code>options</code> (<strong>required</strong>): the options to include in the group.</li>
</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 &amp;KEY NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS)
</pre></div>


<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>
<ul>
<li><code>name</code> (<strong>required</strong>): a symbol naming the interface.</li>
<li><code>summary</code> (<strong>required</strong>): a string of a concise, one-line summary of what the program does.</li>
<li><code>usage</code> (<strong>required</strong>): a string of a UNIX-style usage summary, e.g. <code>"[OPTIONS] PATTERN [FILE...]"</code>.</li>
<li><code>help</code> (<strong>required</strong>): a string of a longer description of the program.</li>
<li><code>manual</code> (optional): a string to use in place of <code>help</code> when rendering a man page.</li>
<li><code>examples</code> (optional): an alist of <code>(prose . command)</code> conses to render as a list of examples.</li>
<li><code>contents</code> (optional): a list of options and groups.  Ungrouped options will be collected into a single top-level group.</li>
</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 &amp;KEY LONG SHORT HELP MANUAL PARAMETER REDUCE
             (INITIAL-VALUE NIL INITIAL-VALUE?) (RESULT-KEY NAME) (KEY #'IDENTITY)
             (FINALLY #'IDENTITY))
</pre></div>


<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>
<ul>
<li><code>name</code> (<strong>required</strong>): a symbol naming the option.</li>
<li><code>help</code> (<strong>required</strong>): a short string describing what the option does.</li>
<li><code>result-key</code> (optional): a symbol to use as the key for this option in the hash table of results.</li>
<li><code>long</code> (optional): a string for the long form of the option (e.g. <code>--foo</code>).</li>
<li><code>short</code> (optional): a character for the short form of the option (e.g. <code>-f</code>).  At least one of <code>short</code> and <code>long</code> must be given.</li>
<li><code>manual</code> (optional): a string to use in place of <code>help</code> when rendering a man page.</li>
<li><code>parameter</code> (optional): a string.  If given, it will turn this option into a parameter-taking option (e.g. <code>--foo=bar</code>) and will be used as a placeholder
  in the help text.</li>
<li><code>reduce</code> (<strong>required</strong>): a function designator that will be called every time the option is specified by the user.</li>
<li><code>initial-value</code> (optional): a value to use as the initial value of the option.</li>
<li><code>key</code> (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.</li>
<li><code>finally</code> (optional): a function designator to be called on the final result after all parsing is complete. </li>
</ul>
<p>The manner in which the reducer is called depends on whether the option takes a parameter:</p>
<ul>
<li>For options that don't take parameters, it will be called with the old value.</li>
<li>For options that take parameters, it will be called with the old value and the value given by the user.</li>
</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 &amp;OPTIONAL (ARGUMENTS (REST (ARGV))))
</pre></div>


<p>Parse <code>arguments</code> according to <code>interface</code>.</p>
<p>Two values are returned:</p>
<ol>
<li>A fresh list of top-level, unaccounted-for arguments that don't correspond
     to any options defined in <code>interface</code>.</li>
<li>An <code>EQL</code> hash table of option keys to values.</li>
</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 &amp;OPTIONAL (ARGUMENTS (REST (ARGV))))
</pre></div>


<p>Parse <code>arguments</code> according to <code>interface</code>, exiting if any error occurs.</p>
<p>Two values are returned:</p>
<ol>
<li>A fresh list of top-level, unaccounted-for arguments that don't correspond
     to any options defined in <code>interface</code>.</li>
<li>An <code>EQL</code> hash table of option keys to values.</li>
</ol>
<p>If an error occurs while parsing the arguments, exits immediately as if with
  <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 &amp;KEY (STREAM *ERROR-OUTPUT*) (EXIT-FUNCTION #'EXIT) (EXIT-CODE 1)
                      (PREFIX error: ))
</pre></div>


<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
    (multiple-value-bind (arguments options) (parse-options *ui*)
      (run arguments options))
  (unrecognized-option (c)
    (print-error-and-exit c)))
</pre></div>


<h3 id="print-help-function"><code>PRINT-HELP</code> (function)</h3>
<div class="codehilite"><pre><span/>(PRINT-HELP INTERFACE &amp;KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV))) (WIDTH 80)
            (OPTION-WIDTH 20) (INCLUDE-EXAMPLES T))
</pre></div>


<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
  cases (extremely long short/long option names and parameters) may slip
  through.</p>
<p><code>option-width</code> should be the width of the column of short/long options (in
  characters).  If the short/long option help is shorter than this, the option's
  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)
; =&gt;
; foo - do some things and meow
;
; USAGE: /bin/foo [options] FILES
;
; Foo is a program to frobulate some files, meowing as it
; happens.
;
; Options:
;   -v, --verbose    Output extra information.
;   -q, --quiet      Shut up.
;   --ignore FILE    Ignore FILE.  May be specified multiple
;                    times.
;   -n NAME, --name NAME
;                    Your name.  May be specified many times,
;                    last one wins.
;   -m, --meow       Meow.
;   0.........1.... option-width
; 0........1.........2.........3.........4.........5.........6
</pre></div>


<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 &amp;KEY (STREAM *STANDARD-OUTPUT*) (PROGRAM-NAME (CAR (ARGV)))
                     (WIDTH 80) (OPTION-WIDTH 20) (INCLUDE-EXAMPLES T) (EXIT-FUNCTION #'EXIT)
                     (EXIT-CODE 0))
</pre></div>


<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*)
  (when (gethash 'help options)
    (print-help-and-exit *ui*))
  (run arguments options))
</pre></div>


<h3 id="print-manual-function"><code>PRINT-MANUAL</code> (function)</h3>
<div class="codehilite"><pre><span/>(PRINT-MANUAL INTERFACE &amp;KEY (STREAM *STANDARD-OUTPUT*) (MANUAL-SECTION 1))
</pre></div>


<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"
                        :direction :output
                        :if-exists :supersede)
  (print-manual *ui* manual))
</pre></div>


<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>


<p>Invoke the <code>supply-new-value</code> restart properly.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(handler-bind
    ((unrecognized-option (alexandria:rcurry 'supply-new-value "--foo"))
  (multiple-value-bind (arguments options) (parse-options *ui*)
    (run arguments options)))
</pre></div>


<h3 id="treat-as-argument-function"><code>TREAT-AS-ARGUMENT</code> (function)</h3>
<div class="codehilite"><pre><span/>(TREAT-AS-ARGUMENT CONDITION)
</pre></div>


<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))
  (multiple-value-bind (arguments options) (parse-options *ui*)
    (run arguments options)))
</pre></div>


<h3 id="unrecognized-option-class"><code>UNRECOGNIZED-OPTION</code> (class)</h3>
<h4 id="slot-problematic-option">Slot <code>PROBLEMATIC-OPTION</code></h4>
<ul>
<li>Allocation: <code>:INSTANCE</code></li>
<li>Initarg: <code>:PROBLEMATIC-OPTION</code></li>
<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>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Wed, 21 Jun 2023 15:21:12 -0400
parents	7af6d40d8264
children	0f6bab39c0f4