initial release

This commit is contained in:
2020-01-29 17:51:57 +01:00
parent d36a768b15
commit 1a998a7960
5 changed files with 484 additions and 5 deletions

View File

@@ -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>)
```
Youll 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 youre 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!

View File

@@ -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>)
```
Youll 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 youre 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. Its 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 dont 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
View 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 &quot;https://veitheller.de/git/carpentry/cli@0.0.1&quot;)
(defn main []
(let [p (=&gt; (CLI.new @&quot;My super cool tool!&quot;)
(CLI.add &amp;(CLI.int &quot;flag&quot; &quot;f&quot; &quot;my flag&quot; true))
(CLI.add &amp;(CLI.str &quot;thing&quot; &quot;t&quot; &quot;my thing&quot; false @&quot;hi&quot; &amp;[@&quot;a&quot; @&quot;b&quot; @&quot;hi&quot;])))]
(match (CLI.parse &amp;p)
(Result.Success flags)
(println* &amp;(str &amp;(Map.get &amp;flags &quot;flag&quot;)) &quot; &quot; &amp;(str &amp;(Map.get &amp;flags &quot;thing&quot;)))
(Result.Error msg) (do (IO.errorln &amp;msg) (CLI.usage &amp;p)))))
</code></pre>
<h2>Installation</h2>
<pre><code class="language-clojure">(load &quot;https://veitheller.de/git/carpentry/cli@0.0.1&quot;)
</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 &lt;long&gt; &lt;short&gt; &lt;description&gt; &lt;required?&gt;)
; or
(CLI.int &lt;long&gt; &lt;short&gt; &lt;description&gt; &lt;required?&gt; &lt;default&gt;)
; or
(CLI.int &lt;long&gt; &lt;short&gt; &lt;description&gt; &lt;required?&gt; &lt;default&gt; &lt;options-array&gt;)
</code></pre>
<p>Youll 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 youre 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 dont 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
View 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
View 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)