Ticket #748: Arguments_Docs.txt

--Tango Arguments - Flexible argument string parsing.

-Introduction

Arguments is a module for parsing argument strings, such as command line arguments passed to main(). It is an extrememly flexible module, able to accomodate a wide variety of desired parsing behavior. Arguments follows a declarative paradigm, requiring the programmer to tell it some basic information about the arguments and any possible parameters. However, it also will parse a given string using a default set of actions that covers most basic use cases.

Here's the most basic example of using Arguments:

void main(char[][] cmdl)
{
    auto args = new Arguments(cmdl[1..$]);
}

And that's it. If the program were called with, say, a command line like:

myProgram -a=read --files text1.txt text2.txt

Then you would be able to perform the following operations:

if ("a" in args)
    char[] action = args["a"][0];
    ... do something cool

if ("files" in args)
    char[][] processFiles = args["files"];

And so on. This is the basic operation mode of Arguments, and it's designed to get you up and running quickly with a minimum of fuss. However, there is a lot more going on under the hood than just this, if you tell Arguments a little bit of information beforehand, it becomes quite powerful in it's ability to decipher argument strings into something coherant for your particular program.


Here's a slightly more complex example:

void main(char[][] cmdl)
{
    auto args = new Arguments;
    args.define("a").parameter;
    args.define("b");
    args.parse(cmdl[1..$]);
}

Here, we've told Arguments a little bit of what we're expecting, by using the .define method. This method is what allows you to set up argument definitions, and there are quite a variety of chaining methods that you can use along with a define. We'll get into them all a little later on. For now, let's accept that .define("a").parameter tells us that the argument "a" expects to get a parameter, and that .define("b") tells us that while we can expect to see a "b", it doesn't take any parameters.

With that information, if the program were called with a command line like:

myProgram -b -a hello

Then we can know that we now have '"b" in args' and that 'args["a"] contains "hello"', as one would reasonably expect.

But wait, you say. Isn't that the same thing that would have happened if I hadn't made any definitions at all? Why did I waste my time calling .define?

You are indeed astute, young grasshopper. Your efforts in calling .define were not in vain, however, and here's why.

Assume that instead of the above command line, you were instead called like this:

myProgram -ab hello

Which you want to have parsed the same way as the previous command line. Well, without having defined your arguments beforehand, Arguments would have parsed that as:

"a" in args
"b" in args
args["b"][0] = "hello"

Which isn't quite right. However, we did tell Arguments about how we wanted our command line parsed beforehand, and because it already knows that "a" takes a parameter but that "b" does not, it will have parsed that line the same as the previous. In other words, because we gave it a little bit of information beforehand, the command lines:

myProgram -b -a hello
myProgram -ab hello

Will not appear any differently to our program, transparently to us using Arguments, those two command lines are the same. This is some of the power and flexibility of Arguments. But that just barely scratches the surface.


-Background

Arguments was designed to be as flexible as possible, and to support a wide variety of command-line paradigms while still maintaining a declarative nature, as opposed to format-string style parsers that are inheriently less flexible with regards to positioning, and also require the user to have some knowledge of some arcane syntax. It does, however, follow a few conventions which the user should be familiar with.

-Terminology

argument
    an argument is one particular item that will be queryable post-parse. Given a command string '-a -b --cde', all of "a", "b", and "cde" are arguments. There are also two distinct types of arguments, long and short.
    short argument
        a short argument is a single character, prefixed by the short-argument prefix (by default, this is "-"). Short arguments may be collected together, for example, "-a -b" and "-ab" are identical.
    long argument
        a long argument is a series of characters, prefixed by the long-argument prefix (by default, this is "--"). Long arguments may not be collected together.

parameter
    a parameter is an attribute of one particular argument. There may be multiple parameters for any given argument. Given a command string '-a 1' and assuming a basic parse, "a" is an argument, and "1" is a parameter to "a".
    standard parameter
        parameters can also directly follow arguments if they are delimited by a delimiter (by default, they are ":" and "="). So, '-a 1', '-a:1', and '-a=1' are all identical.
    implicit parameters
        a parameter that has no associated argument. This can happen if all arguments are defined not to take any parameters, or if no arguments were given at all. implicit arguments are availble after parse in args[null].

-The function of command line arguments

Command line arguments typically provide information that customizes the program execution. These given arguments may be required or optional, the Arguments module itself does not presume to tell you how your program should function, it's up to you to tell it how you want it to work.


--Reference

-Overview

First, you import the Arguments module.

import tango.whatever.Arguments;

The, you create a new Arguments instance:

auto args = new Arguments;

If you pass the Arguments constructor the string you'd like it to parse, you can be done right here.

auto args = new Arguments(cmdl[1..$]);

Otherwise, after creating your new arguments, you will then set up any needed configuration:

args.prefixLong ~= ["%%"];
args.define("x").required.parameters(0,1);

And then finally, call parse:

args.parse(cmdl[1..$]);

After which, can you then access the information parsed from your command line string.

if ("x" in args) {}
char[] myVal = (args["value"][0]);
etc..

-args.prefixShort

-args.prefixLong

-args.delimiters

-args.reset

-args.remove

-args.count

-args.define

--define.parameters
--define.defaults
--define.delimiters
--define.required
--define.aliases
--define.conflicts
--define.requires
--define.callback
--define.validation

-how to generate help text

-some sample use cases
    long arguments with single hyphen
        myProg -pf -> (args["pf")

    different prefixes
        myProg +f +rgb
        myProg /file

    no delimiters
        myProg -ffile1.txt