0.8.0

zig-clap release 0.8.0 which compiles and works for zig 0.12.0

Changes

• Remove support for unofficial package managers gyro and zigmod
• Remove the default allocator from clap.ParseOptions

0.7.0

zig-clap release 0.7.0 which compiles and works for zig 0.11.0

Changes

• Multiple occurrences of a flag are now counted.
  • Fields for flag parameters are now type u8 instead of bool.
  • Updating zig-clap will look something like this:

  -    if (arg_result.my_flag)
  +    if (arg_result.my_flag != 0)

Added

• zig-clap now exposes itself as a module in the build script.
• Support for multiple positional parameters.

0.6.0

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>

0.5.0

zig-clap release 0.5.0 which compiles and works for zig 0.9.0

Changes

New

• clap.help now indents each newline in the help string.

Fixes

• Fixed a bug where clap.parse did not forward diagnostics down to the underlying StreamingClap.

0.4.1

Discovered by @omgitsmoe, 0.4.0 had a critical bug in clap.parse.

Changes

Fixes

• Fix nasty allocation error caused by sharing state between two copies of the same arena (#43)
• Set eval quota in clap.parseParam to a high value to avoid having users needing to specify it themselves (#42)

0.4.0

zig-clap release 0.4.0 which compiles and works for zig 0.8.0.

Changes

Breaking

• Arguments after -- will now all be treated like positional arguments, even if they match something else.
  • -a -b gives you the flags a and b
  • -a -- -b gives you the flag a and the positional argument -b.
  • This applies to both clap.StreamingClap and clap.parse.
• clap.parse and clap.parseEx now takes a ParserOptions
  • This removes the allocator and diag arguments from these functions and moves them into this new struct.
  • This change has been made to make it possible to introduce more options to these functions in the future without breaking the API again.
• clap.StreamingClap.next no longer takes the diag argument.
  • Instead, a diagnostic field have been added to this parser.
• All enums have had their members names changed to snake_case.

New

• Added new args.ShellIterator (this might actually have been in 0.3.0 but it wasn't in the release notes 🤷)
  • This iterator takes a single string and splits it into arguments similarly to how sh or bash would.
  • See the tests to get an idea as to how this iterator splits arguments.
• You should now be able to install zig-clap through both gyro and zigmod package managers.
  • zig-clap can also be found on the astrolab package repository.

zig-clap-0.3.0

A new release of zig-clap for zig 0.7.0

Changes

Breaking

• Now compilers with the zig 0.7.0 compiler.
• clap.parse now supports capturing multiple options.
  • To get multiple options your parameters need to have the take_values field be clap.Values.Many.
    • clap.parseParam has syntax for this: clap.parseParam("-s, --ss <V>... This is a help message").
  • The options function can be called to get a slice of all options passed the parameter.
• All parsers now take an extra diagnostic parameter, which can be used to report more useful error messages.
  • The clap.Diagnostic struct has a report method which prints a simple English error message.
    • Use this as a reference if you want to implement error reporting yourself.
  • null can be pass if the caller does not care about this extra information.

New

• clap.parseParam now supports parsing positional parameter help messages.
  • Syntax is as follows: clap.parseParam("<P> This is a positional parameter").
• clap.args.OsIterator now returns null-terminated strings.

Fixes

• No longer gives compile error for 32 bit targets (#23)

zig-clap-0.2.0

A new release of zig-clap for zig 0.6.0

Changes

Breaking

• Now compilers with the zig 0.6.0 compiler.
• Removes the clap.args.Iterator struct in favor of passing the argument iterator type directly to the different parsers.
  • These diffs show the difference between the two API's

    -var os_iter = clap.args.OsIterator.init(allocator);
    -const iter = &os_iter.iter;
    -defer os_iter.deinit();
    +var iter = clap.args.OsIterator.init(allocator);
    +defer iter.deinit();

    -var args = try clap.ComptimeClap([]const u8, params).parse(allocator, clap.args.OsIterator.Error, iter);
    +var args = try clap.ComptimeClap([]const u8, params).parse(allocator, clap.args.OsIterator, &iter);

  • clap.args.OsIterator now also consumes the arg[0] on init and has a field called exe where this argument is stored.
    • This puts this iterator more in line with how all the others are used.
• clap.help and friends now take Param(Help) instead of Param([]const u8)
• clap.help output is now slightly different:

  +    -d, --dd <V3>    Both option.
  -    -d, --dd=V3    Both option.

• - and -- strings will now be interpreted as positional and not as arguments.

New

• Adds clap.parseParam which takes a string similar to what clap.help emits for each parameter and returns a Param(Help)
  • Most users will find this API more convenient than initializing all the fields of Param themself:

     try clap.help(
         stderr,
    -    [_]clap.Param([]const u8){
    -        clap.Param([]const u8){
    -            .id = "Display this help and exit.",
    -            .names = clap.Names{ .short = 'h', .long = "help" },
    -        },
    -        clap.Param([]const u8){
    -            .id = "Output version information and exit.",
    -            .names = clap.Names{ .short = 'v', .long = "version" },
    -        },
    +    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,
        },
     );

• Adds clap.parse. This is the new simplest way of using zig-clap.
• Adds clap.usage. This function takes a slice of Param(Help) and a stream and prints a usage string based on the parameters passed.
  • Just like help this function has an Ex and Full version.

zig-clap-0.1.0

The first release of zig-clap.

Added

• clap.args.Iterator.
  • The common interface for iterating over program arguments.
  • Used by the rest of the library.
• clap.args.SliceIterator
  • An clap.args.Iterator which just iterates over a slice of strings.
• clap.args.OsIterator
  • An clap.args.Iterator which wraps std.os.ArgIterator
  • It iterates over the program arguments the most memory efficient way on each platform.
• clap.StreamingClap
  • A streaming argument parser. which, given a slice of parameters can parse arguments lazily.
  • This parse is used as a backend for other parsers.
• clap.ComptimeClap
  • A parse which uses reflection to generate an efficient way of querying what parameters have been passed, and their values.
• clap.help, clap.helpEx and clap.helpFull
  • Functions for pretty printing parameters.