Added help function

4 files changed, 226 insertions, 26 deletions

diff --git a/README.md b/README.md
index 68970d9..cb6a7b0 100644
--- a/README.md
+++ b/README.md
@@ -107,3 +107,76 @@ zig-clap/example/comptime-clap.zig:41:18: note: called from here
 ```
 
 Ofc, this limits you to use only parameters that are comptime known.
+
+### `help`
+
+The `help` and `helpEx` are functions for printing a simple list of all parameters the
+program can take.
+
+```rust
+const stderr_file = try std.io.getStdErr();
+var stderr_out_stream = stderr_file.outStream();
+const stderr = &stderr_out_stream.stream;
+
+try clap.help(
+    stderr,
+    []clap.Param([]const u8){
+        clap.Param([]const u8).flag(
+            "Display this help and exit.",
+            clap.Names.prefix("help"),
+        ),
+        clap.Param([]const u8).flag(
+            "Output version information and exit.",
+            clap.Names.prefix("version"),
+        ),
+    },
+);
+```
+
+```
+        -h, --help      Display this help and exit.
+        -v, --version   Output version information and exit.
+```
+
+The `help` function is the simplest to call. It only takes an `OutStream` and a slice of
+`Param([]const u8)`. This function assumes that the id of each parameter is the help message.
+
+The `clap.helpEx` is the generic version of `help`. It can print a help message for any
+`Param`, but requires some extra arguments for it to work.
+
+```rust
+fn getHelp(_: void, param: clap.Param(u8)) error{}![]const u8 {
+    return switch (param.id) {
+        'h' => "Display this help and exit.",
+        'v' => "Output version information and exit.",
+        else => unreachable,
+    };
+}
+
+fn getValue(_: void, param: clap.Param(u8)) error{}![]const u8 {
+    return "";
+}
+
+const stderr_file = try std.io.getStdErr();
+var stderr_out_stream = stderr_file.outStream();
+const stderr = &stderr_out_stream.stream;
+
+try stderr.print("\n");
+try clap.helpEx(
+    stderr,
+    u8,
+    []clap.Param(u8){
+        clap.Param(u8).flag('h', clap.Names.prefix("help")),
+        clap.Param(u8).flag('v', clap.Names.prefix("version")),
+    },
+    error{},
+    {},
+    getHelp,
+    getValue,
+);
+```
+
+```
+        -h, --help      Display this help and exit.
+        -v, --version   Output version information and exit.
+```
diff --git a/example/comptime-clap.zig b/example/comptime-clap.zig
index 3b7b42b..b275dc7 100644
--- a/example/comptime-clap.zig
+++ b/example/comptime-clap.zig
@@ -4,25 +4,25 @@ const clap = @import("clap");
 const debug = std.debug;
 
 pub fn main() !void {
+    const stdout_file = try std.io.getStdOut();
+    var stdout_out_stream = stdout_file.outStream();
+    const stdout = &stdout_out_stream.stream;
+
     var direct_allocator = std.heap.DirectAllocator.init();
     const allocator = &direct_allocator.allocator;
     defer direct_allocator.deinit();
 
     // First we specify what parameters our program can take.
-    const params = comptime []clap.Param(void){
-        // Param.init takes 3 arguments.
-        // * An "id", which can be any type specified by the argument to Param. The
-        //   ComptimeClap expects clap.Param(void) only.
-        // * A bool which determins wether the parameter takes a value.
-        // * A "Names" struct, which determins what names the parameter will have on the
-        //   commandline. Names.prefix inits a "Names" struct that has the "short" name
-        //   set to the first letter, and the "long" name set to the full name.
-        clap.Param(void).flag({}, clap.Names.prefix("help")),
-        clap.Param(void).option({}, clap.Names.prefix("number")),
-
-        // Names.positional returns a "Names" struct where neither the "short" or "long"
-        // name is set.
-        clap.Param(void).positional({}),
+    const params = comptime []clap.Param([]const u8){
+        clap.Param([]const u8).flag(
+            "Display this help and exit.",
+            clap.Names.prefix("help")
+        ),
+        clap.Param([]const u8).option(
+            "An option parameter, which takes a value.",
+            clap.Names.prefix("number"),
+        ),
+        clap.Param([]const u8).positional(""),
     };
 
     // We then initialize an argument iterator. We will use the OsIterator as it nicely
@@ -35,11 +35,14 @@ pub fn main() !void {
     const exe = try iter.next();
 
     // Finally we can parse the arguments
-    var args = try clap.ComptimeClap(void, params).parse(allocator, clap.args.OsIterator.Error, iter);
+    var args = try clap.ComptimeClap([]const u8, params).parse(allocator, clap.args.OsIterator.Error, iter);
     defer args.deinit();
 
+    // clap.help is a function that can print a simple help message, given a
+    // slice of Param([]const u8). There is also a helpEx, which can print a
+    // help message for any Param, but it is more verbose to call.
     if (args.flag("--help"))
-        debug.warn("Help!\n");
+        return try clap.help(stdout, params);
     if (args.option("--number")) |n|
         debug.warn("--number = {}\n", n);
     for (args.positionals()) |pos|
diff --git a/example/streaming-clap.zig b/example/streaming-clap.zig
index 013c1d4..57ebe71 100644
--- a/example/streaming-clap.zig
+++ b/example/streaming-clap.zig
@@ -10,18 +10,8 @@ pub fn main() !void {
 
     // First we specify what parameters our program can take.
     const params = []clap.Param(u8){
-        // Param.init takes 3 arguments.
-        // * An "id", which can be any type specified by the argument to Param. Here, we
-        //   use a "u8" as the "id" type.
-        // * A bool which determins wether the parameter takes a value.
-        // * A "Names" struct, which determins what names the parameter will have on the
-        //   commandline. Names.prefix inits a "Names" struct that has the "short" name
-        //   set to the first letter, and the "long" name set to the full name.
         clap.Param(u8).flag('h', clap.Names.prefix("help")),
         clap.Param(u8).option('n', clap.Names.prefix("number")),
-
-        // Names.positional returns a "Names" struct where neither the "short" or "long"
-        // name is set.
         clap.Param(u8).positional('f'),
     };
 
diff --git a/src/index.zig b/src/index.zig
index 225eb9c..0914176 100644
--- a/src/index.zig
+++ b/src/index.zig
@@ -1,6 +1,8 @@
 const std = @import("std");
 
 const debug = std.debug;
+const io = std.io;
+const mem = std.mem;
 
 pub const @"comptime" = @import("comptime.zig");
 pub const args = @import("args.zig");
@@ -106,3 +108,135 @@ pub fn Param(comptime Id: type) type {
         }
     };
 }
+
+/// Will print a help message in the following format:
+///     -s, --long=value_text help_text
+///     -s,                   help_text
+///         --long            help_text
+pub fn helpEx(
+    stream: var,
+    comptime Id: type,
+    params: []const Param(Id),
+    comptime Error: type,
+    context: var,
+    help_text: fn(@typeOf(context), Param(Id)) Error![]const u8,
+    value_text: fn(@typeOf(context), Param(Id)) Error![]const u8,
+) !void {
+    const max_spacing = blk: {
+        var null_stream = io.NullOutStream.init();
+        var res: usize = 0;
+        for (params) |param| {
+            var counting_stream = io.CountingOutStream(io.NullOutStream.Error).init(&null_stream.stream);
+            try printParam(&counting_stream.stream, Id, param, Error, context, value_text);
+            if (res < counting_stream.bytes_written)
+                res = counting_stream.bytes_written;
+        }
+
+        break :blk res;
+    };
+
+    for (params) |param| {
+        if (param.names.short == null and param.names.long == null)
+            continue;
+
+        var counting_stream = io.CountingOutStream(@typeOf(stream.*).Error).init(stream);
+        try stream.print("\t");
+        try printParam(&counting_stream.stream, Id, param, Error, context, value_text);
+        try stream.writeByteNTimes(' ', max_spacing - counting_stream.bytes_written);
+        try stream.print("\t{}\n", try help_text(context, param));
+    }
+}
+
+fn printParam(
+    stream: var,
+    comptime Id: type,
+    param: Param(Id),
+    comptime Error: type,
+    context: var,
+    value_text: fn(@typeOf(context), Param(Id)) Error![]const u8,
+) @typeOf(stream.*).Error!void {
+    if (param.names.short) |s| {
+        try stream.print("-{c}", s);
+    } else {
+        try stream.print("  ");
+    }
+    if (param.names.long) |l| {
+        if (param.names.short) |_| {
+            try stream.print(", ");
+        } else {
+            try stream.print("  ");
+        }
+
+        try stream.print("--{}", l);
+    }
+    if (param.takes_value)
+        try stream.print("={}", value_text(context, param));
+}
+
+/// A wrapper around helpEx that takes a Param([]const u8) and uses the string id
+/// as the help text for each paramter.
+pub fn help(stream: var, params: []const Param([]const u8)) !void {
+    try helpEx(stream, []const u8, params, error{}, {}, getHelpSimple, getValueSimple);
+}
+
+fn getHelpSimple(context: void, param: Param([]const u8)) error{}![]const u8 {
+    return param.id;
+}
+
+fn getValueSimple(context: void, param: Param([]const u8)) error{}![]const u8 {
+    return "VALUE";
+}
+
+
+test "clap.help" {
+    var buf: [1024]u8 = undefined;
+    var slice_stream = io.SliceOutStream.init(buf[0..]);
+    try help(
+        &slice_stream.stream,
+        []Param([]const u8){
+            Param([]const u8).flag(
+                "Short flag.",
+                Names.short('a'),
+            ),
+            Param([]const u8).option(
+                "Short option.",
+                Names.short('b'),
+            ),
+            Param([]const u8).flag(
+                "Long flag.",
+                Names.long("aa"),
+            ),
+            Param([]const u8).option(
+                "Long option.",
+                Names.long("bb"),
+            ),
+            Param([]const u8).flag(
+                "Both flag.",
+                Names.prefix("cc"),
+            ),
+            Param([]const u8).option(
+                "Both option.",
+                Names.prefix("dd"),
+            ),
+            Param([]const u8).positional(
+                "Positional. This should not appear in the help message."
+            ),
+        },
+    );
+
+    const expected =
+        "\t-a            \tShort flag.\n" ++
+        "\t-b=VALUE      \tShort option.\n" ++
+        "\t    --aa      \tLong flag.\n" ++
+        "\t    --bb=VALUE\tLong option.\n" ++
+        "\t-c, --cc      \tBoth flag.\n" ++
+        "\t-d, --dd=VALUE\tBoth option.\n";
+
+    if (!mem.eql(u8, slice_stream.getWritten(), expected)) {
+        debug.warn("============ Expected ============\n");
+        debug.warn("{}", expected);
+        debug.warn("============= Actual =============\n");
+        debug.warn("{}", slice_stream.getWritten());
+        return error.NoMatch;
+    }
+}