Add clap.parse as the simplest way of using the lib

1 files changed, 96 insertions, 64 deletions

diff --git a/README.md b/README.md
index 6c556b9..0555a0f 100644
--- a/README.md
+++ b/README.md
@@ -15,10 +15,9 @@ 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
 const std = @import("std");
@@ -27,58 +26,69 @@ const clap = @import("clap");
 const debug = std.debug;
 
 pub fn main() !void {
-    const allocator = std.heap.direct_allocator;
-
     // First we specify what parameters our program can take.
-    const params = [_]clap.Param(u8){
-        clap.Param(u8){
-            .id = 'h',
-            .names = clap.Names{ .short = 'h', .long = "help" },
-        },
-        clap.Param(u8){
-            .id = 'n',
-            .names = clap.Names{ .short = 'n', .long = "number" },
-            .takes_value = true,
-        },
-        clap.Param(u8){
-            .id = 'f',
+    // 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,
         },
     };
 
-    // We then initialize an argument iterator. We will use the OsIterator as it nicely
-    // wraps iterating over arguments the most efficient way on each os.
-    var iter = try clap.args.OsIterator.init(allocator);
-    defer iter.deinit();
+    var args = try clap.parse(clap.Help, params, std.heap.direct_allocator);
+    defer args.deinit();
 
-    // Initialize our streaming parser.
-    var parser = clap.StreamingClap(u8, clap.args.OsIterator){
-        .params = params,
-        .iter = &iter,
+    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);
+}
+
+```
+
+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
+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,
     };
 
-    // Because we use a streaming parser, we have to consume each argument parsed individually.
-    while (try parser.next()) |arg| {
-        // arg.param will point to the parameter which matched the argument.
-        switch (arg.param.id) {
-            'h' => debug.warn("Help!\n"),
-            'n' => debug.warn("--number = {}\n", arg.value.?),
+    var args = try clap.parse(clap.Help, params, std.heap.direct_allocator);
+    defer args.deinit();
 
-            // arg.value == null, if arg.param.takes_value == false.
-            // Otherwise, arg.value is the value passed with the argument, such as "-a=10"
-            // or "-a 10".
-            'f' => debug.warn("{}\n", arg.value.?),
-            else => unreachable,
-        }
-    }
+    _ = args.flag("--helps");
 }
 
 ```
 
+```
+zig-clap/clap/comptime.zig:109:17: error: --helps is not a parameter.
+                @compileError(name ++ " is not a parameter.");
+                ^
+zig-clap/clap/comptime.zig:77:45: note: called from here
+            const param = comptime findParam(name);
+                                            ^
+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");
+```
+
 ### `ComptimeClap`
 
-The `ComptimeClap` is a wrapper for `StreamingClap`, which parses all the arguments and makes
-them available through three functions (`flag`, `option`, `positionals`).
+The `ComptimeClap` is the parser used by `clap.parse`. It allows the user to use a custom argument
+iterator.
 
 ```zig
 const std = @import("std");
@@ -118,46 +128,68 @@ pub fn main() !void {
 
 ```
 
-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:
+### `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
 const std = @import("std");
 const clap = @import("clap");
 
+const debug = std.debug;
+
 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" },
-    }};
+    // First we specify what parameters our program can take.
+    const params = [_]clap.Param(u8){
+        clap.Param(u8){
+            .id = 'h',
+            .names = clap.Names{ .short = 'h', .long = "help" },
+        },
+        clap.Param(u8){
+            .id = 'n',
+            .names = clap.Names{ .short = 'n', .long = "number" },
+            .takes_value = true,
+        },
+        clap.Param(u8){
+            .id = 'f',
+            .takes_value = true,
+        },
+    };
 
-    var iter = clap.args.OsIterator.init(allocator);
+    // We then initialize an argument iterator. We will use the OsIterator as it nicely
+    // wraps iterating over arguments the most efficient way on each os.
+    var iter = try 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();
+    // Initialize our streaming parser.
+    var parser = clap.StreamingClap(u8, clap.args.OsIterator){
+        .params = params,
+        .iter = &iter,
+    };
 
-    _ = args.flag("--helps");
-}
+    // Because we use a streaming parser, we have to consume each argument parsed individually.
+    while (try parser.next()) |arg| {
+        // arg.param will point to the parameter which matched the argument.
+        switch (arg.param.id) {
+            'h' => debug.warn("Help!\n"),
+            'n' => debug.warn("--number = {}\n", arg.value.?),
 
-```
+            // arg.value == null, if arg.param.takes_value == false.
+            // Otherwise, arg.value is the value passed with the argument, such as "-a=10"
+            // or "-a 10".
+            'f' => debug.warn("{}\n", arg.value.?),
+            else => unreachable,
+        }
+    }
+}
 
 ```
-zig-clap/src/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
-            const param = comptime findParam(name);
-                                            ^
-zig-clap/example/comptime-clap-error.zig:18:18: note: called from here
-    _ = args.flag("--helps");
-                 ^
-```
 
-Ofc, this limits you to parameters that are comptime known.
+Currently, this parse is the only parser that allow an array of `Param` that
+is generated at runtime.
 
 ### `help`