Parser for command line arguments

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

Warning

⚠️ Please be aware that current HEAD contains breaking changes comparing to 1.*

⚠️ This includes changes in documentation - documentation for 1.* version is here

Changes since 1.* version

Changelog

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.namedArgChar is renamed to Config.namedArgPrefix.

  • Config.endOfArgs is renamed to Config.endOfNamedArgs.

  • Config.helpStyle is renamed to Config.styling.

  • Config.addHelp is renamed to Config.addHelpArgument.

  • Config.arraySep is renamed to Config.valueSep.

• 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.

• 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.namedArgPrefix (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.

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

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.