argparse ~api-with-named-parameters

Parser for command line arguments

argparse is a flexible utility for D programming language to parse command line arguments.

[!WARNING] :warning: Please be aware that current HEAD contains breaking changes comparing to 1.*

:warning: This includes changes in documentation - documentation for 1.* version is here

Changes since 1.* version

<details> <summary>Changelog</summary>

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")

• Dropped support for DMD-2.099.

Enhancements and bug fixes

• 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 </details>

Features

• Positional arguments:
  • Automatic type conversion of the value.
  • Required by default, can be marked as optional.
• Named arguments:
  • Multiple names are supported, including short (-v) and long (--verbose) ones.
  • Case-sensitive/-insensitive parsing.
  • Bundling of short names (-vvv is same as -v -v -v).
  • Equals sign is accepted (-v=debug, --verbose=debug).
  • Automatic type conversion of the value.
  • Optional by default, can be marked as required.
• Support different types of destination data member:
  • Scalar (e.g., int, float, bool).
  • String arguments.
  • Enum arguments.
  • Array arguments.
  • Hash (associative array) arguments.
  • Callbacks.
• Different workflows are supported:
  • Mixin to inject standard main function.
  • Parsing of known arguments only (returning not recognized ones).
  • Enforcing that there are no unknown arguments provided.
• Shell completion.
• Options terminator (e.g., parsing up to -- leaving any argument specified after it).
• Arguments groups.
• Subcommands.
• Fully customizable parsing:
  • Raw (string) data validation (i.e., before parsing).
  • Custom conversion of argument value (string -> any destination type).
  • Validation of parsed data (i.e., after conversion to destination type).
  • Custom action on parsed data (doing something different from storing the parsed value in a member of destination object).
• ANSI colors and styles.
• Built-in reporting of error happened during argument parsing.
• Built-in help generation.

Documentation

Please find up-to-date documentation here.