/usr/share/doc/libtools-cli-clojure/html/README.html is in libtools-cli-clojure 0.3.5-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>tools.cli</title>
</head>
<body><h1>tools.cli</h1>
<p>Tools for working with command line arguments.</p>
<h2>Stable Releases and Dependency Information</h2>
<p>Latest stable release: 0.3.5</p>
<ul>
<li><p><a href="http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22tools.cli%22">All Released Versions</a></p></li>
<li><p><a href="https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~tools.cli~~~">Development Snapshot Versions</a></p></li>
</ul>
<p><a href="https://github.com/technomancy/leiningen">Leiningen</a> dependency information:
<code>clojure
[org.clojure/tools.cli "0.3.5"]
</code>
<a href="http://maven.apache.org/">Maven</a> dependency information:
<code>xml
<dependency>
<groupId>org.clojure</groupId>
<artifactId>tools.cli</artifactId>
<version>0.3.5</version>
</dependency>
</code>
The 0.3.x series of tools.cli features a new flexible API, better adherence
to GNU option parsing conventions, and ClojureScript support.</p>
<p>The function <code>clojure.tools.cli/cli</code> has been superseded by
<code>clojure.tools.cli/parse-opts</code>, and should not be used in new programs.</p>
<p>The previous function will remain for the forseeable future. It has also been
adapted to use the new tokenizer, so upgrading is still worthwhile even if you
are not ready to migrate to <code>parse-opts</code>.</p>
<h2>Quick Start</h2>
<p>```clojure
(ns my.program
(:require [clojure.tools.cli :refer [parse-opts]])
(:gen-class))</p>
<p>(def cli-options
;; An option with a required argument
[["-p" "--port PORT" "Port number"
:default 80
:parse-fn #(Integer/parseInt %)
:validate [#(< 0 % 0x10000) "Must be a number between 0 and 65536"]]
;; A non-idempotent option
["-v" nil "Verbosity level"
:id :verbosity
:default 0
:assoc-fn (fn [m k _] (update-in m [k] inc))]
;; A boolean option defaulting to nil
["-h" "--help"]])</p>
<p>(defn -main [& args]
(parse-opts args cli-options))
```</p>
<p>Execute the command line:</p>
<pre><code>my-program -vvvp8080 foo --help --invalid-opt
</code></pre>
<p>to produce the map:</p>
<p>```clojure
{:options {:port 8080
:verbosity 3
:help true}</p>
<p>:arguments ["foo"]</p>
<p>:summary " -p, --port PORT 80 Port number
-v Verbosity level
-h, --help"</p>
<p>:errors ["Unknown option: \"--invalid-opt\""]}
```</p>
<p><strong>Note</strong> that exceptions are <em>not</em> thrown on parse errors, so errors must be
handled explicitly after checking the <code>:errors</code> entry for a truthy value.</p>
<p>Please see the <a href="#example-usage">example program</a> for a more detailed example
and refer to the docstring of <code>parse-opts</code> for comprehensive documentation:</p>
<p>http://clojure.github.io/tools.cli/index.html#clojure.tools.cli/parse-opts</p>
<h2>New Features in 0.3.x</h2>
<h3>Better Option Tokenization</h3>
<p>In accordance with the <a href="https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html">GNU Program Argument Syntax Conventions</a>, two
features have been added to the options tokenizer:</p>
<ul>
<li><p>Short options may be grouped together.</p>
<p>For instance, <code>-abc</code> is equivalent to <code>-a -b -c</code>. If the <code>-b</code> option
requires an argument, the same <code>-abc</code> is interpreted as <code>-a -b "c"</code>.</p></li>
<li><p>Long option arguments may be specified with an equals sign.</p>
<p><code>--long-opt=ARG</code> is equivalent to <code>--long-opt "ARG"</code>.</p>
<p>If the argument is omitted, it is interpreted as the empty string.
e.g. <code>--long-opt=</code> is equivalent to <code>--long-opt ""</code></p></li>
</ul>
<h3>In-order Processing for Subcommands</h3>
<p>Large programs are often divided into subcommands with their own sets of
options. To aid in designing such programs, <code>clojure.tools.cli/parse-opts</code>
accepts an <code>:in-order</code> option that directs it to stop processing arguments at
the first unrecognized token.</p>
<p>For instance, the <code>git</code> program has a set of top-level options that are
unrecognized by subcommands and vice-versa:</p>
<pre><code>git --git-dir=/other/proj/.git log --oneline --graph
</code></pre>
<p>By default, <code>clojure.tools.cli/parse-opts</code> interprets this command line as:</p>
<pre><code>options: [[--git-dir /other/proj/.git]
[--oneline]
[--graph]]
arguments: [log]
</code></pre>
<p>When :in-order is true however, the arguments are interpreted as:</p>
<pre><code>options: [[--git-dir /other/proj/.git]]
arguments: [log --oneline --graph]
</code></pre>
<p>Note that the options to <code>log</code> are not parsed, but remain in the unprocessed
arguments vector. These options could be handled by another call to
<code>parse-opts</code> from within the function that handles the <code>log</code> subcommand.</p>
<h3>Options Summary</h3>
<p><code>parse-opts</code> returns a minimal options summary string:</p>
<pre><code> -p, --port NUMBER 8080 Required option with default
--host HOST localhost Short and long options may be omitted
-d, --detach Boolean option
-h, --help
</code></pre>
<p>This may be inserted into a larger usage summary, but it is up to the caller.</p>
<p>If the default formatting of the summary is unsatisfactory, a <code>:summary-fn</code>
may be supplied to <code>parse-opts</code>. This function will be passed the sequence
of compiled option specification maps and is expected to return an options
summary.</p>
<p>The default summary function <code>clojure.tools.cli/summarize</code> is public and may
be useful within your own <code>:summary-fn</code> for generating the default summary.</p>
<h3>Option Argument Validation</h3>
<p>There is a new option entry <code>:validate</code>, which takes a tuple of
<code>[validation-fn validation-msg]</code>. The validation-fn receives an option's
argument <em>after</em> being parsed by <code>:parse-fn</code> if it exists.</p>
<pre><code>["-p" "--port PORT" "A port number"
:parse-fn #(Integer/parseInt %)
:validate [#(< 0 % 0x10000) "Must be a number between 0 and 65536"]]
</code></pre>
<p>If the validation-fn returns a falsy value, the validation-msg is added to the
errors vector.</p>
<h3>Error Handling and Return Values</h3>
<p>Instead of throwing errors, <code>parse-opts</code> collects error messages into a vector
and returns them to the caller. Unknown options, missing required arguments,
validation errors, and exceptions thrown during <code>:parse-fn</code> are all added to
the errors vector.</p>
<p>Correspondingly, <code>parse-opts</code> returns the following map of values:</p>
<pre><code>{:options A map of default options merged with parsed values from the command line
:arguments A vector of unprocessed arguments
:summary An options summary string
:errors A vector of error messages, or nil if no errors}
</code></pre>
<p>During development, parse-opts asserts the uniqueness of option <code>:id</code>,
<code>:short-opt</code>, and <code>:long-opt</code> values and throws an error on failure.</p>
<h3>ClojureScript Support</h3>
<p>The <code>cljs.tools.cli</code> namespace is available for use in ClojureScript programs!
Both <code>parse-opts</code> and <code>summarize</code> have been ported, and have complete feature
parity with their Clojure counterparts.</p>
<p>ClojureScript Versions <code>0.0-2080</code> and above are supported, but earlier
versions are likely to work as well.</p>
<h2>Example Usage</h2>
<p>```clojure
(ns cli-example.core
(:require [cli-example.server :as server]
[clojure.string :as string]
[clojure.tools.cli :refer [parse-opts]])
(:import (java.net InetAddress))
(:gen-class))</p>
<p>(def cli-options
[;; First three strings describe a short-option, long-option with optional
;; example argument description, and a description. All three are optional
;; and positional.
["-p" "--port PORT" "Port number"
:default 80
:parse-fn #(Integer/parseInt %)
:validate [#(< 0 % 0x10000) "Must be a number between 0 and 65536"]]
["-H" "--hostname HOST" "Remote host"
:default (InetAddress/getByName "localhost")
;; Specify a string to output in the default column in the options summary
;; if the default value's string representation is very ugly
:default-desc "localhost"
:parse-fn #(InetAddress/getByName %)]
;; If no required argument description is given, the option is assumed to
;; be a boolean option defaulting to nil
[nil "--detach" "Detach from controlling process"]
["-v" nil "Verbosity level; may be specified multiple times to increase value"
;; If no long-option is specified, an option :id must be given
:id :verbosity
:default 0
;; Use assoc-fn to create non-idempotent options
:assoc-fn (fn [m k _] (update-in m [k] inc))]
["-h" "--help"]])</p>
<p>(defn usage [options-summary]
(->> ["This is my program. There are many like it, but this one is mine."
""
"Usage: program-name [options] action"
""
"Options:"
options-summary
""
"Actions:"
" start Start a new server"
" stop Stop an existing server"
" status Print a server's status"
""
"Please refer to the manual page for more information."]
(string/join \newline)))</p>
<p>(defn error-msg [errors]
(str "The following errors occurred while parsing your command:\n\n"
(string/join \newline errors)))</p>
<p>(defn exit [status msg]
(println msg)
(System/exit status))</p>
<p>(defn -main [& args]
(let [{:keys [options arguments errors summary]} (parse-opts args cli-options)]
;; Handle help and error conditions
(cond
(:help options) (exit 0 (usage summary))
(not= (count arguments) 1) (exit 1 (usage summary))
errors (exit 1 (error-msg errors)))
;; Execute program with options
(case (first arguments)
"start" (server/start! options)
"stop" (server/stop! options)
"status" (server/status! options)
(exit 1 (usage summary)))))
```</p>
<h2>Developer Information</h2>
<ul>
<li><p><a href="https://github.com/clojure/tools.cli">GitHub project</a></p></li>
<li><p><a href="http://dev.clojure.org/jira/browse/TCLI">Bug Tracker</a></p></li>
<li><p><a href="http://build.clojure.org/job/tools.cli/">Continuous Integration</a></p></li>
<li><p><a href="http://build.clojure.org/job/tools.cli-test-matrix/">Compatibility Test Matrix</a></p></li>
</ul>
<h2>Change Log</h2>
<ul>
<li>Release 0.3.5 on 2016-05-04
<ul>
<li>Fix <code>summarize</code> in cljs after renaming during TCLI-36 below
<a href="http://dev.clojure.org/jira/browse/TCLI-85">TCLI-85</a>.</li>
</ul></li>
<li>Release 0.3.4 on 2016-05-01
<ul>
<li>Clarify use of <code>summarize</code> via expanded docstring and make both of the
functions it calls public so it is easier to build your own <code>:summary-fn</code>.
<a href="http://dev.clojure.org/jira/browse/TCLI-36">TCLI-36</a>.</li>
<li>Release 0.3.3 on 2015-08-21</li>
<li>Add <code>:missing</code> to option specification to produce the given error message
if the option is not provided (and has no default value).
<a href="http://dev.clojure.org/jira/browse/TCLI-12">TCLI-12</a></li>
<li>Add <code>:strict</code> to <code>parse-opts</code>:
If true, treats required option arguments that match other options as a
parse error (missing required argument).
<a href="http://dev.clojure.org/jira/browse/TCLI-10">TCLI-10</a></li>
</ul></li>
<li>Release 0.3.2 on 2015-07-28
<ul>
<li>Add <code>:no-defaults</code> to <code>parse-opts</code>:
Returns sequence of options that excludes defaulted ones. This helps
support constructing options from multiple sources (command line, config file).</li>
<li>Add <code>get-default-options</code>:
Returns sequence of options that have defaults specified.</li>
<li>Support multiple validations <a href="http://dev.clojure.org/jira/browse/TCLI-9">TCLI-9</a></li>
<li>Support in-order arguments <a href="http://dev.clojure.org/jira/browse/TCLI-5">TCLI-5</a>:
<code>:in-order</code> processes arguments up to the first unknown option;
A warning is displayed when unknown options are encountered.</li>
</ul></li>
<li>Release 0.3.1 on 2014-01-02
<ul>
<li>Apply patch for <a href="http://dev.clojure.org/jira/browse/TCLI-8">TCLI-8</a>:
Correct test that trivially always passes</li>
<li>Apply patch for <a href="http://dev.clojure.org/jira/browse/TCLI-7">TCLI-7</a>:
summarize throws when called with an empty sequence of options</li>
</ul></li>
<li>Release 0.3.0 on 2013-12-15
<ul>
<li>Add public functions <code>parse-opts</code> and <code>summarize</code> to supersede <code>cli</code>,
addressing <a href="http://dev.clojure.org/jira/browse/TCLI-3">TCLI-3</a>,
<a href="http://dev.clojure.org/jira/browse/TCLI-4">TCLI-4</a>, and
<a href="http://dev.clojure.org/jira/browse/TCLI-6">TCLI-6</a></li>
<li>Add ClojureScript port of <code>parse-opts</code> and <code>summarize</code>, available in
<code>cljs.tools.cli</code>.</li>
<li>Move extra documentation of <code>cli</code> function to
https://github.com/clojure/tools.cli/wiki/Documentation-for-0.2.4</li>
</ul></li>
<li>Release 0.2.4 on 2013-08-06
<ul>
<li>Applying patch for <a href="http://dev.clojure.org/jira/browse/TCLI-2">TCLI-2</a>
(support an assoc-fn option)</li>
</ul></li>
<li>Release 0.2.3 on 2013-08-06
<ul>
<li>Add optional description string to prefix the returned banner</li>
</ul></li>
<li>Release 0.2.2 on 2012-08-09
<ul>
<li>Applying patch for <a href="http://dev.clojure.org/jira/browse/TCLI-1">TCLI-1</a>
(do not include keys when no value provided by :default)</li>
</ul></li>
<li>Release 0.2.1 on 2011-11-03
<ul>
<li>Removing the :required option. Hangover from when -h and --help were
implemented by default, causes problems if you want help and dont
provide a :required argument.</li>
</ul></li>
<li>Release 0.2.0 on 2011-10-31
<ul>
<li>Remove calls to System/exit</li>
<li>Remove built-in help options</li>
</ul></li>
<li>Release 0.1.0
<ul>
<li>Initial import of Clargon codebase</li>
</ul></li>
</ul>
<h2>License</h2>
<p>Copyright (c) Rich Hickey and contributors. All rights reserved.</p>
<p>The use and distribution terms for this software are covered by the
Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
which can be found in the file epl.html at the root of this distribution.
By using this software in any fashion, you are agreeing to be bound by
the terms of this license.</p>
<p>You must not remove this notice, or any other, from this software.</p>
</body>
</html>
|