davetron5000/optparse-plus

= optparse-plus - Wrapper around OptionParse to Make CLIs a bit Easier

formerly called methadone, {read about the name change if you care}[https://github.com/davetron5000/optparse-plus/wiki/Name-Change]

A smattering of tools to make your command-line apps easily awesome; Ideally makes it almost as easy as bash to get a command line app up and running.

The goal of this project is to make it as easy as possible to write awesome and powerful command-line applications.

Toward that end, this gem provides:

A command-line app to bootstrap a new command-line app.
A lightweight DSL to create your command-line interface, that loses none of OptionParser's power.
A simplified means of running external commands that has better error handling and diagnostics.
Simplified zero-config logging that is a better-than-puts puts.
Support for integration-testing your CLI using Test::Unit

== Platforms

This library only supports the latest versions of Ruby. JRuby support has been too difficult to keep up with, though the library should work for JRuby.

== Bootstrapping a new CLI App

The +optparse_plus+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and integration tests.

It assumes you are using a standard Ruby development environment, which includes:

Some sort of Ruby version manager to allow you to manage Ruby as yourself and not as root/system
Bundler
Git

(Note that apps powered by this gem have no particular runtime dependencies as classes this gem provides depend only on the standard library)

$ optparse_plus --help
Usage: optparse_plus [options] app_name

Kick the bash habit by bootstrapping your Ruby command-line apps

v2.0.0

Options:
    -h, --help                       Show command line help
        --force                      Overwrite files if they exist
        --[no-]readme                [Do not ]produce a README file
        --rspec                      Generate RSpec unit tests instead of Test::Unit
    -l, --license LICENSE            Specify the license for your project
                                     (mit|apache|gplv2|gplv3|custom|NONE)
        --log-level LEVEL            Set the logging level
                                     (debug|info|warn|error|fatal)
                                     (Default: info)
        --version                    Show help/version info

Arguments:

    app_name
        Name of your app, which is used for the gem name and executable name

Usage: optparse_plus [options] app_name
        --force                      Overwrite files if they exist
$ optparse_plus myapp -l mit
$ cd myapp
$ bundle install
...
$ bundle exec rake
Started
.
Finished in 0.000499 seconds.
-----------------------------------------------------------------------------------------
1 tests, 1 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
-----------------------------------------------------------------------------------------
2004.01 tests/s, 2004.01 assertions/s
Started
.
Finished in 0.298281 seconds.
-----------------------------------------------------------------------------------------
1 tests, 8 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
-----------------------------------------------------------------------------------------
3.35 tests/s, 26.82 assertions/s

$ cat test/integration/test_cli.rb
require "optparse_plus/test/base_integration_test"

class TestSomething < OptparsePlus::BaseIntegrationTest
  def test_truth
    stdout,stderr,results = run_app("myapp","--help")
    assert_banner(stdout, "myapp", takes_options: true, takes_arguments: false)
    assert_option(stdout,"-h", "--help")
    assert_option(stdout,"--version")
    assert_oneline_summary(stdout)
  end
end

Basically, this sets you up with all the boilerplate that you should be using to write a command-line app. Specifically, you get:

Gemified project (based on bundle gem)
An executable using OptparsePlus::Main to outline your new app
Test::Unit test task set up and an empty unit test.
Test::Unit integration tests with some of optparse-plus's assertions to let you drive your CLI's development
The outline of a README
An optional license included

== DSL for your bin file

A canonical OptionParser-driven app has a few problems with it structurally that optparse-plus can solve:

Backwards organization - main logic is at the bottom of the file, not the top
Verbose to use +opts.on+ just to set a value in a +Hash+
No exception handling - you have to explicitly call exit and/or let exceptions' stack traces leak through.

optparse-plus provides OptparsePlus::Main to help make a clean and easy-to-maintain bin file. See the {rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/Main.html] for an example, and see {my blog}[http://www.naildrivin5.com/blog/2011/12/19/methadone-the-awesome-cli-library.html] on the derivation of this module.

== Wrapper for running external commands with good logging

While backtick and %x[] are nice for compact, bash-like scripting, they have some failings:

You have to check the return value via $?
You have no access to the standard error
You really want to log: the command, the output, and the error so that for cron-like tasks, you can sort out what happened

Enter OptparsePlus::SH

sh "cp foo.txt /tmp"
# => logs command at DEBUG level
#    if the command exited zero:
#        logs the standard output at DEBUG
#        logs the standard error at WARN
#    if the command exited nonzero:
#        logs the standard output at INFO
#        logs the standard error at WARN
#        returns the exit code for your examination
#
#        there's a LOT MORE

See the {rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/SH.html] for more detailed examples and usage.

This isn't a replacement for Open3 or ChildProcess, but a way to easily "do the right thing" for most cases.

== Zero-Config Logging

Chances are, your code is littered with STDERR.puts on a good day, and nothing on a bad day. You probably also have a bunch of debug puts calls that you have commented out. Logging is extremely helpful in understanding how your app is behaving (or how it behaved in the past). Logging can be a pain to set up, and can also make it hard to give the user at the command-prompt a good experience.

OptparsePlus::CLILogger is designed to handle this. It's a proper subclass of Ruby's built-in Logger with a few enhancements:

Messages don't get formatting if they are destined for a TTY (e.g. the user sitting at her terminal)
Errors and warnings go to the standard error.
Debug and info messages go to the standard output.
When these are redirected to a file, the log messages are properly date/time stamped as you'd expect
You can mix-in OptparsePlus::CLILogging to get access to a global logger instances without resorting to an explicit global variable

See {CLILogger's rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/CLILogger.html] and then {CLILogging's}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/CLILogging.html] for more.

Currently, there are classes that assist in directing output logger-style to the right place; basically ensuring that errors go to +STDERR+ and everything else goes to +STDOUT+. All of this is, of course, configurable

== Integration Tests

optparse-plus provides some basic features for executing your CLI and asserting things about it. OptparsePlus::Test::IntegrationTestAssertions documents these.

== Contributing

Feel free to file an issue, even if you don't have time to submit a patch
Please try to include a test for any patch you submit. If you don't include a test, I'll have to write one, and it'll take longer to get your code in.
This is not intended to support “command-suite” style CLIs. See {GLI}[http://naildrivin5.com/gli] if that's what you want.

davetron5000 / optparse-plus

readme