Proposal: task usage

[kablamo]

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.

[mbroadhead]

I like this idea.

How deep would the namespace help listing go? If there was a sys::foo namespace, would rex sys --help list the the tasks within it? My preference would be only tasks within the sys namespace, no child namespaces. It might be helpful to list the child namespaces (without any tasks) so you know they are there though. For example:

$ rex sys --help
sys:connections [options] <arg1> <arg2> count connections with netstat. usage: --min
sys:df <dir>                            disk free
child namespaces:
  sys:foo

Then you could run another help for sys:foo:

$ rex sys:foo --help
sys:foo:uptime                       Run uptime on a host

[krimdomu]

Hi @kablamo , i like this feature. I always tried to add something similar but didn't found a way i liked yet. But, i think, with the additional usage keyword it is easy to understand and use.

Also the idea of parsing it and doing parameter validation is a cool idea.