Proposal: task usage

I would like to have a way of describing which parameters and arguments are available for a given task. Here is what I'm thinking would be nice behavior to have:

$ rex sys:run --help
usage:  sys:run [--thing] [--stuff=<number>] <cmd>
Run a command on a bunch of servers

The following commands should work the same way:

$ rex sys:run -h
$ rex sys:run -?

Here is how a user would (optionally) specify the usage in the task definition:

package sys;

description 'Run a command on a bunch of servers';
usage '[--thing] [--stuff=<number>] <cmd>';
task run => sub {
    my ($options, $args) = @_
    do_a thing() if $options->{thing};
    do_stuff()   if $options->{stuff};
    say run $args->[0];
}

To extend this idea a bit: Doing --help on a namespace will list the tasks in that namespace.

$ rex sys --help
sys:connections [options] <arg1> <arg2> count connections with netstat. usage: --min
sys:df <dir>                            disk free
sys:disk_cleanup <dir>                  disk cleanup
sys:du [<optional arg>]                 disk usage
sys:env <etc>                           echo the environment
sys:firewall [options] <thing>          count the number of firewall rules
sys:hostname [<yay>]                    hostname
sys:kick                                restart nonessential services
sys:latency_amazon                      check latency of amazon api 
sys:latency_homepage                    check latency of the homepage
sys:prune                               cleanup fcgi processes
sys:renice                              renice

In other words I want the command line to work more like git which I always think of as the best example of good command line ui.

I believe this can almost be done without a feature flag. The main problem is going to be --help. For that we would need a feature flag.

This is going to take a bunch of pull requests to accomplish. I'm going to try to make my prs radically smaller in the future, fyi. Assuming you guys like this proposal.

Crazy unnecessary future stuff

One idea is to parse the string and do argument/option validation based on that. There are a couple ways to do that. Atm moment I'm curious about http://docopt.org/ and https://metacpan.org/pod/Docopt. Just a thought. Probably not worth the effort. Certainly should be part of a later phase.

Start by reviewing the task and namespace entry points represented by rex sys:run --help and rex sys --help, along with the proposed usage declaration in task definitions. Done means tasks can expose usage and descriptions through --help, -h, and -?, while namespace help lists its tasks as shown.