Skip to content

ddn.util.docopt

Command-line interface description language parser.

Module Declaration

module ddn.util.docopt;

Classes

DocoptLanguageError

class DocoptLanguageError : Exception

Exception thrown when there is an error in the docopt language definition.

This exception indicates a problem with the documentation string itself, such as missing "usage:" section or malformed patterns.

Constructor:

this(string msg, string file = __FILE__, size_t line = __LINE__) @safe;
Parameter Description
msg The error message describing the language error
file The source file where the error originated
line The line number where the error originated

DocoptExitHelp

class DocoptExitHelp : Exception

Exception thrown when the user requests help via --help flag.

This exception is thrown when the parsed arguments contain --help, allowing the application to display help and exit gracefully.

Constructor:

this(string msg, string file = __FILE__, size_t line = __LINE__) @safe;
Parameter Description
msg The help text to display
file The source file where the exception originated
line The line number where the exception originated

DocoptArgumentError

class DocoptArgumentError : Exception

Exception thrown when there is an error in the command-line arguments.

This exception indicates that the user provided invalid arguments that do not match the expected pattern defined in the usage string.

Constructor:

this(string msg, string file = __FILE__, size_t line = __LINE__) @safe;
Parameter Description
msg The error message describing the argument error
file The source file where the exception originated
line The line number where the exception originated

Structs

ArgValue

struct ArgValue

Represents a value parsed from command-line arguments.

ArgValue can hold different types of values:

  • Boolean (for flags)
  • String (for arguments with values)
  • Long integer (for counting repeated options and numeric values)
  • Double-precision floating point (for numeric values)
  • List of strings (for repeated arguments)
  • Null (for missing optional arguments)

Type Enum

enum Type {
    NONE,
    BOOL,
    STRING,
    LONG,
    DOUBLE,
    LIST
}

Constructors

this(bool b) @safe pure nothrow @nogc;
this(string s) @safe pure nothrow @nogc;
this(long i) @safe pure nothrow @nogc;
this(int i) @safe pure nothrow @nogc;
this(double d) @safe pure nothrow @nogc;
this(float f) @safe pure nothrow @nogc;
this(string[] l) @safe pure nothrow @nogc;

Methods

type
Type type() const @safe pure nothrow @nogc;

Returns the type of value stored.

Returns: The Type enum value indicating what kind of value is stored.

isTrue
bool isTrue() const @safe pure nothrow @nogc;

Checks if this value represents a "true" condition.

Returns true if:

  • The value is a boolean true
  • The value is a non-empty string
  • The value is a non-zero integer
  • The value is a non-zero floating point number (and not NaN)
  • The value is a non-empty list

Returns: true if the value represents a truthy condition.

isNull
bool isNull() const @safe pure nothrow @nogc;

Checks if this value is null/none.

Returns: true if no value is stored.

asBool
bool asBool() const @safe pure nothrow @nogc;

Returns the value as a boolean.

Returns: The boolean value, or false if not a boolean type.

asString
string asString() const @safe pure nothrow @nogc;

Returns the value as a string.

Returns: The string value, or null if not a string type.

asInt
int asInt() const @safe pure nothrow @nogc;

Returns the value as a 32-bit integer.

Returns: The integer value, or 0 if not an integer type.

asLong
long asLong() const @safe pure nothrow @nogc;

Returns the value as a 64-bit integer.

Returns: The long value, or 0L if not an integer type.

asDouble
double asDouble() const @safe pure nothrow @nogc;

Returns the value as a double-precision floating point number.

Returns: The double value, or 0.0 if not a double type.

toString
string toString() const;

Returns a string representation of the value.

CtfeDoc

struct CtfeDoc

Pre-parsed docopt descriptor for compile-time evaluation.

Use with parseDocopt template to parse the docstring at compile time for zero runtime overhead.

Aliases

ArgMap

alias ArgMap = ArgValue[string];

Associative array mapping argument names to their parsed values.

Functions

docopt

ArgMap docopt(string doc, string[] argv, bool help = true, string versn = null, bool optionsFirst = false);

Parses command-line arguments according to the docopt specification.

Parameter Description
doc The docstring defining the command-line interface
argv The command-line arguments to parse (typically args[1..$])
help If true, automatically handle --help flag
versn Version string to display for --version flag
optionsFirst If true, options must come before positional arguments

Returns: An ArgMap containing the parsed argument values.

Throws:

  • DocoptLanguageError — if the docstring is malformed
  • DocoptArgumentError — if the arguments don't match the pattern
  • DocoptExitHelp — if --help or --version is requested

Example:

import ddn.util.docopt;

enum DOC = `
Usage:
  prog [options] <file>

Options:
  -h --help     Show this help
  -v --verbose  Be verbose
`;

void main(string[] args) {
    auto arguments = docopt(DOC, args[1..$]);
    if (arguments["--verbose"].isTrue) {
        writeln("Verbose mode enabled");
    }
}

docopt (CTFE version)

ArgMap docopt(CtfeDoc parsed, string[] argv, bool help = true, string versn = null, bool optionsFirst = false);

Parses command-line arguments using a pre-parsed docopt descriptor.

Parameter Description
parsed Pre-parsed docopt descriptor from parseDocopt
argv The command-line arguments to parse
help If true, automatically handle --help flag
versn Version string to display for --version flag
optionsFirst If true, options must come before positional arguments

Returns: An ArgMap containing the parsed argument values.

Templates

parseDocopt

template parseDocopt(string doc)

Parses a docstring at compile time.

Returns a CtfeDoc that can be used with the CTFE version of docopt for zero runtime parsing overhead.

Example:

import ddn.util.docopt;

enum DOC = `
Usage:
  prog greet <name> [--times=<n>]

Options:
  -t --times=<n>   Repeat times [default: 1]
`;

// Pre-parse at compile time
enum PRE = parseDocopt!DOC;

void main(string[] args) {
    // Use pre-parsed descriptor at runtime
    auto arguments = docopt(PRE, args[1..$], true, "1.0.0");
}

See Also