Skip to content

andrey-zherikov/argparse

Repository files navigation

Build codecov

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.

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

    For example, replace this

      .AllowNoValue!"myvalue"

    with

      .AllowNoValue("myvalue")
  • 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

Documentation

Please find up-to-date documentation here.