<commit_before>= Methadone - kick the bash habit and start your command line apps off right

Author::  <NAME> (mailto:davetron5000 at g mail dot com)
Copyright:: Copyright (c) 2011 by <NAME>
License:: Distributes under the Apache License, see LICENSE.txt in the source distro

{<img src="https://secure.travis-ci.org/davetron5000/methadone.png" alt="Build Status" />}[http://travis-ci.org/davetron5000/methadone]

A smattering of tools to make your command-line apps easily awesome; kick the bash habit without sacrificing any of the power.

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 <tt>OptionParser</tt>'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-<tt>puts</tt> <tt>puts</tt>.
* Cucumber Steps, built on Aruba, to allow you to test-drive your command-line app development.

== Tutorial

http://a1.mzstatic.com/us/r30/Publication/v4/2c/f7/90/2cf7902f-f709-9125-c73d-87311216527d/MethadoneTutorial.225x225-75.jpg

{Tutorial for your iPad}[http://itunes.apple.com/us/book/kick-bash-habit-ruby-methadone/id515825242?ls=1] - This is a *free* iBooks interactive ebook that contains a step-by-step tutorial on making an awesome app with Methadone, including screencasts.

== Links

* {Source on Github}[http://github.com/davetron5000/methadone]
* RDoc[http://davetron5000.github.com/methadone/rdoc]

== Platforms

* Works completely on:
  * MRI Ruby 1.8.7
  * MRI Ruby 1.9.2
  * MRI Ruby 1.9.3
  * MRI Ruby Head
  * RBX
  * REE
* For JRuby, everything works but Aruba; Aruba just doesn't work on JRuby for some reason, though this library *is* being used in production under JRuby 1.6.6

== Bootstrapping a new CLI App

The +methadone+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and cucumber-based tests with aruba:

    $ methadone --help
    Usage: methadone [options] app_name
            --force                      Overwrite files if they exist
    $ methadone newgem
    $ cd newgem
    $ bundle
    $ rake
    1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
    1 scenario (1 passed)
    3 steps (3 passed)
    $ cat features/newgem.feature
    Feature: My bootstrapped app kinda works
      In order to get going on coding my awesome app
      I want to have aruba and cucumber setup
      So I don't have to do it myself

      Scenario: App just runs
        When I run `newgem --help`
        Then the exit status should be 0
        And the output should contain:
        """
        Usage: newgem [options]
        """

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 <tt>bundle gem</tt>)
* An executable using Methadone::Main to outline your new app
* <tt>Test::Unit</tt> test task set up and an empty unit test.
* Aruba/Cucumber set up with a basic feature that exercise your executable
* The outline of a README
* An optional license included

== DSL for your <tt>bin</tt> file

A canonical <tt>OptionParser</tt> driven app has a few problems with it structurally that Methadone 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 <tt>exit</tt> and/or let exceptions' stack traces leak through.

Methadone provides Methadone::Main to help make a clean and easy-to-maintain <tt>bin</tt> file.  See the  {rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/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 <tt>%x[]</tt> are nice for compact, bash-like scripting, they have some failings:

* You have to check the return value via <tt>$?</tt>
* 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 Methadone::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.com/methadone/rdoc/classes/Methadone/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 <tt>STDERR.puts</tt> on a good day, and nothing on a bad day.  You probably also have a bunch of debug <tt>puts</tt> calls that you have commented out.  Logging is extremely helpful in understand 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.

Methadone::CLILogger is designed to handle this.  It's a proper subclass of Ruby's built-in <tt>Logger</tt> 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 Methadone::CLILogging to get access to a global logger instances without resorting to an explicit global variable

See {CLILogger's rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogger.html] and then {CLILogging's}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogging.html] for more.


Currently, there are classes the 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

== Cucumber Steps

Methadone uses aruba[http://www.github.com/cucumber/aruba] for BDD-style testing with cucumber. This library has some awesome steps, and Methadone provides additional, more opinionated, steps.  

=== Example

Here's an example from methadone's own tests:

    Scenario: Help is properly documented
      When I get help for "methadone"
      Then the exit status should be 0
      And the following options should be documented:
        |--force|
      And the banner should be present
      And the banner should include the version
      And the banner should document that this app takes options
      And the banner should document that this app's arguments are:
        |app_name|which is required|
        |dir_name|which is optional|

See Methadone::Cucumber or its {rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/Cucumber.html] for a list of all the steps provided.

== 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.
<commit_msg>update rdoc<commit_after>= Methadone - kick the bash habit and start your command line apps off right

Author::  <NAME> (mailto:davetron5000 at g mail dot com)
Copyright:: Copyright (c) 2011 by <NAME>
License:: Distributes under the Apache License, see LICENSE.txt in the source distro

{<img src="https://secure.travis-ci.org/davetron5000/methadone.png" alt="Build Status" />}[http://travis-ci.org/davetron5000/methadone]

A smattering of tools to make your command-line apps easily awesome; kick the bash habit without sacrificing any of the power.

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 <tt>OptionParser</tt>'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-<tt>puts</tt> <tt>puts</tt>.
* Cucumber Steps, built on Aruba, to allow you to test-drive your command-line app development.

== Tutorial

http://a1.mzstatic.com/us/r30/Publication/v4/2c/f7/90/2cf7902f-f709-9125-c73d-87311216527d/MethadoneTutorial.225x225-75.jpg

{Tutorial for your iPad}[http://itunes.apple.com/us/book/kick-bash-habit-ruby-methadone/id515825242?ls=1] - This is a *free* iBooks interactive ebook that contains a step-by-step tutorial on making an awesome app with Methadone, including screencasts.

== Links

* {Source on Github}[http://github.com/davetron5000/methadone]
* RDoc[http://davetron5000.github.com/methadone/rdoc]

== Platforms

* The build runs on Travis for:
  * MRI Ruby 1.8.7
  * MRI Ruby 1.9.2
  * MRI Ruby 1.9.3
  * RBX
  * REE
  * JRuby in both 1.8 and 1.9 mode

It should work on 2.0.0 but there's a weird bundler issue where some of the aruba tests fail in odd ways.

== Bootstrapping a new CLI App

The +methadone+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and cucumber-based tests with aruba:

    $ methadone --help
    Usage: methadone [options] app_name
            --force                      Overwrite files if they exist
    $ methadone newgem
    $ cd newgem
    $ bundle
    $ rake
    1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
    1 scenario (1 passed)
    3 steps (3 passed)
    $ cat features/newgem.feature
    Feature: My bootstrapped app kinda works
      In order to get going on coding my awesome app
      I want to have aruba and cucumber setup
      So I don't have to do it myself

      Scenario: App just runs
        When I run `newgem --help`
        Then the exit status should be 0
        And the output should contain:
        """
        Usage: newgem [options]
        """

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 <tt>bundle gem</tt>)
* An executable using Methadone::Main to outline your new app
* <tt>Test::Unit</tt> test task set up and an empty unit test.
* Aruba/Cucumber set up with a basic feature that exercise your executable
* The outline of a README
* An optional license included

== DSL for your <tt>bin</tt> file

A canonical <tt>OptionParser</tt> driven app has a few problems with it structurally that Methadone 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 <tt>exit</tt> and/or let exceptions' stack traces leak through.

Methadone provides Methadone::Main to help make a clean and easy-to-maintain <tt>bin</tt> file.  See the  {rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/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 <tt>%x[]</tt> are nice for compact, bash-like scripting, they have some failings:

* You have to check the return value via <tt>$?</tt>
* 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 Methadone::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.com/methadone/rdoc/classes/Methadone/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 <tt>STDERR.puts</tt> on a good day, and nothing on a bad day.  You probably also have a bunch of debug <tt>puts</tt> calls that you have commented out.  Logging is extremely helpful in understand 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.

Methadone::CLILogger is designed to handle this.  It's a proper subclass of Ruby's built-in <tt>Logger</tt> 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 Methadone::CLILogging to get access to a global logger instances without resorting to an explicit global variable

See {CLILogger's rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogger.html] and then {CLILogging's}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/CLILogging.html] for more.


Currently, there are classes the 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

== Cucumber Steps

Methadone uses aruba[http://www.github.com/cucumber/aruba] for BDD-style testing with cucumber. This library has some awesome steps, and Methadone provides additional, more opinionated, steps.  

=== Example

Here's an example from methadone's own tests:

    Scenario: Help is properly documented
      When I get help for "methadone"
      Then the exit status should be 0
      And the following options should be documented:
        |--force|
      And the banner should be present
      And the banner should include the version
      And the banner should document that this app takes options
      And the banner should document that this app's arguments are:
        |app_name|which is required|
        |dir_name|which is optional|

See Methadone::Cucumber or its {rdoc}[http://davetron5000.github.com/methadone/rdoc/classes/Methadone/Cucumber.html] for a list of all the steps provided.

== 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.

{'fraction_non_alphanumeric': 0.0762503239181135, 'fraction_numerical': 0.01684374190204716, 'mean_word_length': 3.541629891144454, 'pattern_counts': {'":': 0, '<': 65, '<?xml version=': 0, '>': 67, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '284573', 'n_tokens_mistral': 4877, 'n_tokens_neox': 4472, 'n_words': 2041}