initial release
This commit is contained in:
23
README.md
23
README.md
@@ -23,6 +23,29 @@ A simple CLI library for Carp.
|
||||
|
||||
## Usage
|
||||
|
||||
`CLI` should be built using combinators, as in the example above. It has, as of
|
||||
now, three option types: integrals (longs), floating point numbers (doubles),
|
||||
and strings. They can be built using `CLI.int`, `CLI.float`, and `CLI.str`,
|
||||
respectively. Their structure is always the same:
|
||||
|
||||
```clojure
|
||||
(CLI.int <long> <short> <description> <required?>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default> <options-array>)
|
||||
```
|
||||
|
||||
You’ll have to set a default if you want to specify options, although you can
|
||||
set it to `(Maybe.Nothing)` if you want to make sure that it has to be set
|
||||
manually.
|
||||
|
||||
Once you’re done building your flag structure, you can run `CLI.parse`. It
|
||||
will not abort the program on error, instead it will tell you what went wrong
|
||||
in a `Result.Error`. If it succeeds, the `Result.Success` contains a `Map` from
|
||||
the long flag name to the value (the values are `Maybe`s, since they might be
|
||||
optional arguments.
|
||||
|
||||
<hr/>
|
||||
|
||||
Have fun!
|
||||
|
85
cli.carp
85
cli.carp
@@ -1,8 +1,56 @@
|
||||
; TODO: this is temporary until we have this in the stdlib
|
||||
(defmodule Maybe
|
||||
(defn zero [] (Maybe.Nothing))
|
||||
)
|
||||
|
||||
(doc CLI "is a simple CLI library for Carp.
|
||||
|
||||
```clojure
|
||||
(load \"https://veitheller.de/git/carpentry/cli@0.0.1\")
|
||||
|
||||
(defn main []
|
||||
(let [p (=> (CLI.new @\"My super cool tool!\")
|
||||
(CLI.add &(CLI.int \"flag\" \"f\" \"my flag\" true))
|
||||
(CLI.add &(CLI.str \"thing\" \"t\" \"my thing\" false @\"hi\" &[@\"a\" @\"b\" @\"hi\"])))]
|
||||
(match (CLI.parse &p)
|
||||
(Result.Success flags)
|
||||
(println* &(str &(Map.get &flags \"flag\")) \" \" &(str &(Map.get &flags \"thing\")))
|
||||
(Result.Error msg) (do (IO.errorln &msg) (CLI.usage &p)))))
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```clojure
|
||||
(load \"https://veitheller.de/git/carpentry/cli@0.0.1\")
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
`CLI` should be built using combinators, as in the example above. It has, as of
|
||||
now, three option types: integrals (longs), floating point numbers (doubles),
|
||||
and strings. They can be built using `CLI.int`, `CLI.float`, and `CLI.str`,
|
||||
respectively. Their structure is always the same:
|
||||
|
||||
```clojure
|
||||
(CLI.int <long> <short> <description> <required?>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default> <options-array>)
|
||||
```
|
||||
|
||||
You’ll have to set a default if you want to specify options, although you can
|
||||
set it to `(Maybe.Nothing)` if you want to make sure that it has to be set
|
||||
manually.
|
||||
|
||||
Once you’re done building your flag structure, you can run `CLI.parse`. It
|
||||
will not abort the program on error, instead it will tell you what went wrong
|
||||
in a `Result.Error`. If it succeeds, the `Result.Success` contains a `Map` from
|
||||
the long flag name to the value (the values are `Maybe`s, since they might be
|
||||
optional arguments.")
|
||||
(defmodule CLI
|
||||
(hidden Type)
|
||||
(private Type)
|
||||
(deftype Type
|
||||
(Integer [Long])
|
||||
(Floating [Double])
|
||||
@@ -32,6 +80,8 @@
|
||||
(Str s2) (String.format s &s2)))
|
||||
)
|
||||
|
||||
(hidden Tag)
|
||||
(private Tag)
|
||||
(deftype Tag
|
||||
(Integer [])
|
||||
(Floating [])
|
||||
@@ -46,6 +96,8 @@
|
||||
(Str) (CLI.Type.Str @s)))
|
||||
)
|
||||
|
||||
(doc Option "is the option type. To construct an `Option`, please use
|
||||
[`int`](#int), [`float`](#float), or [`str](#str).")
|
||||
(deftype Option [
|
||||
type- Tag
|
||||
long String
|
||||
@@ -56,11 +108,18 @@
|
||||
options (Maybe (Array Type))
|
||||
])
|
||||
|
||||
(doc Parser "is the parser type. To construct a `Parser`, please use
|
||||
[`new](#new).")
|
||||
(deftype Parser [
|
||||
description String
|
||||
options (Array Option)
|
||||
])
|
||||
|
||||
(private CmdMap)
|
||||
(hidden CmdMap)
|
||||
; this is pretty brutal. It’s a (Pair (Pair <long> <short>) (<tag> <value>))
|
||||
; we need to make our own map because long or short might match and both are
|
||||
; equivalent. This means a lot of manual work. Sorry about that.
|
||||
(deftype CmdMap [
|
||||
values (Array (Pair (Pair String String) (Pair Tag (Maybe Type))))
|
||||
])
|
||||
@@ -148,11 +207,15 @@
|
||||
(Array.reduce &CLI.CmdMap.put-empty (CLI.CmdMap.new) (options p)))
|
||||
)
|
||||
|
||||
(doc new "creates a new `Parser` with a program description `descr`.")
|
||||
(defn new [descr] (Parser.init descr []))
|
||||
|
||||
(doc add "adds an `Option` `opt` to the `Parser` `p`.")
|
||||
(defn add [p opt]
|
||||
(Parser.update-options p &(fn [options] (Array.push-back options @opt))))
|
||||
|
||||
(hidden option-)
|
||||
(private option-)
|
||||
(defndynamic option- [t long short description required default-options]
|
||||
(if (= (length default-options) 0)
|
||||
(list 'CLI.Option.init (list t)
|
||||
@@ -168,18 +231,20 @@
|
||||
(list 'Maybe.Just
|
||||
(list 'Array.copy-map '(ref (fn [e] (to-cli-type @e))) (cadr default-options)))))))
|
||||
|
||||
(defmacro option [long short description required :rest default-options]
|
||||
(CLI.option- t long short description required default-options))
|
||||
|
||||
(doc str "creates a string option.")
|
||||
(defmacro str [long short description required :rest default-options]
|
||||
(CLI.option- 'CLI.Tag.Str long short description required default-options))
|
||||
|
||||
(doc int "creates a integer option. The actual type is a `Long`.")
|
||||
(defmacro int [long short description required :rest default-options]
|
||||
(CLI.option- 'CLI.Tag.Integer long short description required default-options))
|
||||
|
||||
(doc float "creates a integer option. The actual type is a `Double`.")
|
||||
(defmacro float [long short description required :rest default-options]
|
||||
(CLI.option- 'CLI.Tag.Floating long short description required default-options))
|
||||
|
||||
(private options-str)
|
||||
(hidden options-str)
|
||||
(defn options-str [p]
|
||||
(join
|
||||
" "
|
||||
@@ -187,6 +252,7 @@
|
||||
&(fn [o] (fmt "[-%s | --%s]" (Option.short o) (Option.long o)))
|
||||
(Parser.options p))))
|
||||
|
||||
(doc usage "takes a `Parser` `p` and prints its usage information.")
|
||||
(defn usage [p]
|
||||
(do
|
||||
(IO.println
|
||||
@@ -207,6 +273,15 @@
|
||||
(IO.println "")))
|
||||
(IO.println " --help|-h: print this help message and exit.")))
|
||||
|
||||
(doc parse "parses the arguments as specified by the parser `p`.
|
||||
|
||||
If everything goes right, it will return a `Success` containing a map from
|
||||
the long arguments to their values. Because values can be optional, they are
|
||||
returned as `Maybe`.
|
||||
|
||||
Otherwise it will return an `Error` containing an error message. If that error
|
||||
mesage is empty, `--help` was requested. If you don’t want to provide a
|
||||
`--help` feature, you can override that flag.")
|
||||
(defn parse [p]
|
||||
(let-do [values (Parser.values p)
|
||||
res (Result.Success @p)
|
||||
@@ -226,8 +301,8 @@
|
||||
(break))))
|
||||
(or (= &flag "help") (= &flag "h"))
|
||||
(do
|
||||
(usage p)
|
||||
(System.exit 0))
|
||||
(set! res (Result.Error @""))
|
||||
(break))
|
||||
(do
|
||||
(set! res (Result.Error (fmt "Unknown option: %s" x)))
|
||||
(break))))
|
||||
|
258
docs/CLI.html
Normal file
258
docs/CLI.html
Normal file
@@ -0,0 +1,258 @@
|
||||
<!DOCTYPE HTML>
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
|
||||
<link rel="stylesheet" href="style.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="content">
|
||||
<div class="logo">
|
||||
<a href="http://github.com/carp-lang/Carp">
|
||||
<img src="logo.png">
|
||||
</a>
|
||||
<div class="title">
|
||||
cli
|
||||
</div>
|
||||
<div class="index">
|
||||
<ul>
|
||||
<li>
|
||||
<a href="CLI.html">
|
||||
CLI
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<h1>
|
||||
CLI
|
||||
</h1>
|
||||
<div class="module-description">
|
||||
<p>is a simple CLI library for Carp.</p>
|
||||
<pre><code class="language-clojure">(load "https://veitheller.de/git/carpentry/cli@0.0.1")
|
||||
|
||||
(defn main []
|
||||
(let [p (=> (CLI.new @"My super cool tool!")
|
||||
(CLI.add &(CLI.int "flag" "f" "my flag" true))
|
||||
(CLI.add &(CLI.str "thing" "t" "my thing" false @"hi" &[@"a" @"b" @"hi"])))]
|
||||
(match (CLI.parse &p)
|
||||
(Result.Success flags)
|
||||
(println* &(str &(Map.get &flags "flag")) " " &(str &(Map.get &flags "thing")))
|
||||
(Result.Error msg) (do (IO.errorln &msg) (CLI.usage &p)))))
|
||||
</code></pre>
|
||||
<h2>Installation</h2>
|
||||
<pre><code class="language-clojure">(load "https://veitheller.de/git/carpentry/cli@0.0.1")
|
||||
</code></pre>
|
||||
<h2>Usage</h2>
|
||||
<p><code>CLI</code> should be built using combinators, as in the example above. It has, as of
|
||||
now, three option types: integrals (longs), floating point numbers (doubles),
|
||||
and strings. They can be built using <code>CLI.int</code>, <code>CLI.float</code>, and <code>CLI.str</code>,
|
||||
respectively. Their structure is always the same:</p>
|
||||
<pre><code class="language-clojure">(CLI.int <long> <short> <description> <required?>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default>)
|
||||
; or
|
||||
(CLI.int <long> <short> <description> <required?> <default> <options-array>)
|
||||
</code></pre>
|
||||
<p>You’ll have to set a default if you want to specify options, although you can
|
||||
set it to <code>(Maybe.Nothing)</code> if you want to make sure that it has to be set
|
||||
manually.</p>
|
||||
<p>Once you’re done building your flag structure, you can run <code>CLI.parse</code>. It
|
||||
will not abort the program on error, instead it will tell you what went wrong
|
||||
in a <code>Result.Error</code>. If it succeeds, the <code>Result.Success</code> contains a <code>Map</code> from
|
||||
the long flag name to the value (the values are <code>Maybe</code>s, since they might be
|
||||
optional arguments.</p>
|
||||
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#Option">
|
||||
<h3 id="Option">
|
||||
Option
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
module
|
||||
</div>
|
||||
<p class="sig">
|
||||
Module
|
||||
</p>
|
||||
<span>
|
||||
|
||||
</span>
|
||||
<p class="doc">
|
||||
<p>is the option type. To construct an <code>Option</code>, please use
|
||||
<a href="#int"><code>int</code></a>, <a href="#float"><code>float</code></a>, or <a href="#str">`str</a>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#Parser">
|
||||
<h3 id="Parser">
|
||||
Parser
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
module
|
||||
</div>
|
||||
<p class="sig">
|
||||
Module
|
||||
</p>
|
||||
<span>
|
||||
|
||||
</span>
|
||||
<p class="doc">
|
||||
<p>is the parser type. To construct a <code>Parser</code>, please use
|
||||
<a href="#new">`new</a>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#add">
|
||||
<h3 id="add">
|
||||
add
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
defn
|
||||
</div>
|
||||
<p class="sig">
|
||||
(λ [Parser, (Ref Option)] Parser)
|
||||
</p>
|
||||
<pre class="args">
|
||||
(add p opt)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>adds an <code>Option</code> <code>opt</code> to the <code>Parser</code> <code>p</code>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#float">
|
||||
<h3 id="float">
|
||||
float
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
macro
|
||||
</div>
|
||||
<p class="sig">
|
||||
Macro
|
||||
</p>
|
||||
<pre class="args">
|
||||
(float long short description required :rest default-options)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>creates a integer option. The actual type is a <code>Double</code>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#int">
|
||||
<h3 id="int">
|
||||
int
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
macro
|
||||
</div>
|
||||
<p class="sig">
|
||||
Macro
|
||||
</p>
|
||||
<pre class="args">
|
||||
(int long short description required :rest default-options)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>creates a integer option. The actual type is a <code>Long</code>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#new">
|
||||
<h3 id="new">
|
||||
new
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
defn
|
||||
</div>
|
||||
<p class="sig">
|
||||
(λ [String] Parser)
|
||||
</p>
|
||||
<pre class="args">
|
||||
(new descr)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>creates a new <code>Parser</code> with a program description <code>descr</code>.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#parse">
|
||||
<h3 id="parse">
|
||||
parse
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
defn
|
||||
</div>
|
||||
<p class="sig">
|
||||
(λ [(Ref Parser)] (Result (Map String (Maybe Type)) String))
|
||||
</p>
|
||||
<pre class="args">
|
||||
(parse p)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>parses the arguments as specified by the parser <code>p</code>.</p>
|
||||
<p>If everything goes right, it will return a <code>Success</code> containing a map from
|
||||
the long arguments to their values. Because values can be optional, they are
|
||||
returned as <code>Maybe</code>.</p>
|
||||
<p>Otherwise it will return an <code>Error</code> containing an error message. If that error
|
||||
mesage is empty, <code>--help</code> was requested. If you don’t want to provide a
|
||||
<code>--help</code> feature, you can override that flag.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#str">
|
||||
<h3 id="str">
|
||||
str
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
macro
|
||||
</div>
|
||||
<p class="sig">
|
||||
Macro
|
||||
</p>
|
||||
<pre class="args">
|
||||
(str long short description required :rest default-options)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>creates a string option.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="binder">
|
||||
<a class="anchor" href="#usage">
|
||||
<h3 id="usage">
|
||||
usage
|
||||
</h3>
|
||||
</a>
|
||||
<div class="description">
|
||||
defn
|
||||
</div>
|
||||
<p class="sig">
|
||||
(λ [(Ref Parser)] ())
|
||||
</p>
|
||||
<pre class="args">
|
||||
(usage p)
|
||||
</pre>
|
||||
<p class="doc">
|
||||
<p>takes a <code>Parser</code> <code>p</code> and prints its usage information.</p>
|
||||
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
110
docs/style.css
Normal file
110
docs/style.css
Normal file
@@ -0,0 +1,110 @@
|
||||
html {
|
||||
font-family: "Helvetica", sans-serif;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
a {
|
||||
color: #000;
|
||||
}
|
||||
|
||||
.logo {
|
||||
display: none;
|
||||
}
|
||||
|
||||
ul {
|
||||
list-style-type: none;
|
||||
font-family: "Hasklig", "Lucida Console", monospace;
|
||||
line-height: 1.4em;
|
||||
}
|
||||
|
||||
.module-description {
|
||||
margin-bottom: 3em;
|
||||
}
|
||||
|
||||
.content {
|
||||
margin: 3em auto auto auto;
|
||||
width: 80%;
|
||||
max-width: 610px;
|
||||
min-width: 400px
|
||||
}
|
||||
|
||||
h1 {
|
||||
margin-bottom: 1em;
|
||||
font-weight: 400;
|
||||
}
|
||||
|
||||
h2 {
|
||||
font-weight: 400;
|
||||
margin-bottom: 0em;
|
||||
}
|
||||
|
||||
h3 {
|
||||
margin: 0em;
|
||||
font-weight: 400;
|
||||
}
|
||||
|
||||
.binder {
|
||||
margin: 0em 0em 3.5em 0em;
|
||||
}
|
||||
|
||||
.sig {
|
||||
font-family: "Hasklig", "Lucida Console", monospace;
|
||||
margin: 0.5em 0em 0.5em 0em;
|
||||
}
|
||||
|
||||
.args {
|
||||
background-color: #eee;
|
||||
display: inline-block;
|
||||
white-space: normal;
|
||||
margin: 0;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
code {
|
||||
background-color: #eee;
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: #eee;
|
||||
overflow-y: scroll;
|
||||
}
|
||||
|
||||
.description {
|
||||
margin-top: 0.3em;
|
||||
font-size: 0.8em;
|
||||
color: #aaa;
|
||||
}
|
||||
|
||||
.huge {
|
||||
font-size: 15em;
|
||||
margin: 0em;
|
||||
}
|
||||
|
||||
/* Smaller screens */
|
||||
@media only screen and (max-width: 600px) {
|
||||
.logo {
|
||||
margin: 1em;
|
||||
text-align: left;
|
||||
float: left;
|
||||
width: 100%;
|
||||
}
|
||||
.logo img {
|
||||
display: block;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
width: 50%;
|
||||
}
|
||||
.content {
|
||||
margin: 0.5em;
|
||||
}
|
||||
.binder {
|
||||
margin: 0em 0em 1.5em 0em;
|
||||
}
|
||||
.sig {
|
||||
font-size: 0.9em;
|
||||
}
|
||||
ul {
|
||||
padding: 0px;
|
||||
}
|
||||
}
|
||||
.title, .index { display: none; }
|
13
gendocs.carp
Normal file
13
gendocs.carp
Normal file
@@ -0,0 +1,13 @@
|
||||
(load "CLI.carp")
|
||||
|
||||
(defndynamic gendocs []
|
||||
(do
|
||||
(Project.config "title" "cli")
|
||||
(Project.config "docs-directory" "./docs/")
|
||||
(Project.config "docs-logo" "")
|
||||
(Project.config "docs-styling" "style.css")
|
||||
(Project.config "docs-generate-index" false)
|
||||
(save-docs CLI)))
|
||||
|
||||
(gendocs)
|
||||
(quit)
|
Reference in New Issue
Block a user