From a305e818bd986c599fff17141617bc4f890276cf Mon Sep 17 00:00:00 2001
From: Jimmi Holst Christensen
Date: Wed, 27 Nov 2019 23:13:31 +0900
Subject: Add clap.parse as the simplest way of using the lib

---
 example/README.md.template      | 50 ++++++++++++++++++++++++-----------------
 example/comptime-clap-error.zig | 19 ----------------
 example/simple-error.zig        | 15 +++++++++++++
 example/simple.zig              | 26 +++++++++++++++++++++
 4 files changed, 71 insertions(+), 39 deletions(-)
 delete mode 100644 example/comptime-clap-error.zig
 create mode 100644 example/simple-error.zig
 create mode 100644 example/simple.zig

(limited to 'example')

diff --git a/example/README.md.template b/example/README.md.template
index 373a037..1fd90b0 100644
--- a/example/README.md.template
+++ b/example/README.md.template
@@ -15,45 +15,55 @@ A simple and easy to use command line argument parser library for Zig.
 
 ## Examples
 
-### `StreamingClap`
+### `clap.parse`
 
-The `StreamingClap` is the base of all the other parsers. It's a streaming parser that uses an
-`args.Iterator` to provide it with arguments lazily.
+The simplest way to use this library is to just call the `clap.parse` function.
 
 ```zig
 {}
 ```
 
-### `ComptimeClap`
-
-The `ComptimeClap` is a wrapper for `StreamingClap`, which parses all the arguments and makes
-them available through three functions (`flag`, `option`, `positionals`).
-
-```zig
-{}
-```
-
-The data structure returned from this parser has lookup speed on par with array access (`arr[i]`)
-and validates that the strings you pass to `option` and `flag` are actually parameters that the
-program can take:
+The data structure returned has lookup speed on par with array access (`arr[i]`) and validates
+that the strings you pass to `option` and `flag` are actually parameters that the program can take:
 
 ```zig
 {}
 ```
 
 ```
-zig-clap/src/comptime.zig:109:17: error: --helps is not a parameter.
+zig-clap/clap/comptime.zig:109:17: error: --helps is not a parameter.
                 @compileError(name ++ " is not a parameter.");
                 ^
-zig-clap/src/comptime.zig:77:45: note: called from here
+zig-clap/clap/comptime.zig:77:45: note: called from here
             const param = comptime findParam(name);
                                             ^
-zig-clap/example/comptime-clap-error.zig:18:18: note: called from here
+zig-clap/clap.zig:238:31: note: called from here
+            return a.clap.flag(name);
+                              ^
+zig-clap/example/simple-error.zig:16:18: note: called from here
     _ = args.flag("--helps");
-                 ^
 ```
 
-Ofc, this limits you to parameters that are comptime known.
+### `ComptimeClap`
+
+The `ComptimeClap` is the parser used by `clap.parse`. It allows the user to use a custom argument
+iterator.
+
+```zig
+{}
+```
+
+### `StreamingClap`
+
+The `StreamingClap` is the base of all the other parsers. It's a streaming parser that uses an
+`args.Iterator` to provide it with arguments lazily.
+
+```zig
+{}
+```
+
+Currently, this parse is the only parser that allow an array of `Param` that
+is generated at runtime.
 
 ### `help`
 
diff --git a/example/comptime-clap-error.zig b/example/comptime-clap-error.zig
deleted file mode 100644
index 3209b74..0000000
--- a/example/comptime-clap-error.zig
+++ /dev/null
@@ -1,19 +0,0 @@
-const std = @import("std");
-const clap = @import("clap");
-
-pub fn main() !void {
-    const allocator = std.heap.direct_allocator;
-
-    const params = [_]clap.Param(void){clap.Param(void){
-        .names = clap.Names{ .short = 'h', .long = "help" },
-    }};
-
-    var iter = clap.args.OsIterator.init(allocator);
-    defer iter.deinit();
-    const exe = try iter.next();
-
-    var args = try clap.ComptimeClap(void, params).parse(allocator, clap.args.OsIterator, &iter);
-    defer args.deinit();
-
-    _ = args.flag("--helps");
-}
diff --git a/example/simple-error.zig b/example/simple-error.zig
new file mode 100644
index 0000000..fc72a03
--- /dev/null
+++ b/example/simple-error.zig
@@ -0,0 +1,15 @@
+const std = @import("std");
+const clap = @import("clap");
+
+pub fn main() !void {
+    // First we specify what parameters our program can take.
+    // We can use `parseParam` to parse a string to a `Param(Help)`
+    const params = comptime [_]clap.Param(clap.Help){
+        clap.parseParam("-h, --help  Display this help and exit.") catch unreachable,
+    };
+
+    var args = try clap.parse(clap.Help, params, std.heap.direct_allocator);
+    defer args.deinit();
+
+    _ = args.flag("--helps");
+}
diff --git a/example/simple.zig b/example/simple.zig
new file mode 100644
index 0000000..f791447
--- /dev/null
+++ b/example/simple.zig
@@ -0,0 +1,26 @@
+const std = @import("std");
+const clap = @import("clap");
+
+const debug = std.debug;
+
+pub fn main() !void {
+    // First we specify what parameters our program can take.
+    // We can use `parseParam` to parse a string to a `Param(Help)`
+    const params = comptime [_]clap.Param(clap.Help){
+        clap.parseParam("-h, --help          Display this help and exit.              ") catch unreachable,
+        clap.parseParam("-n, --number <NUM>  An option parameter, which takes a value.") catch unreachable,
+        clap.Param(clap.Help){
+            .takes_value = true,
+        },
+    };
+
+    var args = try clap.parse(clap.Help, params, std.heap.direct_allocator);
+    defer args.deinit();
+
+    if (args.flag("--help"))
+        debug.warn("--help\n");
+    if (args.option("--number")) |n|
+        debug.warn("--number = {}\n", n);
+    for (args.positionals()) |pos|
+        debug.warn("{}\n", pos);
+}
-- 
cgit v1.2.3