Hejsil/zig-clap 0.6.0

on GitHub

zig-clap release 0.6.0 which compiles and works for zig 0.10.0

Changes

• zig-clap is now under the MIT license instead of Unlicense #64

• Refactor the clap.ArgIterator interface to be the same interface as std.process.ArgIterator

• clap.StreamingClap has been moved to clap.streaming.Clap

• clap.parseParam can now parse a parameter spanning multiple lines and is overall more robust than before.

• clap.parse and clap.parseEx has had their return type changed. Instead of returning a struct with .flag, .option, .options and .positionals methods, it now just returns a struct with fields for each parameter your program takes.

  • clap.parse and clap.parseEx takes an additional argument, which use used to lookup the parser that should be used for each parameter.
  • Updating zig-clap will look something like this:

  -    var args = clap.parse(clap.Help, &params, .{
  +    var args = clap.parse(clap.Help, &params, clap.parsers.default, .{

  -    if (args.flag("--help"))
  +    if (args.args.help)
           debug.print("--help\n", .{});
  -    if (args.option("--number")) |n|
  -        debug.print("--number = {s}\n", .{n});
  -    for (args.options("--string")) |s|
  +    if (args.args.number) |n|
  +        debug.print("--number = {}\n", .{n});
  +    for (args.args.string) |s|
           debug.print("--string = {s}\n", .{s});
  -    for (args.positionals()) |pos|
  +    for (args.positionals) |pos|
           debug.print("{s}\n", .{pos});
   }
  

• clap.help and clap.usage are now generic and expect the Id in Param(Id) to provide getters for description and value. Usage of clap.help and clap.usage require the following change:

  -    try help(stream, params);
  +    try help(stream, clap.Help, params);
  -    try usage(stream, params);
  +    try usage(stream, clap.Help, params);

• clap.help now also takes an option parameter that configures how the parameters should be formatted. You can leave it empty for a good default:

  -    try help(stream, clap.Help, params);
  +    try help(stream, clap.Help, params, .{});

Added

• clap.parseParamEx which is the same as clap.parseParam, but takes a pointer to end and sets that to the latest byte parsed before returning either an error or a value.
• clap.parseParams and clap.parseParamsEx which parse a string into a slice of multiple parameters.
• clap.parseParamsIntoSlice and clap.parseParamsIntoSliceEx which parse a string into multiple parameters, which are stored into a slice passed in by the caller.
• clap.parseParamsIntoArrayList and clap.parseParamsIntoArrayListEx which parse a string into multiple parameters, which are stored into an ArrayList passed in by the caller.
• clap.parseParamsComptime which parse a string into a slice of multiple parameters at compile time, returning a fixes size array.
  • This is the new "most convenient way" of specifying your parameters in zig-clap. The following change is recommended, but not necessary.

  -    const params = comptime [_]clap.Param(clap.Help){
  -        clap.parseParam("-h, --help             Display this help and exit.") catch unreachable,
  -        clap.parseParam("-n, --number <usize>   An option parameter, which takes a value.") catch unreachable,
  -        clap.parseParam("-s, --string <str>...  An option parameter which can be specified multiple times.") catch unreachable,
  -        clap.parseParam("<str>...") catch unreachable,
  -    };
  +    const params = comptime clap.parseParamsComptime(
  +        \\-h, --help
  +        \\        Display this help and exit.
  +        \\-n, --number <usize>
  +        \\        An option parameter, which takes a value.
  +        \\-s, --string <str>...
  +        \\        An option parameter which can be specified multiple times.
  +        \\<str>...
  +        \\
  +    );

Removed

• clap.args.OsIterator. Use std.process.ArgIterator instead
• args.ShellIterator. Use std.process.ArgIteratorGeneral instead
• clap.ComptimeClap. Use clap.parse and clap.parseEx instead
• clap.helpEx, clap.helpFull. Implement the description and value methods on your Id and use clap.help instead
• clap.usageEx, clap.usageFull. Implement the description and value methods on your Id and use clap.help instead

Fixes

• clap.usage now prints many value positional parameters correctly as <file>... instead of <file>