Markus Laker 
Posted in reply to Chris Wright
| On Thursday, 3 March 2016 at 01:52:11 UTC, Chris Wright wrote:
> You might want to take a minute to shill it here. What's great about it?
OK. :-)
* It parses positional parameters, error-checks them and places them into type-safe variables: it doesn't just pick out named --switches and then leave you to pick everything else out of argv.
* It can open files specified at the command line. It can do a simplified version of what cat(1) does and many Perl programs so, and open a file specified by the user or fall back to reading from stdin. There's also a convention that the user can type "-" to mean stdin or stdout, depending on the open-mode you specify.
* You can apply range-checks to numeric input and length-checks to string input.
* For numeric arguments, you can change the default radix from decimal to hex, octal or binary, and users can choose their own radices at run time.
* You can error-check string input using a sequence of regular expressions with user-friendly error messages, and then the picked-apart input is ready for your program to use, so that you don't have to analyse it again.
* Users can abbreviate switch names and enum values.
* As well as default values, there are separate end-of-line defaults, so that `list-it`, `list-it --wrap' and `list-it --wrap 132' are all valid: you might arrange things so that the first doesn't wrap, the second wraps to 80 columns by default, and the third wraps to the user-specified width.
* You can set up argument groups: between N and M of these arguments (e.g. you can have --to and --by, but not both); all or none of these arguments (can't have --length without --width or vice versa); and first-or-none arguments (can specify a file name without a block size, but not vice versa). An argument can belong to more than one group, and groups can be applied to any mixture of positional arguments and --named-options.
* Error messages are friendly, and take into account (for example) whether the user specified a parameter by its long name or its short name, and (if there are alternatives, such as --colour and color) which of several long names was used.
* Users can take advantage of flexible syntax: for example, -t5, -t 5 and -t=5 are all permitted and, for Boolean switches, --foo reverses the default (typically turning a switch on), but there's also --foo=0, --foo=no and ==foo=false (or any abbreviations), and similarly for true values.
* Argon gently encourages you to improve program structure by moving command-line parsing and all your parameters into a separate class, rather than passing a dozen pieces of information between functions all over the code.
> How do I use it?
Here's the example from Github, showing off just the basic functionality:
#!/usr/bin/rdmd --shebang -unittest -g -debug -w
import argon;
import std.stdio;
// Imagine a program that creates widgets of some kind.
enum Colours {black, blue, green, cyan, red, magenta, yellow, white}
// Write a class that inherits from argon.Handler:
class MyHandler: argon.Handler {
// Inside your class, define a set of data members.
// Argon will copy user input into these variables.
uint size;
Colours colour;
bool winged;
uint nr_windows;
string name;
argon.Indicator got_name;
// In your constructor, make a series of calls to Named(),
// Pos() and (not shown here) Incremental(). These calls tell Argon
// what kind of input to expect and where to deposit the input after
// decoding and checking it.
this() {
// The first argument is positional (meaning that the user specifies
// it just after the command name, with an --option-name), because we
// called Pos(). It's mandatory, because the Pos() invocation doesn't
// specify a default value or an indicator. (Indicators are explained
// below.) The AddRange() call rejects user input that isn't between
// 1 and 20, inclusive.
Pos("size of the widget", size).AddRange(1, 20);
// The second argument is also positional, but it's optional, because
// we specified a default colour: by default, our program will create
// a green widget. The user specifies colours by their names ('black',
// 'blue', etc.), or any unambiguous abbreviation.
Pos("colour of the widget", colour, Colours.green);
// The third argument is a Boolean option that is named, as all
// Boolean arguments are. That means a user who wants to override
// the default has to specify it by typing "--winged", or some
// unambiguous abbreviation of it. We've also provided a -w shortcut.
//
// All Boolean arguments are optional.
Named("winged", winged) ('w');
// The fourth argument, the number of windows, is a named argument,
// with a long name of --windows and a short name of -i, and it's
// optional. A user who doesn't specify a window count gets six
// windows. Our AddRange() call ensures that no widget has more
// than twelve and, because we pass in a uint, Argon will reject
// all negative numbers. The string "number of windows" is called a
// description, and helps Argon auto-generate a more helpful
// syntax summary.
Named("windows", nr_windows, 6) ('i') ("number of windows").AddRange(0, 12);
// The user can specify a name for the new widget. Since the user
// could explicitly specify an empty name, our program uses an
// indicator, got_name, to determine whether a name was specified or
// not, rather than checking whether the name is empty.
Named("name", name, got_name) ('n').LimitLength(0, 20);
}
// Now write a separate method that calls Parse() and does something with
// the user's input. If the input is valid, your class's data members will
// be populated; otherwise, Argon will throw an exception.
auto Run(string[] args) {
try {
Parse(args);
writeln("Size: ", size);
writeln("Colour: ", colour);
writeln("Wings? ", winged);
writeln("Windows: ", nr_windows);
if (got_name)
writeln("Name: ", name);
return 0;
}
catch (argon.ParseException x) {
stderr.writeln(x.msg);
stderr.writeln(BuildSyntaxSummary);
return 1;
}
}
}
int main(string[] args) {
auto handler = new MyHandler;
return handler.Run(args);
}
> Why should I use it instead of std.getopt?
More functionality for you; more flexible syntax for your users.
Cheers,
Markus
|
Permalink
Reply
