6 files changed, 270 insertions, 36 deletions

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 93d00fc..7418c8c 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -4,7 +4,7 @@ jobs:
   test:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
     runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v1
@@ -12,7 +12,7 @@ jobs:
           submodules: recursive
       - uses: goto-bus-stop/setup-zig@v1.0.0
         with:
-          version: 0.5.0
+          version: 0.6.0
       - run: zig build
   lint:
     runs-on: ubuntu-latest
@@ -20,5 +20,5 @@ jobs:
       - uses: actions/checkout@v1
       - uses: goto-bus-stop/setup-zig@v1.0.0
         with:
-          version: 0.5.0
+          version: 0.6.0
       - run: zig fmt --check .
diff --git a/README.md b/README.md
index 642856b..2b38281 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 A simple and easy to use command line argument parser library for Zig.
 
+Looking for a version that works with `zig master`? The `zig-master` branch has
+you covered. It is maintained by people who live at head (not me) and is merged
+into master on every `zig` release.
+
 ## Features
 
 * Short arguments `-a`
@@ -231,3 +235,35 @@ The `helpEx` is the generic version of `help`. It can print a help message for a
 
 The `helpFull` is even more generic, allowing the functions that get the help and value strings
 to return errors and take a context as a parameter.
+
+### `usage`
+
+The `usage`, `usageEx` and `usageFull` are functions for printing a small abbreviated version
+of the help message.
+
+```zig
+const std = @import("std");
+const clap = @import("clap");
+
+pub fn main() !void {
+    const stderr = std.io.getStdErr().outStream();
+
+    // clap.usage is a function that can print a simple usage message, given a
+    // slice of Param(Help). There is also a usageEx, which can print a
+    // usage message for any Param, but it is more verbose to call.
+    try clap.usage(
+        stderr,
+        comptime &[_]clap.Param(clap.Help){
+            clap.parseParam("-h, --help       Display this help and exit.         ") catch unreachable,
+            clap.parseParam("-v, --version    Output version information and exit.") catch unreachable,
+            clap.parseParam("    --value <N>  Output version information and exit.") catch unreachable,
+        },
+    );
+}
+
+```
+
+```
+[-hv] [--value <N>]
+```
+
diff --git a/build.zig b/build.zig
index 6adfbf4..f468fb6 100644
--- a/build.zig
+++ b/build.zig
@@ -32,6 +32,7 @@ pub fn build(b: *Builder) void {
         "comptime-clap",
         "streaming-clap",
         "help",
+        "usage",
     }) |example_name| {
         const example = b.addExecutable(example_name, "example/" ++ example_name ++ ".zig");
         example.addPackagePath("clap", "clap.zig");
@@ -66,6 +67,7 @@ fn readMeStep(b: *Builder) *std.build.Step {
                 @embedFile("example/comptime-clap.zig"),
                 @embedFile("example/streaming-clap.zig"),
                 @embedFile("example/help.zig"),
+                @embedFile("example/usage.zig"),
             });
         }
     }.make);
diff --git a/clap.zig b/clap.zig
index 6ef00a4..ff423cc 100644
--- a/clap.zig
+++ b/clap.zig
@@ -57,10 +57,14 @@ pub fn Param(comptime Id: type) type {
 /// Takes a string and parses it to a Param(Help).
 /// This is the reverse of 'help' but for at single parameter only.
 pub fn parseParam(line: []const u8) !Param(Help) {
+    var z: usize = 0;
     var res = Param(Help){
         .id = Help{
-            .msg = line[0..0],
-            .value = line[0..0],
+            // For testing, i want to be able to easily compare slices just by pointer,
+            // so I slice by a runtime value here, so that zig does not optimize this
+            // out. Maybe I should write the test better, geeh.
+            .msg = line[z..z],
+            .value = line[z..z],
         },
     };
 
@@ -119,6 +123,7 @@ pub fn parseParam(line: []const u8) !Param(Help) {
 }
 
 test "parseParam" {
+    var z: usize = 0;
     var text: []const u8 = "-s, --long <value> Help text";
     testing.expectEqual(Param(Help){
         .id = Help{
@@ -162,7 +167,7 @@ test "parseParam" {
     testing.expectEqual(Param(Help){
         .id = Help{
             .msg = find(text, "Help text"),
-            .value = text[0..0],
+            .value = text[z..z],
         },
         .names = Names{
             .short = 's',
@@ -175,7 +180,7 @@ test "parseParam" {
     testing.expectEqual(Param(Help){
         .id = Help{
             .msg = find(text, "Help text"),
-            .value = text[0..0],
+            .value = text[z..z],
         },
         .names = Names{
             .short = 's',
@@ -188,7 +193,7 @@ test "parseParam" {
     testing.expectEqual(Param(Help){
         .id = Help{
             .msg = find(text, "Help text"),
-            .value = text[0..0],
+            .value = text[z..z],
         },
         .names = Names{
             .short = null,
@@ -265,25 +270,25 @@ pub fn parse(
 }
 
 /// Will print a help message in the following format:
-///     -s, --long <value_text> help_text
-///     -s,                     help_text
-///     -s <value_text>         help_text
-///         --long              help_text
-///         --long <value_text> help_text
+///     -s, --long <valueText> helpText
+///     -s,                    helpText
+///     -s <valueText>         helpText
+///         --long             helpText
+///         --long <valueText> helpText
 pub fn helpFull(
     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,
+    helpText: fn (@TypeOf(context), Param(Id)) Error![]const u8,
+    valueText: fn (@TypeOf(context), Param(Id)) Error![]const u8,
 ) !void {
     const max_spacing = blk: {
         var res: usize = 0;
         for (params) |param| {
             var counting_stream = io.countingOutStream(io.null_out_stream);
-            try printParam(&counting_stream.outStream(), Id, param, Error, context, value_text);
+            try printParam(counting_stream.outStream(), Id, param, Error, context, valueText);
             if (res < counting_stream.bytes_written)
                 res = counting_stream.bytes_written;
         }
@@ -297,9 +302,9 @@ pub fn helpFull(
 
         var counting_stream = io.countingOutStream(stream);
         try stream.print("\t", .{});
-        try printParam(&counting_stream.outStream(), Id, param, Error, context, value_text);
+        try printParam(counting_stream.outStream(), Id, param, Error, context, valueText);
         try stream.writeByteNTimes(' ', max_spacing - counting_stream.bytes_written);
-        try stream.print("\t{}\n", .{ try help_text(context, param) });
+        try stream.print("\t{}\n", .{try helpText(context, param)});
     }
 }
 
@@ -309,10 +314,10 @@ fn printParam(
     param: Param(Id),
     comptime Error: type,
     context: var,
-    value_text: fn (@TypeOf(context), Param(Id)) Error![]const u8,
-) @TypeOf(stream.*).Error!void {
+    valueText: fn (@TypeOf(context), Param(Id)) Error![]const u8,
+) !void {
     if (param.names.short) |s| {
-        try stream.print("-{c}", .{ s });
+        try stream.print("-{c}", .{s});
     } else {
         try stream.print("  ", .{});
     }
@@ -323,31 +328,31 @@ fn printParam(
             try stream.print("  ", .{});
         }
 
-        try stream.print("--{}", .{ l });
+        try stream.print("--{}", .{l});
     }
     if (param.takes_value)
-        try stream.print(" <{}>", .{ value_text(context, param) });
+        try stream.print(" <{}>", .{valueText(context, param)});
 }
 
-/// A wrapper around helpFull for simple help_text and value_text functions that
+/// A wrapper around helpFull for simple helpText and valueText functions that
 /// cant return an error or take a context.
 pub fn helpEx(
     stream: var,
     comptime Id: type,
     params: []const Param(Id),
-    help_text: fn (Param(Id)) []const u8,
-    value_text: fn (Param(Id)) []const u8,
+    helpText: fn (Param(Id)) []const u8,
+    valueText: fn (Param(Id)) []const u8,
 ) !void {
     const Context = struct {
-        help_text: fn (Param(Id)) []const u8,
-        value_text: fn (Param(Id)) []const u8,
+        helpText: fn (Param(Id)) []const u8,
+        valueText: fn (Param(Id)) []const u8,
 
         pub fn help(c: @This(), p: Param(Id)) error{}![]const u8 {
-            return c.help_text(p);
+            return c.helpText(p);
         }
 
         pub fn value(c: @This(), p: Param(Id)) error{}![]const u8 {
-            return c.value_text(p);
+            return c.valueText(p);
         }
     };
 
@@ -357,8 +362,8 @@ pub fn helpEx(
         params,
         error{},
         Context{
-            .help_text = help_text,
-            .value_text = value_text,
+            .helpText = helpText,
+            .valueText = valueText,
         },
         Context.help,
         Context.value,
@@ -417,17 +422,172 @@ test "clap.help" {
     const actual = slice_stream.getWritten();
     if (!mem.eql(u8, actual, expected)) {
         debug.warn("\n============ Expected ============\n", .{});
-        debug.warn("{}", .{ expected });
+        debug.warn("{}", .{expected});
+        debug.warn("============= Actual =============\n", .{});
+        debug.warn("{}", .{actual});
+
+        var buffer: [1024 * 2]u8 = undefined;
+        var fba = std.heap.FixedBufferAllocator.init(&buffer);
+
+        debug.warn("============ Expected (escaped) ============\n", .{});
+        debug.warn("{x}\n", .{expected});
+        debug.warn("============ Actual (escaped) ============\n", .{});
+        debug.warn("{x}\n", .{actual});
+        testing.expect(false);
+    }
+}
+
+/// Will print a usage message in the following format:
+/// [-abc] [--longa] [-d <valueText>] [--longb <valueText>] <valueText>
+///
+/// First all none value taking parameters, which have a short name are
+/// printed, then non positional parameters and finally the positinal.
+pub fn usageFull(
+    stream: var,
+    comptime Id: type,
+    params: []const Param(Id),
+    comptime Error: type,
+    context: var,
+    valueText: fn (@TypeOf(context), Param(Id)) Error![]const u8,
+) !void {
+    var cos = io.countingOutStream(stream);
+    const cs = cos.outStream();
+    for (params) |param| {
+        const name = param.names.short orelse continue;
+        if (param.takes_value)
+            continue;
+
+        if (cos.bytes_written == 0)
+            try stream.writeAll("[-");
+        try cs.writeByte(name);
+    }
+    if (cos.bytes_written != 0)
+        try cs.writeByte(']');
+
+    var positional: ?Param(Id) = null;
+    for (params) |param| {
+        if (!param.takes_value and param.names.short != null)
+            continue;
+
+        const prefix = if (param.names.short) |_| "-" else "--";
+
+        // Seems the zig compiler is being a little wierd. I doesn't allow me to write
+        // @as(*const [1]u8, s)                  VVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
+        const name = if (param.names.short) |*s| @ptrCast([*]const u8, s)[0..1] else param.names.long orelse {
+            positional = param;
+            continue;
+        };
+        if (cos.bytes_written != 0)
+            try cs.writeByte(' ');
+
+        try cs.print("[{}{}", .{ prefix, name });
+        if (param.takes_value)
+            try cs.print(" <{}>", .{try valueText(context, param)});
+
+        try cs.writeByte(']');
+    }
+
+    if (positional) |p| {
+        if (cos.bytes_written != 0)
+            try cs.writeByte(' ');
+        try cs.print("<{}>", .{try valueText(context, p)});
+    }
+}
+
+/// A wrapper around usageFull for a simple valueText functions that
+/// cant return an error or take a context.
+pub fn usageEx(
+    stream: var,
+    comptime Id: type,
+    params: []const Param(Id),
+    valueText: fn (Param(Id)) []const u8,
+) !void {
+    const Context = struct {
+        valueText: fn (Param(Id)) []const u8,
+
+        pub fn value(c: @This(), p: Param(Id)) error{}![]const u8 {
+            return c.valueText(p);
+        }
+    };
+
+    return usageFull(
+        stream,
+        Id,
+        params,
+        error{},
+        Context{ .valueText = valueText },
+        Context.value,
+    );
+}
+
+/// A wrapper around usageEx that takes a Param(Help).
+pub fn usage(stream: var, params: []const Param(Help)) !void {
+    try usageEx(stream, Help, params, getValueSimple);
+}
+
+fn testUsage(expected: []const u8, params: []const Param(Help)) !void {
+    var buf: [1024]u8 = undefined;
+    var fbs = io.fixedBufferStream(&buf);
+    try usage(fbs.outStream(), params);
+
+    const actual = fbs.getWritten();
+    if (!mem.eql(u8, actual, expected)) {
+        debug.warn("\n============ Expected ============\n", .{});
+        debug.warn("{}\n", .{expected});
         debug.warn("============= Actual =============\n", .{});
-        debug.warn("{}", .{ actual });
+        debug.warn("{}\n", .{actual});
 
         var buffer: [1024 * 2]u8 = undefined;
         var fba = std.heap.FixedBufferAllocator.init(&buffer);
 
         debug.warn("============ Expected (escaped) ============\n", .{});
-        debug.warn("{x}\n", .{ expected });
+        debug.warn("{x}\n", .{expected});
         debug.warn("============ Actual (escaped) ============\n", .{});
-        debug.warn("{x}\n", .{ actual });
+        debug.warn("{x}\n", .{actual});
         testing.expect(false);
     }
 }
+
+test "usage" {
+    @setEvalBranchQuota(100000);
+    try testUsage("[-ab]", comptime &[_]Param(Help){
+        parseParam("-a") catch unreachable,
+        parseParam("-b") catch unreachable,
+    });
+    try testUsage("[-a <value>] [-b <v>]", comptime &[_]Param(Help){
+        parseParam("-a <value>") catch unreachable,
+        parseParam("-b <v>") catch unreachable,
+    });
+    try testUsage("[--a] [--b]", comptime &[_]Param(Help){
+        parseParam("--a") catch unreachable,
+        parseParam("--b") catch unreachable,
+    });
+    try testUsage("[--a <value>] [--b <v>]", comptime &[_]Param(Help){
+        parseParam("--a <value>") catch unreachable,
+        parseParam("--b <v>") catch unreachable,
+    });
+    try testUsage("<file>", comptime &[_]Param(Help){
+        Param(Help){
+            .id = Help{
+                .value = "file",
+            },
+            .takes_value = true,
+        },
+    });
+    try testUsage("[-ab] [-c <value>] [-d <v>] [--e] [--f] [--g <value>] [--h <v>] <file>", comptime &[_]Param(Help){
+        parseParam("-a") catch unreachable,
+        parseParam("-b") catch unreachable,
+        parseParam("-c <value>") catch unreachable,
+        parseParam("-d <v>") catch unreachable,
+        parseParam("--e") catch unreachable,
+        parseParam("--f") catch unreachable,
+        parseParam("--g <value>") catch unreachable,
+        parseParam("--h <v>") catch unreachable,
+        Param(Help){
+            .id = Help{
+                .value = "file",
+            },
+            .takes_value = true,
+        },
+    });
+}
diff --git a/example/README.md.template b/example/README.md.template
index 1fd90b0..2afbe86 100644
--- a/example/README.md.template
+++ b/example/README.md.template
@@ -2,6 +2,10 @@
 
 A simple and easy to use command line argument parser library for Zig.
 
+Looking for a version that works with `zig master`? The `zig-master` branch has
+you covered. It is maintained by people who live at head (not me) and is merged
+into master on every `zig` release.
+
 ## Features
 
 * Short arguments `-a`
@@ -87,3 +91,17 @@ The `helpEx` is the generic version of `help`. It can print a help message for a
 
 The `helpFull` is even more generic, allowing the functions that get the help and value strings
 to return errors and take a context as a parameter.
+
+### `usage`
+
+The `usage`, `usageEx` and `usageFull` are functions for printing a small abbreviated version
+of the help message.
+
+```zig
+{}
+```
+
+```
+[-hv] [--value <N>]
+```
+
diff --git a/example/usage.zig b/example/usage.zig
new file mode 100644
index 0000000..25e1a34
--- /dev/null
+++ b/example/usage.zig
@@ -0,0 +1,18 @@
+const std = @import("std");
+const clap = @import("clap");
+
+pub fn main() !void {
+    const stderr = std.io.getStdErr().outStream();
+
+    // clap.usage is a function that can print a simple usage message, given a
+    // slice of Param(Help). There is also a usageEx, which can print a
+    // usage message for any Param, but it is more verbose to call.
+    try clap.usage(
+        stderr,
+        comptime &[_]clap.Param(clap.Help){
+            clap.parseParam("-h, --help       Display this help and exit.         ") catch unreachable,
+            clap.parseParam("-v, --version    Output version information and exit.") catch unreachable,
+            clap.parseParam("    --value <N>  Output version information and exit.") catch unreachable,
+        },
+    );
+}