maxlinc/fog-samples — pull request #1 by maxlinc (2014-12-18 22:44:10+00:00)
Title: Proposal: use docopt for readable, configurable examples

Gotta love Ruby! (though to be fair docopt.rb is a port from python)

The current samples in Fog get values by prompting the user. This is hard for tests to automate, and I'm not even sure it looks that clean.

My fork uses a "SampleHelper", which get a value from an environment variable if it was set, or prompt for a value if it wasn't. This made it easier to automate but also let the users run it manually.

@mdarby and I talked about switching over to tokens like php-opencloud recently did. That would also work well with my test automation (really any key/value pair system should work), but I think CLI options are even better.

I still have the benefits of templates:
- Easily take a hash and convert it to input for the samples
- Easily find out what keys are used by any given sample (as long as it supports `--help`)

Unlike tokens, I don't need to modify the file before execution, and it's easy to have default values that are used if a given value isn't set.

I started to do this with Ruby's OptionParser so I wouldn't add any dependencies, but it's a lot of extra code that could look confusing.

I thought about hooking up Thor which has a nice API, but it adds too many dependencies and opinions.

Finally, I checked out [docopt.rb](https://github.com/docopt/docopt.rb). With docopt you just write what you want it to print when calle with `--help`, and it'll turn it into an actual option parser.

My only concern is docopt.rb hasn't been updated in a while, hopefully that's just because updates haven't been necessary, not a sign that it's unmaintained.

/cc @smashwilson