initial release

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!

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]
+  (doc str "creates a string option.")
-    (CLI.option- t long short description required default-options))
-
   (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)
+                    (set! res (Result.Error @""))
-                    (System.exit 0))
+                    (break))
                 (do
                   (set! res (Result.Error (fmt "Unknown option: %s" x)))
                   (break))))

docs/CLI.html

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

docs/style.css

@@ -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; }

gendocs.carp

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