From 1a219fc680faa79f1236912b14fd58754313df87 Mon Sep 17 00:00:00 2001 From: Jimmi Holst Christensen Date: Thu, 15 Nov 2018 12:53:46 +0100 Subject: Added help function --- README.md | 73 ++++++++++++++++++++++++ example/comptime-clap.zig | 35 ++++++------ example/streaming-clap.zig | 10 ---- src/index.zig | 134 +++++++++++++++++++++++++++++++++++++++++++++ 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; + } +} -- cgit v1.2.3