What's Changed

• Update to be compatible with zig v0.14.0
• Update to be compatible with zig master branch by @max-legrand in #29

New Contributors

• @max-legrand made their first contribution in #29

Fixed an Overflow error when printing a help message when the length of an argument name is more than 9 characters.

Fix: Don't panic if examples directory is missing when running zig build.

What's New

• Added new Arg.setValuePlaceholder() to display option's value placeholder in help message. For e.x.: -t, --time=<SECS>.
• Added new .help_on_empty_args property for a command which, when set, a help message is automatically displayed when arguments are not provided.

Before:

if (!matches.containsArgs()) {
    try app.displayHelp();
    return;
}

if (matches.subcommandMatches("update")) |update_cmd_matches| {
    if (!update_cmd_matches.containsArgs()) {
        try app.displaySubcommandHelp();
        return;
    }
}

After:

var app = App.init(allocator, "myls", "My custom ls");
defer app.deinit();

var myls = app.rootCommand();
myls.setProperty(.help_on_empty_args);

var update_cmd = app.createCommand("update", "Update the app or check for new updates");
update_cmd.setProperty(.help_on_empty_args);

try myls.addSubcommand(update_cmd);

const matches = try myls.parseProcess();

// --snip--

Note that App.displayHelp() and App.displaySubcommandHelp() are still available.

• Improved error messages.
• Polished help message.

What's Changed

• App.parseProcess() and App.parseFrom() now returns ArgMatches directly instead of *const ArgMatches.
• Add const qualifier in Command.addArgs and Command.addSubcommands. By @monomycelium in #21
• Fix: Arg.multiValuesOption behavior when single value is provided by @fardragon in #26
• Fix: compiler crash during zig build test by @fardragon in 8f53fcb
• Fix: subcommands with no values will never match #23. With this change, ArgMatches.subcommandMatches() now returns empty matches for any subcommand that doesn't take argument.
• Fix: disable printing error messages during test.

Internal Improvements

• The parser implementation has been polished to make it easier to contribute by adding inline comments where necessary.
• Error handling has been enhanced.
• Improved the help message writer's implementation.
• Overall documentation is improved.

New Contributors

• @monomycelium made their first contribution in #21
• @fardragon made their first contribution in #26

Full Changelog: v0.5.1...v0.6.0

A compatible update for zig v0.12.0, v0.12.1 and  v0.13.0.

Fix

• getOutputDocs was renamed to getEmittedDocs by @karlseguin in #13
• Latest zig requires immutable vars to be const by @karlseguin in #15
• std.os.WriteError -> std.posix.WriteError by @cdmistman in #19
• Minor fix for code example by @higuoxing in #5

What's Changed

• Update to zig 0.12.0-dev.2063+804cee3b9 by @KNnut in #16
• Add build.zig.zon by @dasimmet in #17

New Contributors

• @karlseguin made their first contribution in #13
• @KNnut made their first contribution in #16
• @dasimmet made their first contribution in #17
• @joshua-software-dev made their first contribution in #18
• @cdmistman made their first contribution in #19
• @higuoxing made their first contribution in #5

Breaking Changes

flag Changes

• Moved and Renamed boolean() to Arg.booleanOption().

• Moved and Renamed argOne() to Arg.singleValueOption().

• Moved and Renamed argN() to Arg.multiValuesOption() with slightly
  modified parameter order.

  Old

  fn(name: []const u8, short_name: ?u8, max_values: usize, description: ?[]const u8) Arg;

  New

  fn(name: []const u8, short_name: ?u8, description: ?[]const u8, max_values: usize) Arg;

• Moved and Renamed option() to Arg.singleValueOptionWithValidValues() with
  slightly modified parameter order.

  Old

  fn(name: []const u8, short_name: ?u8, values: []const []const u8, description: ?[]const u8);

  New

  fn(name: []const u8, short_name: ?u8, description: ?[]const u8, values: []const []const u8);

Examples

Before:

const flag = yazap.flag

// -- snip --
try root.addArg(flag.boolean("bool", null, null));
try root.addArg(flag.argOne("one", null, null));
try root.addArg(flag.argN("many", null, 2, null));
try root.addArg(flag.option("opt", null, &[_][]const u8 {
    "opt1",
    "opt2",
}, null));
// -- snip --

After:

const Arg = yazap.Arg

// -- snip --
try root.addArg(Arg.booleanOption("bool", null, null));
try root.addArg(Arg.singleValueOption("one", null, null));
try root.addArg(Arg.multiValuesOption("many", null, null, 2));
try root.addArg(Arg.singleValueOptionWithValidValues("opt", null, null, &[_][]const u8 {
    "opt1",
    "opt2",
}));
// -- snip --

Command Changes

• Renamed countArgs() to countPositionalArgs().
• Renamed setSetting() to setProperty().
• Renamed unsetSetting() to unsetProperty().
• Renamed isSettingSet() to hasProperty().
• Removed takesSingleValue() and takesNValues(), use new Arg.positional()
  instead.

Arg Changes

• Renamed allowed_values to valid_values.
• Renamed setAllowedValues() to setValidValues().
• Renamed setSetting() to setProperty().
• Renamed unsetSetting() to unsetProperty().
• Renamed isSettingSet() to hasProperty().
• Removed setShortNameFromName().
• Removed setNameAsLongName().

ArgsContext Changes

• Renamed ArgsContext to ArgMatches.
• Renamed isPresent() to containsArg().
• Renamed valueOf() to getSingleValue().
• Renamed valuesOf() to getMultiValues().
• Renamed subcommandContext() to subcommandMatches().

What's New

• Introduced Arg.multiValuesOptionWithValidValues() API to support creating an argument that can take multiple arguments
  from pre-defined values.

• Introduced Arg.positional() API, eliminating the need to set the .takes_positional_arg property for commands. This simplifies the
  process of creating positional arguments.

  Before

  var root = app.rootCommand();
  
  try root.takesSingleValue("ONE");
  try root.takesSingleValue("TWO");
  try root.takesSingleValue("THREE");
  root.setSetting(.takes_positional_arg);

  After

  const Arg = yazap.Arg;
  
  var root = app.rootCommand();
  
  // Arg.positional(name: []const u8, description: ?[]const u8, index: ?usize)
  
  // Order dependent
  try root.addArg(Arg.positional("ONE", null, null));
  try root.addArg(Arg.positional("TWO", null, null));
  try root.addArg(Arg.positional("THREE", null, null));
  
  // Equivalent but order independent
  try root.addArg(Arg.positional("THREE", null, 3));
  try root.addArg(Arg.positional("TWO", null, 2));
  try root.addArg(Arg.positional("ONE", null, 1));

• Enhanced documentation for App.* API with detailed explanations and examples.

• Enhanced documentation for Arg.* API with detailed explanations and examples.

• Enhanced documentation for Command.* API with detailed explanations and examples.

Internal Changes

• Removed enable_help property for commands, making -h and --help options
  always available for both the root command and subcommands.

What's new:

• Added Yazap.displayHelp and Yazap.displaySubcommandHelp to manually display root command help and provided subcommand help respectively
• Added Command.addArgs and Command.addSubcommands

Breaking changes:

• Command.takesValue, Command.argRequired, Command.subcommandRequired,
  Arg.takesValue, Arg.takesMultipleValues and Arg.allowedEmptyValue is removed and now you have to use applySetting and removeSetting to set and unset setting
  Ex:

  var app = Yazap.init(allocator, "app", null);
  defer app.deinit();
  
  var cmd = app.rootCommand();
  cmd.applySetting(.takes_value);

Fixes:

• Fixed v0.10.0 optional specifier error messaged (#6)
• Now parsing will be stop after encountering help option (-h or --help)

What's new:

• Added new Yazap as a main entry point for library. (b3a78ad)

  Now you have to use Yazap.init to initialize the library and Yazap.deinit to deinitilize all the structures at once. Previously you had to deinitilize the two structures (Command and ArgsContext which is previously returned by the Command.parseProcess and Command.parseFrom) by yourself.

• Auto help text generation

  Now you don't need to defined -h, --help flag and handle it manually. yazap can now build and display help text dynamically based on provided arguments and their settings.

  Note: For now help will be displayed when -h, --help is provided but not on error. Once help will be displayed all the structures will be deinitilize and app will exit gracefully.

• Added Arg.description and its Arg.setDescription setter

Breaking changes:

• Command.parseFrom and Command.parseProcess is moved to Yazap
• Command.about is renamed to Command.description
• Command.newWithHelpTxt is renamed to Command.newWithDescription
• Now flag.* functions takes a description of type ?[]const u8 as a last parameter

Fixes:

• Thread panic error/Incorrect or an unexpected error message to be logged when an error used to occur when parsing subcommand's argument and trying to log error using root command error trace. (4c1f7de)
• Value outside of Arg.allowed_values to be consumed without verifying it. (dcb7518)

Fixes:

• Fixed CommandArgumentNotProvided error when argRequired is set to false (#4)
• Fixed an error message that shows parent command name instead of sub-command when CommandArgumentNotProvided error is returned from sub-command parser (#4)

What's new:

• Added new Command.takesValue setter (f6ca476)
• Added new Arg.takesMultipleValues API which allows Arg to take unknown number of values (f5e6512)

Internal changes:

• fix(Parser): Set ErrorContext.setErr(err) when error is captured on else (98aee00)
• refactor(Parser): Add a function to verify and append the value (c734d0c)
• fix(Parser): Use a pointer capture instead of value capture (7caff04)