methadone 1.0.0.rc1 → 1.0.0.rc2

data/README.rdoc

@@ -6,17 +6,15 @@ License:: Distributes under the Apache License, see LICENSE.txt in the source di
 
 A smattering of tools to make your command-line apps easily awesome; kick the bash habit without sacrificing any of the power.
 
-The overall goal of this project is to allow you to write a command-line app in Ruby that is as close as possible to the expedience and concisenes of bash, but with all the power of Ruby available when you need it.
+The goal of this project is to make it as easy as possible to write awesome and powerful command-line applications.
 
-Currently, this library is under development and has the following to offer:
+Toward that end, this gem provides:
 
-* Bootstrapping a new CLI app
-* Lightweight DSL to structure your bin file
-* Simple wrapper for running external commands with good logging
-* Utility Classes
-  * Methadone::CLILogger - a logger subclass that sends messages to standard error standard out as appropriate
-  * Methadone::CLILogging - a module that, when included in any class, provides easy access to a shared logger
-* Cucumber Steps
+* 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.
 
 == Links
 
@@ -26,13 +24,13 @@ Currently, this library is under development and has the following to offer:
 == Platforms
 
 * Works completely on:
+  * MRI Ruby 1.8.7
   * MRI Ruby 1.9.2
   * MRI Ruby 1.9.3
   * MRI Ruby Head
-  * MRI Ruby 1.8.7
   * 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
+* 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
 
@@ -61,68 +59,24 @@ The +methadone+ command-line app will bootstrap a new command-line app, setting
         Usage: newgem [options]
         """
 
-Basically, this sets you up with all the boilerplate that you *should* be using to write a command-line app.
+Basically, this sets you up with all the boilerplate that you *should* be using to write a command-line app.  Specifically, you get:
 
-== DSL for your `bin` file
+* 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
 
-A canonical `OptionParser` driven app has a few problems with it structurally that methadone can solve
+== 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
-
-Methadone gives you a simple,lightweight DSL to help.  It's important to note that we're taking a light touch here; this is all a thin wrapper around +OptionParser+ and you still have complete access to it if you'd like.  We're basically wrapping up some canonical boilerplate into more expedient code
-
-    #!/usr/bin/env ruby
-    
-    require 'optparse'
-    require 'methadone'
-
-    include Methadone::Main
-
-    main do |name,password|
-      name # => guaranteed to be non-nil
-      password # => nil if user omitted on command line
-      options[:switch] # => true if user used --switch or -s
-      options[:s]      # => ALSO true if user used --switch or -s
-      options[:f]      # => value of FILE if used on command-line
-      options[:flag]   # => ALSO value of FILE if used on command-line
-
-      # If something goes wrong, you can just raise an exception
-      # or call exit_now! if you want to control the exit status
-      #
-      # Note that if you set DEBUG in the environment, the exception
-      # will leak through; this can be handy to figure out why
-      # your app might be failing
-    end
-
-    description "One line summary of your awesome app"
-
-    on("--[no-]switch","-s","Some switch")
-    on("-f FILE","--flag","Some flag")
-    on("-x FOO") do |foo|
-      # something more complex; this is exactly OptionParser opts.on 
-    end
-
-    arg :name
-    arg :password, :optional
-
-    # If you want to avoid automatic exception catching/logging do:
-    #
-    # leak_exceptions true
-    #
-    # Note that Methadone::Error exceptions are always caught and logged
-
-    go!
+* No exception handling - you have to explicitly call <tt>exit</tt> and/or let exceptions' stack traces leak through.
 
-+go!+ runs the block you gave to +main+, passing it the unparsed +ARGV+ as parameters to the block.  It will
-also parse the command-line via +OptionParser+ and do a check on the remaining arguments to see
-if there's enough to satisfy the <tt>:required</tt> args you've specified.
-
-Finally, the banner/help string will be full constructed based on the interface you've declared.  If you 
-don't accept options, <tt>[options]</tt> won't appear in the help.  The names of your arguments
-will appear in proper order and <tt>:optional</tt> ones will be in square brackets.  You don't have to 
-touch a thing.
+Methadone provides Methadone::Main to help make a clean and easy-to-maintain <tt>bin</tt> file.  See the  {rdoc}[http://rubydoc.info/github/davetron5000/methadone/master/Methadone/Main] 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
 
@@ -132,87 +86,44 @@ While backtick and <tt>%x[]</tt> are nice for compact, bash-like scripting, they
 * 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
-
-    include Methadone::SH
-
-    sh 'cp foo.txt /tmp'
-    # => logs the command to DEBUG, executes the command, logs its output to DEBUG and its
-    #    error output to WARN, returns 0
-    
-    sh 'cp non_existent_file.txt /nowhere_good'
-    # => logs the command to DEBUG, executes thecommand, logs its output to INFO and
-    #    its error output to WARN, returns the nonzero exit status of the underlying command
-    
-    sh! 'cp non_existent_file.txt /nowhere_good'
-    # => same as above, EXCEPT, raises a Methadone::FailedCommandError
-
-With this, you can easily script external commands in *almost* as expedient a fashion as with +bash+, however you get sensible logging along the way.  By default, this uses the logger provided by Methadone::CLILogging (which is *not* mixed in when you mix in Methadone::SH).  If you want to use a different logger, or don't want to mix in Methadone::CLILogging, simply call +set_sh_logger+ with your preferred logger.
-
-But that's not all!  You can run code when the command succeed by passing a block:
-
-    sh 'cp foo.txt /tmp' do
-      # Behaves exactly as before, but this block is called after
-    end
-
-    sh 'cp non_existent_file.txt /nowhere_good' do
-      # This block isn't called, since the command failed
-    end
-
-The <tt>sh!</tt> form works this way as well.  The block form is also how you can access the standard output or error of the command that ran.  Simply have your block accept one or two aguments:
+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
 
-    sh 'ls -l /tmp/' do |stdout|
-      # stdout contains the output of the command
-    end
-    sh 'ls -l /tmp/ /non_existent_dir' do |stdout,stderr|
-      # stdout contains the output of the command,
-      # stderr contains the standard error output.
-    end
+See the {rdoc}[http://rubydoc.info/github/davetron5000/methadone/master/Methadone/SH] 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.
 
-== Utility Classes
-
-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
+== Zero-Config Logging
 
-=== Examples
+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.
 
-==== Using STDOUT as a log, respecting STDERR
+Methadone::CLILogger is designed to handle this.  It's a proper subclass of Ruby's built-in <tt>Logger</tt> with a few enhancements:
 
-    require 'methadone'
+* 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
 
-    include Methadone::CLILogging
+See {CLILogger's rdoc}[http://rubydoc.info/github/davetron5000/methadone/master/Methadone/CLILogger] and then {CLILogging's}[http://rubydoc.info/github/davetron5000/methadone/master/Methadone/CLILogging] for more.
 
-    command = "rm -rf /tmp/*"
-    debug("About to run #{command}") # => goes only to STDOUT, no logging format
-    if system(command)
-      info("Succesfully ran #{command}") # => goes only to STDOUT, no logging format
-    else
-      error("There was a problem running #{command}") # => goes only to STDERR, no logging format
-    end
 
-==== Using a log file, but respecting STDERR
-
-Here, since we have a logfile, that logfile gets ALL messages and they have the default logger format.
-
-    require 'methadone'
-
-    include Methadone::CLILogging
-
-    self.logger = CLILogger.new("logfile.txt")
-    command = "rm -rf /tmp/*"
-    debug("About to run #{command}") # => goes only to logfile.txt, in the logger-style format
-    if system(command)
-      info("Succesfully ran #{command}") # => goes only to logfile.txt, in the logger-style format
-    else
-      error("There was a problem running #{command}") 
-      # => goes to logfile.txt in the logger-style format, and
-      #    to STDERR in a plain format
-    end
+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.  
+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
 
@@ -230,50 +141,9 @@ Here's an example from methadone's own tests:
         |app_name|which is required|
         |dir_name|which is optional|
 
-=== Steps Provided
-* Run <tt>command_to_run --help</tt> using aruba
-
-    When I get help for "command_to_run"
-
-* Make sure that each option shows up in the help and has *some* sort of documentation
-
-    Then the following options should be documented:
-      |--force|
-      |-x     |
-
-* Check an individual option for documentation:
-
-    Then the option "--force" should be documented
-
-* Checks that the help has a proper usage banner
-
-    Then the banner should be present
-
-* Checks that the banner includes the version
-
-    Then the banner should include the version
-
-* Checks that the usage banner indicates it takes options via <tt>[options]</tt>
-
-    Then the banner should document that this app takes options
-
-* Do the opposite; check that you don't indicate options are accepted
-
-    Then the banner should document that this app takes no options
-
-* Checks that the app's usage banner documents that its arguments are <tt>args</tt>
-
-    Then the banner should document that this app's arguments are "args"
-
-* Do the opposite; check that your app doesn't take any arguments
-
-    Then the banner should document that this app takes no arguments
-
-* Check for a usage description which occurs after the banner and a blank line
-
-    Then there should be a one-line summary of what the app does
-
-== What might be
+See Methadone::Cucumber or its {rdoc}[http://rubydoc.info/github/davetron5000/methadone/master/Methadone/Cucumber] for a list of all the steps provided.
 
-See {the roadmap}[https://github.com/davetron5000/methadone/wiki/Roadmap]
+== 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.

data/bin/methadone

@@ -7,6 +7,7 @@ require 'methadone/cli'
 
 include FileUtils
 include Methadone::Main
+include Methadone::CLILogging
 include Methadone::CLI
 include Methadone::SH
 
@@ -32,20 +33,11 @@ main do |app_name|
   end
 
   license = options[:license]
-  if license
-    if license == 'NONE'
-      license = nil
-    else
-      copy_file "#{options[:license]}_LICENSE.txt", :as => "LICENSE.txt"
-    end
-  else
-    warn "warning: your app has no license"
-  end
-
+  warn "warning: your app has no license" unless license
+  license = nil if license == 'NONE'
+  copy_file "#{options[:license]}_LICENSE.txt", :as => "LICENSE.txt" if license
 
-  if using_readme
-    copy_file "README.rdoc", :binding => binding 
-  end
+  copy_file "README.rdoc", :binding => binding if using_readme
 
   copy_file "features/executable.feature", :as => "#{gemname}.feature", :binding => binding
   copy_file "features/step_definitions/executable_steps.rb", :as => "#{gemname}_steps.rb"
@@ -70,9 +62,13 @@ on("--[no-]readme","[Do not ]produce a README file")
 licenses = %w(mit apache custom NONE)
 on("-l LICENSE","--license",licenses,"Specify the license for your project (#{licenses.join('|')})")
 
+use_log_level_option
+
 arg :app_name, :required
 
 version Methadone::VERSION
 
+defaults_from_env_var 'METHODONE_OPTS'
+
 go!
 

data/features/bootstrap.feature

@@ -43,6 +43,7 @@ Feature: Bootstrap a new command-line app
     And the banner should document that this app takes options
     And the following options should be documented:
       |--version|
+      |--log-level|
     And the banner should document that this app takes no arguments
     When I successfully run `rake -T -I../../lib`
     Then the output should contain:

data/lib/methadone/cli_logger.rb

@@ -2,17 +2,18 @@ require 'logger'
 
 module Methadone
   # A Logger instance that gives better control of messaging the user
-  # and logging app activity.  At it's most basic, you would use
-  # #info as a replacement for +puts+ and #error as a replacement
+  # and logging app activity.  At it's most basic, you would use <tt>info</tt>
+  # as a replacement for +puts+ and <tt>error</tt> as a replacement
   # for <tt>STDERR.puts</tt>.  Since this is a logger, however, you
   # can also use #debug, #warn, and #fatal, and you can control
   # the format and "logging level" as such.
   #
   # So, by default:
-  # * #debug messages do not appear anywhere
-  # * #info messages appear on the standard output
-  # * #warn, #error, and #fata messagse appear on the standard error
-  # * The default format of messages is simply the message, no logging cruft
+  # * debug messages do not appear anywhere
+  # * info messages appear on the standard output
+  # * warn, error, and fatal messagse appear on the standard error
+  # * The default format of messages is simply the message, no logging cruft, however if your output
+  #   is redirected to a file, a better timestamped logging format is used
   #
   # You can customize this in several ways:
   # 
@@ -66,7 +67,8 @@ module Methadone
       end
       @stderr_logger.add(severity,message,progname,&block)
     end
-    
+   
+    DEFAULT_ERROR_LEVEL = Logger::Severity::WARN
 
     # A logger that logs error-type messages to a second device; useful
     # for ensuring that error messages go to standard error.  This should be
@@ -81,16 +83,27 @@ module Methadone
     # +error_device+:: device where all error messages should go.  By default, this is Logger::Severity::WARN
     def initialize(log_device=$stdout,error_device=$stderr)
       super(log_device)
+      @stderr_logger = Logger.new(error_device)
+
       @split_logs = log_device.tty? && error_device.tty?
+
       self.level = Logger::Severity::INFO
-      @stderr_logger = Logger.new(error_device)
-      @stderr_logger.level = Logger::Severity::WARN
+      @stderr_logger.level = DEFAULT_ERROR_LEVEL
+
       self.formatter = BLANK_FORMAT if log_device.tty?
       @stderr_logger.formatter = BLANK_FORMAT if error_device.tty?
     end
 
+    def level=(level)
+      super(level)
+      current_error_level = @stderr_logger.level
+      if (level > DEFAULT_ERROR_LEVEL) && @split_logs
+        @stderr_logger.level = level
+      end
+    end
+
     # Set the threshold for what messages go to the error device.  Note that calling
-    # #level= will *not* affect the error logger
+    # #level= will *not* affect the error logger *unless* both devices are TTYs.
     #
     # +level+:: a constant from Logger::Severity for the level of messages that should go
     #           to the error logger

data/lib/methadone/cli_logging.rb

@@ -23,6 +23,11 @@ module Methadone
   #       end
   #     end
   module CLILogging
+
+    def self.included(k)
+      k.extend(self)
+    end
+
     # Access the shared logger.  All classes that include this module
     # will get the same logger via this method.
     def logger
@@ -40,6 +45,7 @@ module Methadone
     def change_logger(new_logger)
       raise ArgumentError,"Logger may not be nil" if new_logger.nil?
       @@logger = new_logger
+      @@logger.level = @log_level if @log_level
     end
 
     alias logger= change_logger
@@ -55,5 +61,33 @@ module Methadone
     def error(progname = nil, &block); logger.error(progname,&block); end
     # pass-through to <tt>logger.fatal(progname,&block)</tt>
     def fatal(progname = nil, &block); logger.fatal(progname,&block); end
+
+    LOG_LEVELS = {
+      'debug' => Logger::DEBUG,
+      'info' => Logger::INFO,
+      'warn' => Logger::WARN,
+      'error' => Logger::ERROR,
+      'fatal' => Logger::FATAL,
+    }
+
+    # Call this *if* you've included Methadone::Main to set up a <tt>--log-level</tt> option for your app
+    # that will allow the user to configure the logging level.
+    #
+    # Example:
+    #
+    #     main do 
+    #       # your app
+    #     end
+    #
+    #     use_log_level_option
+    #
+    #     go!
+    #
+    def use_log_level_option
+      on("--log-level LEVEL",LOG_LEVELS,"Set the logging level (#{LOG_LEVELS.keys.join('|')})","(Default: info)") do |level|
+        @log_level = level
+        logger.level = level
+      end
+    end
   end
 end

data/lib/methadone/cucumber.rb

@@ -1,3 +1,52 @@
+module Methadone
+  # By <tt>require</tt>'ing <tt>methadone/cucumber</tt> in your Cucumber setup (e.g. in <tt>env.rb</tt>), you
+  # gain access to the steps defined in this file.  They provide you with the following:
+  #
+  # * Run <tt>command_to_run --help</tt> using aruba
+  # 
+  #     When I get help for "command_to_run"
+  # 
+  # * Make sure that each option shows up in the help and has *some* sort of documentation
+  # 
+  #     Then the following options should be documented:
+  #       |--force|
+  #       |-x     |
+  # 
+  # * Check an individual option for documentation:
+  # 
+  #     Then the option "--force" should be documented
+  # 
+  # * Checks that the help has a proper usage banner
+  # 
+  #     Then the banner should be present
+  # 
+  # * Checks that the banner includes the version
+  # 
+  #     Then the banner should include the version
+  # 
+  # * Checks that the usage banner indicates it takes options via <tt>[options]</tt>
+  # 
+  #     Then the banner should document that this app takes options
+  # 
+  # * Do the opposite; check that you don't indicate options are accepted
+  # 
+  #     Then the banner should document that this app takes no options
+  # 
+  # * Checks that the app's usage banner documents that its arguments are <tt>args</tt>
+  # 
+  #     Then the banner should document that this app's arguments are "args"
+  # 
+  # * Do the opposite; check that your app doesn't take any arguments
+  # 
+  #     Then the banner should document that this app takes no arguments
+  # 
+  # * Check for a usage description which occurs after the banner and a blank line
+  # 
+  #     Then there should be a one-line summary of what the app does
+  # 
+  module Cucumber
+  end
+end
 When /^I get help for "([^"]*)"$/ do |app_name|
   @app_name = app_name
   step %(I run `#{app_name} --help`)

data/lib/methadone/execution_strategy/base.rb

@@ -1,10 +1,4 @@
 module Methadone
-  # Module to contain ExecutionStrategy implementations.
-  # To build your own simply implement two methods:
-  #
-  # <tt>exception_meaning_command_not_found</tt>:: return the class that, if caught, means that the underlying command
-  #                                                couldn't be found.  This is needed because currently impelmentations
-  #                                                throw an exception, but they don't all throw the same one.
   module ExecutionStrategy
     # Base for any ExecutionStrategy implementation.  Currently, this is nothing more than an interface
     # specification.

data/lib/methadone/main.rb

@@ -14,31 +14,37 @@ module Methadone
   # in a sensible way.  You can use as much or as little as you want, though
   # you must at least use #main to get any benefits.
   #
+  # Further, you must provide access to a logger via a method named
+  # #logger.  If you include Methadone::CLILogging, this will be done for you
+  #
   # You also get a more expedient interface to OptionParser as well
   # as checking for required arguments to your app.  For example, if
   # we want our app to accept a negatable switch named "switch", a flag
   # named "flag", and two arguments "needed" (which is required) 
   # and "maybe" which is optional, we can do the following:
   #
-  #     #!/usr/bin/env ruby -w
+  #     #!/usr/bin/env ruby
   #       
   #     require 'methadone'
   #      
-  #     include Methadone::Main
-  #     
-  #     main do |needed, maybe|
-  #       options[:switch] => true or false, based on command line
-  #       options[:flag] => value of flag passed on command line
-  #     end
-  #     
-  #     # Proxy to an OptionParser instance's on method
-  #     on("--[no]-switch")
-  #     on("--flag VALUE")
+  #     class App
+  #       include Methadone::Main
+  #       include Methadone::CLILogging
+  #       
+  #       main do |needed, maybe|
+  #         options[:switch] => true or false, based on command line
+  #         options[:flag] => value of flag passed on command line
+  #       end
+  #       
+  #       # Proxy to an OptionParser instance's on method
+  #       on("--[no]-switch")
+  #       on("--flag VALUE")
   #
-  #     arg :needed
-  #     arg :maybe, :optional
-  #     
-  #     go!
+  #       arg :needed
+  #       arg :maybe, :optional
+  #       
+  #       go!
+  #     end
   #
   # Our app then acts as follows:
   #
@@ -47,9 +53,18 @@ module Methadone
   #     $ our_app foo
   #     # => succeeds; "maybe" in main is nil
   #
-  # This also includes Methadone::CLILogging to give you access to simple logging
+  # Note that we've done all of this inside a class that we called +App+.  This isn't strictly
+  # necessary, and you can just +include+ Methadone::Main and Methadone::CLILogging at the root
+  # of your +bin+ file if you like.  This is somewhat unsafe, because +self+ inside the +bin+
+  # file is Object, and any methods you create (or cause to be created via +include+) will be
+  # present on *every* object.  This can cause odd problems, so it's recommended that you
+  # *not* do this.
+  #
   module Main
-    include Methadone::CLILogging
+    def self.included(k)
+      k.extend(self)
+    end
+
     # Declare the main method for your app.
     # This allows you to specify the general logic of your
     # app at the top of your bin file, but can rely on any methods
@@ -97,6 +112,14 @@ module Methadone
       @leak_exceptions = leak
     end
 
+    # Set the name of the environment variable where users can place default
+    # options for your app.  Omit this to disable the feature.
+    def defaults_from_env_var(env_var)
+      @env_var = env_var
+      opts.separator ''
+      opts.separator "Default values can be placed in the #{env_var} environment variable"
+      opts.separator ''
+    end
 
     # Start your command-line app, exiting appropriately when
     # complete.
@@ -113,6 +136,11 @@ module Methadone
     #
     def go!
       normalize_defaults
+      if @env_var
+        String(ENV[@env_var]).split(/\s+/).each do |arg|
+          ::ARGV.unshift(arg)
+        end
+      end
       opts.parse!
       opts.check_args!
       result = call_main
@@ -122,7 +150,7 @@ module Methadone
         exit 0
       end
     rescue OptionParser::ParseError => ex
-      error ex.message
+      logger.error ex.message
       puts
       puts opts.help
       exit 64 # Linux standard for bad command line
@@ -253,12 +281,12 @@ module Methadone
       @main_block.call(*ARGV)
     rescue Methadone::Error => ex
       raise ex if ENV['DEBUG']
-      error ex.message unless no_message? ex
+      logger.error ex.message unless no_message? ex
       ex.exit_code
     rescue => ex
       raise ex if ENV['DEBUG']
       raise ex if @leak_exceptions
-      error ex.message unless no_message? ex
+      logger.error ex.message unless no_message? ex
       70 # Linux sysexit code for internal software error
     end
 

data/lib/methadone/sh.rb

@@ -11,15 +11,51 @@ module Methadone
   # Module with various helper methods for executing external commands.
   # In most cases, you can use #sh to run commands and have decent logging
   # done.  You will likely use this in a class that also mixes-in
-  # Methadone::CLILogging.  If you *don't*, you must provide a logger
-  # via #set_sh_logger.
+  # Methadone::CLILogging (remembering that Methadone::Main mixes this in for you).  
+  # If you <b>don't</b>, you must provide a logger via #set_sh_logger.
+  #
+  # == Examples
+  #
+  #    include Methadone::SH
+  #
+  #    sh 'cp foo.txt /tmp'
+  #    # => logs the command to DEBUG, executes the command, logs its output to DEBUG and its
+  #    #    error output to WARN, returns 0
+  # 
+  #    sh 'cp non_existent_file.txt /nowhere_good'
+  #    # => logs the command to DEBUG, executes the command, logs its output to INFO and
+  #    #    its error output to WARN, returns the nonzero exit status of the underlying command
+  # 
+  #    sh! 'cp non_existent_file.txt /nowhere_good'
+  #    # => same as above, EXCEPT, raises a Methadone::FailedCommandError
+  #
+  #     sh 'cp foo.txt /tmp' do
+  #       # Behaves exactly as before, but this block is called after
+  #     end
+  #
+  #     sh 'cp non_existent_file.txt /nowhere_good' do
+  #       # This block isn't called, since the command failed
+  #     end
+  #
+  #     sh 'ls -l /tmp/' do |stdout|
+  #       # stdout contains the output of the command
+  #     end
+  #     sh 'ls -l /tmp/ /non_existent_dir' do |stdout,stderr|
+  #       # stdout contains the output of the command,
+  #       # stderr contains the standard error output.
+  #      end
+  #    
+  # == Handling remote execution
   #
   # In order to work on as many Rubies as possible, this class defers the actual execution
   # to an execution strategy.  See #set_execution_strategy if you think you'd like to override
   # that, or just want to know how it works.
   #
-  # This is not intended to be a complete replacement for Open3, but instead of make common cases
-  # and good practice easy to accomplish.
+  # == More complex execution and subprocess management
+  #
+  # This is not intended to be a complete replacement for Open3 or an enhanced means of managing subprocesses.
+  # This is to make it easy for you to shell-out to external commands and have your app be robust and
+  # easy to maintain.
   module SH
     # Run a shell command, capturing and logging its output.
     # If the command completed successfully, it's output is logged at DEBUG.

data/lib/methadone/version.rb

@@ -1,3 +1,3 @@
 module Methadone
-  VERSION = "1.0.0.rc1"
+  VERSION = "1.0.0.rc2"
 end

data/templates/full/bin/executable.erb

@@ -4,35 +4,40 @@ require 'optparse'
 require 'methadone'
 require '<%= gemname %>'
 
-include Methadone::Main
-
-main do # Add args you want: |like,so|
-  # your program code here
-  # You can access CLI options via
-  # the options Hash
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+  main do # Add args you want: |like,so|
+    # your program code here
+    # You can access CLI options via
+    # the options Hash
+  end
+
+  # supplemental methods here
+
+  # Declare command-line interface here
+
+  # description "one line description of your app"
+  #
+  # Accept flags via:
+  # on("--flag VAL","Some flag")
+  # options[flag] will contain VAL
+  #
+  # Specify switches via:
+  # on("--[no-]switch","Some switch")
+  #
+  # Or, just call OptionParser methods on opts
+  #
+  # Require an argument
+  # arg :some_arg 
+  #
+  # # Make an argument optional
+  # arg :optional_arg, :optional
+
+  version <%= module_name %>::VERSION
+
+  use_log_level_option
+
+  go!
 end
-
-# supplemental methods here
-
-# Declare command-line interface here
-
-# description "one line description of your app"
-#
-# Accept flags via:
-# on("--flag VAL","Some flag")
-# options[flag] will contain VAL
-#
-# Specify switches via:
-# on("--[no-]switch","Some switch")
-#
-# Or, just call OptionParser methods on opts
-#
-# Require an argument
-# arg :some_arg 
-#
-# # Make an argument optional
-# arg :optional_arg, :optional
-
-version <%= module_name %>::VERSION
-
-go!

data/test/test_cli_logger.rb

@@ -41,6 +41,27 @@ class TestCLILogger < BaseTest
     }
   end
 
+  test_that "when both stderr and stdin are ttys, setting the level higher than WARN should affect the error logger" do
+    Given {
+      class << $stderr
+        def tty?; true; end
+      end
+      class << $stdout
+        def tty?; true; end
+      end
+
+      @logger = CLILogger.new
+      @logger.level = Logger::ERROR
+    }
+
+    When log_all_levels
+
+    Then {
+      $stdout.string.should == ""
+      $stderr.string.should == "error\nfatal\n"
+    }
+  end
+
   test_that "logger sends debug and info to stdout, and warns, errors, and fatals to stderr" do
     Given a_logger_with_blank_format
     When log_all_levels

data/test/test_cli_logging.rb

@@ -92,6 +92,56 @@ class TestCLILogging < BaseTest
     }
   end
 
+  test_that "when we call use_log_level_option, it sets up logging level CLI options" do
+    Given {
+      @app = MyAppThatActsLikeItUsesMain.new
+      @app.call_use_log_level_option
+      @level = any_int
+    }
+    When {
+      @app.use_option(@level)
+    }
+    Then {
+      @app.logger.level.should == @level
+    }
+  end
+
+  test_that "when we call use_log_level_option, then later change the logger, that logger gets the proper level set" do
+    Given {
+      @app = MyAppThatActsLikeItUsesMain.new
+      @app.call_use_log_level_option
+      @level = any_int
+    }
+    When {
+      @app.use_option(@level)
+      @other_logger = OpenStruct.new
+      @app.change_logger(@other_logger)
+    }
+    Then {
+      @other_logger.level.should == @level
+    }
+  end
+
+  class MyAppThatActsLikeItUsesMain
+    include Methadone::CLILogging
+
+    def call_use_log_level_option
+      use_log_level_option
+    end
+
+    def use_option(level)
+      @block.call(level)
+    end
+
+    def on(*args,&block)
+      @block = block
+    end
+
+    def logger
+      @logger ||= OpenStruct.new
+    end
+  end
+
   class MyClassThatLogsToStdout
     include Methadone::CLILogging
 

data/test/test_main.rb

@@ -6,21 +6,23 @@ class TestMain < BaseTest
   include Methadone::Main
 
   def setup
-    @logged = []
     @original_argv = ARGV.clone
     ARGV.clear
     @old_stdout = $stdout
     $stdout = StringIO.new
+    @logged = StringIO.new
+    @custom_logger = Logger.new(@logged)
   end
 
-  # Override error so we can capture what's being logged at this level
-  def error(string)
-    @logged << string
+  # Override the built-in logger so we can capture it
+  def logger
+    @custom_logger
   end
 
   def teardown
     set_argv @original_argv
     ENV.delete('DEBUG')
+    ENV.delete('APP_OPTS')
     $stdout = @old_stdout
   end
 
@@ -29,11 +31,11 @@ class TestMain < BaseTest
       @called = false
       main do
         begin
-          debug "debug"
-          info "info"
-          warn "warn"
-          error "error"
-          fatal "fatal"
+          logger.debug "debug"
+          logger.info "info"
+          logger.warn "warn"
+          logger.error "error"
+          logger.fatal "fatal"
           @called = true
         rescue => ex
           puts ex.message
@@ -106,10 +108,6 @@ class TestMain < BaseTest
     end
   end
 
-  def main_that_exits(exit_status)
-    proc { main { exit_status } }
-  end
-
   test_that "go exits with 70, which is the Linux sysexits.h code for this sort of thing, if there's an exception" do
     Given {
       main do
@@ -497,7 +495,75 @@ class TestMain < BaseTest
     }
   end
 
-  private
+  test_that "when getting defaults from an environment variable, show it in the help output" do
+    Given app_to_use_environment
+    When {
+      @help_string = opts.to_s
+    }
+    Then {
+      @help_string.should match /Default values can be placed in the APP_OPTS environment variable/
+    }
+  end
+
+  test_that "when we want to get opts from the environment, we can" do
+    Given app_to_use_environment
+    And {
+      @flag_value = '56'
+      @some_arg = any_string
+      set_argv([])
+      ENV['APP_OPTS'] = "--switch --flag=#{@flag_value} #{@some_arg}"
+    }
+    When {
+      @code = lambda { go! }
+    }
+    Then {
+      assert_exits(0,'',&@code)
+      @switch.should == true
+      @flag.should == @flag_value
+      @args.should == [@some_arg]
+    }
+  end
+
+  test_that "environment args are overridden by the command line" do
+    Given app_to_use_environment
+    And {
+      @flag_value = any_string
+      ENV['APP_OPTS'] = "--switch --flag=#{any_string}"
+      set_argv(['--flag',@flag_value])
+    }
+    When {
+      @code = lambda { go! }
+    }
+    Then {
+      assert_exits(0,'',&@code)
+      @switch.should == true
+      @flag.should == @flag_value
+    }
+  end
+
+private
+
+  def main_that_exits(exit_status)
+    proc { main { exit_status } }
+  end
+
+  def app_to_use_environment
+    lambda {
+      @switch = nil
+      @flag = nil
+      @args = nil
+      main do |*args|
+        @switch = options[:switch]
+        @flag = options[:flag]
+        @args = args
+      end
+
+      defaults_from_env_var 'APP_OPTS'
+
+      on('--switch','Some Switch')
+      on('--flag FOO','Some Flag')
+    }
+  end
 
   def main_shouldve_been_called
     Proc.new { assert @called,"Main block wasn't called?!" }
@@ -516,7 +582,7 @@ class TestMain < BaseTest
   def run_go!; proc { go! }; end
 
   def assert_logged_at_error(expected_message)
-    @logged.should include expected_message
+    @logged.string.should include expected_message
   end
 
   def assert_exits(exit_code,message='',&block)

metadata

@@ -1,167 +1,126 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: methadone
-version: !ruby/object:Gem::Version 
-  hash: 1276957477555352091
+version: !ruby/object:Gem::Version
+  version: 1.0.0.rc2
   prerelease: 6
-  segments: 
-  - 1
-  - 0
-  - 0
-  - rc
-  - 1
-  version: 1.0.0.rc1
 platform: ruby
-authors: 
+authors:
 - davetron5000
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-22 00:00:00 -05:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-02-04 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bundler
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70291259020440 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec-expectations
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259020440
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: &70291259018880 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 15
-        segments: 
-        - 2
-        - 6
-        version: "2.6"
+      - !ruby/object:Gem::Version
+        version: '2.6'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259018880
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70291259018280 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rdoc
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259018280
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70291259017480 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 21
-        segments: 
-        - 3
-        - 9
-        version: "3.9"
+      - !ruby/object:Gem::Version
+        version: '3.9'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: cucumber
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259017480
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: &70291259016720 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 17
-        segments: 
-        - 1
-        - 1
-        - 1
+      - !ruby/object:Gem::Version
         version: 1.1.1
   type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: aruba
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259016720
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: &70291259016160 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: simplecov
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259016160
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &70291259015380 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 1
-        segments: 
-        - 0
-        - 5
-        version: "0.5"
+      - !ruby/object:Gem::Version
+        version: '0.5'
   type: :development
-  version_requirements: *id007
-- !ruby/object:Gem::Dependency 
-  name: clean_test
   prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259015380
+- !ruby/object:Gem::Dependency
+  name: clean_test
+  requirement: &70291259014700 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 0
-        - 10
-        version: "0.10"
+      - !ruby/object:Gem::Version
+        version: '0.10'
   type: :development
-  version_requirements: *id008
-- !ruby/object:Gem::Dependency 
-  name: mocha
   prerelease: false
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  version_requirements: *70291259014700
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &70291259014060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id009
-description: Methadone provides a lot of small but useful features for developing a command-line app, including an opinionated bootstrapping process, some helpful cucumber steps, and some classes to bridge logging and output into a simple, unified, interface
-email: 
+  prerelease: false
+  version_requirements: *70291259014060
+description: Methadone provides a lot of small but useful features for developing
+  a command-line app, including an opinionated bootstrapping process, some helpful
+  cucumber steps, and some classes to bridge logging and output into a simple, unified,
+  interface
+email:
 - davetron5000 at gmail.com
-executables: 
+executables:
 - methadone
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rvmrc
 - .travis.yml
@@ -218,43 +177,31 @@ files:
 - test/test_cli_logging.rb
 - test/test_main.rb
 - test/test_sh.rb
-has_rdoc: true
 homepage: http://github.com/davetron5000/methadone
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      hash: 25
-      segments: 
-      - 1
-      - 3
-      - 1
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-
 rubyforge_project: methadone
-rubygems_version: 1.5.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Kick the bash habit and start your command-line apps off right
-test_files: 
+test_files:
 - features/bootstrap.feature
 - features/license.feature
 - features/readme.feature