v2.0.2

Bug fixes

• Do not call user main() if -h/--help is provided in command line

v2.0.1

Bug fixes

• Fix printing "Error:" on help screen - #246

v2.0.0

Changes since previous major version

Breaking changes

• Changes in Config:

  • Custom error handler function (Config.errorHandler) now receives message text with ANSI styling if styling is enabled. One can use argparse.ansi.getUnstyledText function to remove any styling - this function returns a range of unstyled string objects which can be used as is or join'ed into a string if needed: message.getUnstyledText.join.

  • Config.addHelp is renamed to Config.addHelpArgument.

  • Config.arraySep is renamed to Config.valueSep.

  • Config.caseSensitive is replaced with Config.caseSensitiveShortName, Config.caseSensitiveLongName and Config.caseSensitiveSubCommand.
    There is also a "new" Config.caseSensitive function/property helper that sets all above settings to a specific value.

  • Config.endOfArgs is renamed to Config.endOfNamedArgs.

  • Config.helpStyle is renamed to Config.styling.

  • Config.namedArgChar is replaced with Config.shortNamePrefix and Config.longNamePrefix.

  • Config.stylingMode remains unchanged even if it was set to autodetect. One should check ansiStylingArgument.stdoutStyling
    or ansiStylingArgument.stderrStyling to determine whether styling should be enabled.

• Style.namedArgumentName is renamed to Style.argumentName.

• Underlying type of ansiStylingArgument argument is changed. It supports detection and tracking of styling for stdout and stderr
  separately: use ansiStylingArgument.stdoutStyling and ansiStylingArgument.stderrStyling for this.
  Also it can be cast to boolean which is an equivalent to ansiStylingArgument.stdoutStyling.

  So if you use it:

    static auto color = ansiStylingArgument;

  then you should replace

    if(args.color == Config.StylingMode.on)

  with

    if(args.color)
    // or
    if(args.color.stdoutStyling)
    // or
    if(ansiStylingArgument.stdoutStyling)

• @SubCommands UDA is removed. One should use SubCommand template instead of SumType.
  All calls to std.sumtype.match should be replaced with matchCmd.

  Simply replace

    @SubCommands SumType!(CMD1, CMD2, Default!CMD3) cmd;
    ...
    cmd.match!...;

  with

    SubCommand!(CMD1, CMD2, Default!CMD3) cmd;
    ...
    cmd.matchCmd!...;

• @TrailingArguments UDA is removed: all command line parameters that appear after double-dash -- are considered as positional arguments.
  So if those parameters are to be parsed, use @PositionalArgument instead of @TrailingArguments.

• Functions for parsing customization (PreValidation, Parse, Validation and Action) now accept functions as runtime parameters instead of template arguments

  For example, replace this

    .Parse     !((string s) { return cast(char) s[1]; })
    .Validation!((char v) { return v >= '0' && v <= '9'; })

  with

    .Parse     ((string s) { return cast(char) s[1]; })
    .Validation((char v) { return v >= '0' && v <= '9'; })

• HideFromHelp is renamed to Hidden and now also hides an argument from shell completion.

• AllowedValues now accepts values as run-time parameters, not as template parameters.

  For example, replace this

    .AllowedValues!(["value1", "value2", value3"])

  with

    .AllowedValues("value1", "value2", value3")

• AllowNoValue now accepts a value as run-time parameter, not as template parameter.

  For example, replace this

    .AllowNoValue!"myvalue"

  with

    .AllowNoValue("myvalue")

• RequireNoValue is renamed to ForceNoValue and now accepts a value as run-time parameter, not as template parameter.

  For example, replace this

    .RequireNoValue!"myvalue"

  with

    .ForceNoValue("myvalue")

• ArgumentValue is renamed to AllowedValues.

  For example, replace this

    .ArgumentValue("value1", "value2")

  with

    .AllowedValues("value1", "value2")

• parseArgs template functions that received newMain template argument was removed. One should use either main template mixin
  or non-templated Result parseArgs(ref COMMAND receiver, string[] args) function.

• Removed Result.Error(T...)(string msg, T extraArgs) function. Users should explicitly specify result code using
  Result.Error(T...)(int resultCode, string msg, T extraArgs).

• Dropped support for DMD-2.099.

Enhancements and bug fixes

• Parsing procedure follows POSIX.1-2024 meaning that argparse now
  allows at most one value per appearance of named argument in command line. This means that prog --param value1 value2
  is not working anymore by default - --param must be repeated: prog --param value1 --param value2.
  However, prog --param value1,value2 still works.

  To make argparse 2.* behave like 1.*, one should set Config.variadicNamedArgument to true.
  See documentation for details.

• Fix for Command() UDA: ArrayIndexError is not thrown anymore.

• Error messages are printed with Config.styling and now have the same styling as help text.

• New errorMessagePrefix member in Config.styling that determines the style of "Error:" prefix in error messages. This prefix is printed in red by default.

• New checks:

  • Argument is not allowed to be in multiple argument groups.
  • Subcommand name can't start with Config.shortNamePrefix (dash - by default) or Config.longNamePrefix (double-dash -- by default).

• Functions for parsing customization (PreValidation, Parse, Validation and Action) can now return Result through Result.Success or Result.Error and provide error message if needed.

• Fixes for bundling of single-letter arguments.
  For example, the following cases are supported for bool b; string s; arguments:

  • ./prog -b -s=abc
  • ./prog -b -s abc
  • ./prog -b -sabc
  • ./prog -bsabc
  • ./prog -bs=abc

• Fixes for parsing of multiple values. Only these formats are supported:

  • ./prog --arg value1 value2 value3
  • ./prog --arg=value1,value2,value3

• Values of multi-value positional argument can now be interleaved with named arguments.
  For example, the following is the same when arg1 and arg2 are values for single string[] args positional argument:

  • --flag arg1 arg2
  • arg1 --flag arg2
  • arg1 arg2 --flag

• Long and short names of arguments are now separated:

  • Short names are single-character names by default. This can be overridden by explicitly specifying short and long names in NamedArgument UDA.
  • Short names can be specified with short prefix only (e.g. -).
  • Long names can be specified with long prefix only (e.g. --).

• Removed support for delegate in Config.errorHandler, Description, ShortDescription, Usage and Epilog because of compiler's closures are not yet supported in CTFE.

• Added new Config.assignKeyValueChar parameter to customize assign character in key=value syntax for arguments with associative array type.

• Added new Config.errorExitCode parameter to customize exit code in case of parsing error.

• Added support of @PositionalArgument without explicit position. In this case positions are determined in the order of declarations of members.

• Added support for environment fallback, so adding EnvFallback("VAR") to an argument would automatically populate the argument with the content
  of the VAR environment variable if nothing is provided on the command line.

• Fix for empty argument values: they are now non-null empty strings ("" instead of string.init before).

• Added support for classes.

Other changes

• Removed dependency on std.regex.
• New code base: library implementation is almost fully rewritten (public API was not changed in this effort). Unnecessary templates were replaced with regular functions. As a result, compilation time and memory usage were improved: 2x better for dub build and 4x better for dub test.
• New documentation

v2.0.0-rc2

Bug fixes

• Fix for 'main' template.

v2.0.0-rc1

Breaking changes

• Changes in Config:

  • Custom error handler function (Config.errorHandler) now receives message text with ANSI styling if styling is enabled. One can use argparse.ansi.getUnstyledText function to remove any styling - this function returns a range of unstyled string objects which can be used as is or join'ed into a string if needed: message.getUnstyledText.join.

  • Config.addHelp is renamed to Config.addHelpArgument.

  • Config.arraySep is renamed to Config.valueSep.

  • Config.caseSensitive is replaced with Config.caseSensitiveShortName, Config.caseSensitiveLongName and Config.caseSensitiveSubCommand.
    There is also a "new" Config.caseSensitive function/property helper that sets all above settings to a specific value.

  • Config.endOfArgs is renamed to Config.endOfNamedArgs.

  • Config.helpStyle is renamed to Config.styling.

  • Config.namedArgChar is replaced with Config.shortNamePrefix and Config.longNamePrefix.

• Style.namedArgumentName is renamed to Style.argumentName.

• Underlying type of ansiStylingArgument argument is changed. It can now be directly cast to boolean instead comparing against Config.StylingMode.

  So if you use it:

    static auto color = ansiStylingArgument;

  then you should replace

    if(args.color == Config.StylingMode.on)

  with

    if(args.color)

• @SubCommands UDA is removed. One should use SubCommand template instead of SumType

  Simply replace

    @SubCommands SumType!(CMD1, CMD2, Default!CMD3) cmd;

  with

    SubCommand!(CMD1, CMD2, Default!CMD3) cmd;

• @TrailingArguments UDA is removed: all command line parameters that appear after double-dash -- are considered as positional arguments.
  So if those parameters are to be parsed, use @PositionalArgument instead of @TrailingArguments.

• Functions for parsing customization (PreValidation, Parse, Validation and Action) now accept functions as runtime parameters instead of template arguments

  For example, replace this

    .Parse     !((string s) { return cast(char) s[1]; })
    .Validation!((char v) { return v >= '0' && v <= '9'; })

  with

    .Parse     ((string s) { return cast(char) s[1]; })
    .Validation((char v) { return v >= '0' && v <= '9'; })

• HideFromHelp is renamed to Hidden and now also hides an argument from shell completion.

• AllowedValues now accepts values as run-time parameters, not as template parameters.

  For example, replace this

    .AllowedValues!(["value1", "value2", value3"])

  with

    .AllowedValues("value1", "value2", value3")

• AllowNoValue now accepts a value as run-time parameter, not as template parameter.

  For example, replace this

    .AllowNoValue!"myvalue"

  with

    .AllowNoValue("myvalue")

• RequireNoValue is renamed to ForceNoValue and now accepts a value as run-time parameter, not as template parameter.

  For example, replace this

    .RequireNoValue!"myvalue"

  with

    .ForceNoValue("myvalue")

• ArgumentValue is renamed to AllowedValues.

  For example, replace this

    .ArgumentValue("value1", "value2")

  with

    .AllowedValues("value1", "value2")

• parseArgs template functions that received newMain template argument was removed. One should use either main template mixin
  or non-templated Result parseArgs(ref COMMAND receiver, string[] args) function.

• Dropped support for DMD-2.099.

Enhancements and bug fixes

• Parsing procedure follows POSIX.1-2024 meaning that argparse now
  allows at most one value per appearance of named argument in command line. This means that prog --param value1 value2
  is not working anymore by default - --param must be repeated: prog --param value1 --param value2.
  However, prog --param value1,value2 still works.

  To make argparse 2.* behave like 1.*, one should set Config.variadicNamedArgument to true.
  See documentation for details.

• Fix for Command() UDA: ArrayIndexError is not thrown anymore.

• Error messages are printed with Config.styling and now have the same styling as help text.

• New errorMessagePrefix member in Config.styling that determines the style of "Error:" prefix in error messages. This prefix is printed in red by default.

• New checks:

  • Argument is not allowed to be in multiple argument groups.
  • Subcommand name can't start with Config.shortNamePrefix (dash - by default) or Config.longNamePrefix (double-dash -- by default).

• Functions for parsing customization (PreValidation, Parse, Validation and Action) can now return Result through Result.Success or Result.Error and provide error message if needed.

• Fixes for bundling of single-letter arguments.
  For example, the following cases are supported for bool b; string s; arguments:

  • ./prog -b -s=abc
  • ./prog -b -s abc
  • ./prog -b -sabc
  • ./prog -bsabc
  • ./prog -bs=abc

• Fixes for parsing of multiple values. Only these formats are supported:

  • ./prog --arg value1 value2 value3
  • ./prog --arg=value1,value2,value3

• Removed support for delegate in Config.errorHandler, Description, ShortDescription, Usage and Epilog because of compiler's closures are not yet supported in CTFE.

• Long and short names of arguments are now separated:

  • Short names are single-character names by default. This can be overridden by explicitly specifying short and long names in NamedArgument UDA.
  • Short names can be specified with short prefix only (e.g. -).
  • Long names can be specified with long prefix only (e.g. --).

• Added new Config.assignKeyValueChar parameter to customize assign character in key=value syntax for arguments with associative array type.

• Added support of @PositionalArgument without explicit position. In this case positions are determined in the order of declarations of members.

Other changes

• Removed dependency on std.regex.
• New code base: library implementation is almost fully rewritten (public API was not changed in this effort). Unnecessary templates were replaced with regular functions. As a result, compilation time and memory usage were improved: 2x better for dub build and 4x better for dub test.
• New documentation

v1.4.1

Bug fixes

• Fix for reporting of missed required argument in subcommands (#192)

v1.4.0

Enhancements

• CLI.main can now accept struct with disabled copy constructor.
• Main function passed to CLI.main can accept parameter by reference.
• Boolean values (yes,y,true,no,n and false) are now parsed case-insensitively.
• New checks:
  • Argument name can't start with Config.namedArgChar (dash - by default).
  • For positional arguments within a command:
    • There should be no gaps in indexes, e.g. 0,1,3,4 indexes are not allowed because 2 is missed.
    • Indexes should be unique, e.g. 0,1,2,3,2 indexes are not allowed because 2 is repeated.
    • Number of values should be fixed (i.e. minimum number of values should be the same as maximum number of values) unless it's the last positional argument.
    • Required positional arguments must go before optional positional arguments.
    • Optional positional arguments are not allowed if command has default subcommand.

v1.3.0

Enhancements

• You can now customize what values are accepted in command line for enum types:

  struct T
  {
      enum Fruit {
          apple,
          @ArgumentValue("no-apple","noapple")
          noapple
      };
      Fruit a;
  }
  assert(CLI!T.parseArgs!((T t) { assert(t == T(T.Fruit.apple)); })(["-a","apple"]) == 0);
  assert(CLI!T.parseArgs!((T t) { assert(t == T(T.Fruit.noapple)); })(["-a=no-apple"]) == 0);
  assert(CLI!T.parseArgs!((T t) { assert(t == T(T.Fruit.noapple)); })(["-a","noapple"]) == 0);

Other changes

• Code has been widely refactored to have more clear responsibility separation between components
• New testing mode in CI: -preview=in

v1.2.0

Enhancements

• Add support of custom types:

  struct Value
  {
      string a;
  }
  struct T
  {
      @(NamedArgument.Parse!((string s) { return Value(s); }))
      Value s;
  }

Bug fixes

• Fix for the case when main program is attributed with Command without name:

  @(Command.Description("Description of main program"))
  struct Program
  {
  ...
  }

• Ignore arguments with long invocation text during indent calculation for help text:

  Optional arguments:
    -x X          1 x
    --yyyyyyyyyyyy YYYYYYYYYYYY
                  12 ys
    -h, --help    Show this help message and exit
  

v1.1.1

Bug fixes

• Fix for positional argument name where "name" was ignored:

  @PositionalArgument(0, "name")
  string param