methadone 0.2.0 → 0.3.0

data/README.rdoc

@@ -6,9 +6,12 @@ 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.
 
-Currently, this is under development and has the following to offer:
+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.
+
+Currently, this library is under development and has the following to offer:
 
 * Bootstrapping a new CLI app
+* Lightweight DSL to structure your bin file
 * 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
@@ -48,6 +51,62 @@ The +methadone+ command-line app will bootstrap a new command-line app, setting
 
 Basically, this sets you up with all the boilerplate that you *should* be using to write a command-line app.
 
+== DSL for your `bin` file
+
+A canonical `OptionParser` 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
+    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
+
+    go!
+
++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.
+
+Why not just <tt>def main</tt> and call that method?  +go!+ also handles exceptions:
+
+* Any uncaught exception that isn't a subclass of <tt>Methadone::Error</tt> will cause the app to exit with a 70 (standard Linux "internal error" exit status) and print the exception's messages to standard error, no backtrace
+* An instance of <tt>Methadone::Error</tt>, if caught, will have similar behavior, but the +exit_code+ method will be called on the exception to determine the exit status.  You can trigger this exception via <tt>exit_now! exit_stats,message</tt>
+
 == 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

data/bin/methadone

@@ -11,13 +11,13 @@ include FileUtils
 include Methadone::Main
 include Methadone::CLI
 
-main do |basedir,force|
-  check_and_prepare_basedir!(basedir,force)
+main do |app_name|
+  check_and_prepare_basedir!(app_name,options[:force])
 
-  gemname = File.basename(basedir)
+  gemname = File.basename(app_name)
   debug "Creating project for gem #{gemname}"
 
-  chdir File.dirname(basedir)
+  chdir File.dirname(app_name)
 
   %x[bundle gem #{gemname}]
 
@@ -41,26 +41,11 @@ main do |basedir,force|
   ], :before => /^end\s*$/
 end
 
-options = {}
-option_parser = OptionParser.new do |opts|
-  executable = File.basename(__FILE__)
-  opts.banner = "Usage: #{executable} [options] app_name\n\n" +
-  "Kick the bash habit by bootstrapping your Ruby command-line apps\n\nOptions:"
+description "Kick the bash habit by bootstrapping your Ruby command-line apps"
 
-  opts.on("--force","Overwrite files if they exist") do
-    options[:force] = true
-  end
-end
-
-option_parser.parse!
+on("--force","Overwrite files if they exist")
 
-EXE = File.expand_path(__FILE__)
-
-if ARGV.empty?
-  STDERR.puts("error: app_dir required")
-  exit 2
-end
+arg :app_name, :required
 
-ARGV << options[:force]
 go!
 

data/features/bootstrap.feature

@@ -79,10 +79,7 @@ Feature: Bootstrap a new command-line app
   Scenario: We must supply a dirname
     When I run `methadone`
     Then the exit status should not be 0
-    And the stderr should contain:
-    """
-    error: app_dir required
-    """
+    And the stderr should match /'app_name' is required/
 
     @debug
   Scenario: Help is properly documented

data/features/step_definitions/bootstrap_steps.rb

@@ -9,3 +9,7 @@ end
 Given /^my app's name is "([^"]*)"$/ do |app_name|
   @app_name = app_name
 end
+
+Then /^the stderr should match \/([^\/]*)\/$/ do |expected|
+  assert_matching_output(expected, all_stderr)
+end

data/lib/methadone.rb

@@ -3,3 +3,4 @@ require 'methadone/cli_logger'
 require 'methadone/cli_logging'
 require 'methadone/main'
 require 'methadone/error'
+# Note: DO NOT require cli.rb OR cucumber.rb here

data/lib/methadone/cli.rb

@@ -83,7 +83,7 @@ module Methadone
 
     # Get the location of the templates for profile "from"
     def template_dir(from)
-      File.join(File.dirname(EXE),'..','templates',from.to_s)
+      File.join(File.dirname(__FILE__),'..','..','templates',from.to_s)
     end
 
     def template_dirs_in(profile)

data/lib/methadone/main.rb

@@ -1,8 +1,44 @@
+require 'optparse'
+
 module Methadone
   # Include this module to gain access to the "canonical command-line app structure"
   # DSL.  This is a *very* lightweight layer on top of what you might
   # normally write that gives you just a bit of help to keep your code structured
-  # in a sensible way.
+  # 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.
+  #
+  # 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 optional, we can do the following:
+  #
+  #     #!/usr/bin/env ruby -w
+  #       
+  #     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")
+  #
+  #     arg :needed
+  #     arg :maybe, :optional
+  #     
+  #     go!
+  #
+  # Our app then acts as follows:
+  #
+  #     $ our_app 
+  #     # => parse error: 'needed' is required
+  #     $ our_app foo
+  #     # => succeeds; "maybe" in main is nil
   #
   # This also includes Methadone::CLILogging to give you access to simple logging
   module Main
@@ -40,21 +76,36 @@ module Methadone
     # To run this method, call #go!
     def main(&block)
       @main_block = block
+      @options = {}
+      @option_parser = OptionParserProxy.new(OptionParser.new,@options)
     end
 
+
     # Start your command-line app, exiting appropriately when
-    # complete
+    # complete.
     #
     # This *will* exit your program when it completes.  If your
     # #main block evaluates to an integer, that value will be sent
     # to Kernel#exit, otherwise, this will exit with 0
+    #
+    # If the command-line options couldn't be parsed, this
+    # will exit with 64 and whatever message OptionParser provided.
+    #
+    # If a required argument (see #arg) is not found, this exits with
+    # 64 and a message about that missing argument.
+    #
     def go!
+      opts.parse!
+      opts.check_args!
       result = call_main
       if result.kind_of? Fixnum
         exit result
       else
         exit 0
       end
+    rescue OptionParser::ParseError => ex
+      error ex.message
+      exit 64 # Linux standard for bad command line
     end
 
     # Call this to exit the program immediately
@@ -66,6 +117,65 @@ module Methadone
       raise Methadone::Error.new(exit_code,message)
     end
 
+    # Returns an OptionParser that you can use
+    # to declare your command-line interface.  The object returned as
+    # an additional feature that implements typical use of OptionParser.
+    #
+    #     opts.on("--flag VALUE")
+    #
+    # Does this under the covers:
+    #
+    #     opts.on("--flag VALUE") do |value|
+    #       options[:flag] = value
+    #     end
+    #
+    # Since, most of the time, this is all you want to do,
+    # this makes it more expedient to do so.  The key that is
+    # is set in #options will be a symbol of the option name, without
+    # the dashes.  Note that if you use multiple option names, a key
+    # will be generated for each.  Further, if you use the negatable form,
+    # only the positive key will be set, e.g. for <tt>--[no-]verbose</tt>,
+    # only <tt>:verbose</tt> will be set (to true or false).
+    def opts
+      @option_parser
+    end
+
+    # Calls <tt>opts.on</tt> with the given arguments
+    def on(*args,&block)
+      opts.on(*args,&block)
+    end
+
+    # Sets the name of an arguments your app accepts.  Note
+    # that no sanity checking is done on the configuration
+    # of your arguments you create via multiple calls to this method.
+    # Namely, the last argument should be the only one that is
+    # a :many or a :any, but the system here won't sanity check that.
+    #
+    # +arg_name+:: name of the argument to appear in documentation
+    #              This will be converted into a String and used to create
+    #              the banner (unless you have overridden the banner)
+    # +options+:: list (not Hash) of options:
+    #             <tt>:required</tt> - this arg is required (this is the default)
+    #             <tt>:optional</tt> - this arg is optional
+    #             <tt>:one</tt> - only one of this arg should be supplied (default)
+    #             <tt>:many</tt> - many of this arg may be supplied, but at least one is required
+    #             <tt>:any</tt> - any number, include zero, may be supplied
+    def arg(arg_name,*options)
+      opts.arg(arg_name,*options)
+    end
+
+    # Set the description of your app for inclusion in the help output.
+    # +desc+:: a short, one-line description of your app
+    def description(desc)
+      opts.description(desc)
+    end
+
+    # Returns a Hash that you can use to store or retrieve options
+    # parsed from the command line
+    def options
+      @options
+    end
+
     private
 
     # Handle calling main and trapping any exceptions thrown
@@ -83,4 +193,124 @@ module Methadone
       exception.message.nil? || exception.message.strip.empty?
     end
   end
+
+  # A proxy to OptionParser that intercepts #on
+  # so that we can allow a simpler interface
+  class OptionParserProxy < BasicObject
+    # Create the proxy
+    #
+    # +option_parser+:: An OptionParser instance
+    # +options+:: a hash that will store the options
+    #             set via automatic setting.  The caller should
+    #             retain a reference to this
+    def initialize(option_parser,options)
+      @option_parser = option_parser
+      @options = options
+      @user_specified_banner = false
+      @accept_options = false
+      @args = []
+      @arg_options = {}
+      @description = nil
+      set_banner
+    end
+
+    def check_args!
+      ::Hash[@args.zip(::ARGV)].each do |arg_name,arg_value|
+        if @arg_options[arg_name].include? :required
+          if arg_value.nil?
+            message = "'#{arg_name.to_s}' is required"
+            message = "at least one " + message if @arg_options[arg_name].include? :many
+            raise ::OptionParser::ParseError,message
+          end
+        end
+      end
+    end
+
+    # If invoked as with OptionParser, behaves the exact same way.
+    # If invoked without a block, however, the options hash given
+    # to the constructor will be used to store
+    # the parsed command-line value.  See #opts in the Main module
+    # for how that works.
+    def on(*args,&block)
+      @accept_options = true
+      if block
+        @option_parser.on(*args,&block)
+      else
+        opt_names = option_names(*args)
+        @option_parser.on(*args) do |value|
+          opt_names.each { |name| @options[name] = value }
+        end
+      end
+      set_banner
+    end
+
+    # Proxies to underlying OptionParser
+    def banner=(new_banner)
+      @option_parser.banner=new_banner
+      @user_specified_banner = true
+    end
+
+    # Sets the banner to include these arg names
+    def arg(arg_name,*options)
+      options << :optional if options.include?(:any) && !options.include?(:optional)
+      options << :required unless options.include? :optional
+      options << :one unless options.include?(:any) || options.include?(:many)
+      @args << arg_name
+      @arg_options[arg_name] = options
+      set_banner
+    end
+
+    def description(desc)
+      @description = desc
+      set_banner
+    end
+
+    # Defers all calls save #on to 
+    # the underlying OptionParser instance
+    def method_missing(sym,*args,&block)
+      @option_parser.send(sym,*args,&block)
+    end
+
+    private
+
+    def set_banner
+      unless @user_specified_banner
+        new_banner="Usage: #{::File.basename($0)}"
+        new_banner += " [options]" if @accept_options
+        unless @args.empty?
+          new_banner += " " 
+          new_banner += @args.map { |arg|
+            if @arg_options[arg].include? :any
+              "[#{arg.to_s}...]"
+            elsif @arg_options[arg].include? :optional
+              "[#{arg.to_s}]"
+            elsif @arg_options[arg].include? :many
+              "#{arg.to_s}..."
+            else
+              arg.to_s
+            end
+          }.join(' ')
+        end
+        new_banner += "\n\n#{@description}" if @description
+        new_banner += "\n\nOptions:" if @accept_options
+
+        @option_parser.banner=new_banner
+      end
+    end
+
+    def option_names(*opts_on_args,&block)
+      opts_on_args.map { |arg|
+        if arg =~ /^--\[no-\]([^-\s]*)/
+          $1.to_sym
+        elsif arg =~ /^--([^-\s]*)/
+          $1.to_sym
+        elsif arg =~ /^-([^-\s]*)/
+          $1.to_sym
+        else
+          nil
+        end
+      }.reject(&:nil?)
+    end
+
+  end
 end

data/lib/methadone/version.rb

@@ -1,3 +1,3 @@
 module Methadone
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/templates/full/bin/executable.erb

@@ -5,31 +5,31 @@ require 'methadone'
 
 include Methadone::Main
 
-main do |options|
+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
 
-options = {}
-option_parser = OptionParser.new do |opts|
-  executable_name = File.basename(__FILE__)
-  opts.banner = "Usage: #{executable_name}"
-  # When/if you add options:
-  # opts.banner = "Usage: #{executable_name} [options]\n\n" +
-  # "One-line description of your app\n\n" +
-  # "Options:"
+# 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
 
-  # opts.on("--flag VAL","Some flag") do |val|
-  #   options[:flag] = val
-  # end
-  #
-  # opts.on("--[no-]switch","Some switch") do |switch|
-  #   options[:switch] = switch
-  # end
-end
-
-option_parser.parse!
-
-ARGV << options
 go!

data/test/test_main.rb

@@ -110,6 +110,153 @@ class TestMain < BaseTest
     assert_logged_at_error "oh noes"
   end
 
+  test "opts allows us to more expediently set up OptionParser" do
+    switch = nil
+    flag = nil
+    main do
+      switch = options[:switch]
+      flag = options[:flag]
+    end
+
+    opts.on("--switch") { options[:switch] = true }
+    opts.on("--flag FLAG") { |value| options[:flag] = value }
+
+    set_argv %w(--switch --flag value)
+
+    safe_go!
+
+    assert switch
+    assert_equal 'value',flag
+  end
+
+  test "when the command line is invalid, we exit with 64" do
+    main do
+    end
+
+    opts.on("--switch") { options[:switch] = true }
+    opts.on("--flag FLAG") { |value| options[:flag] = value }
+
+    set_argv %w(--invalid --flag value)
+
+    assert_exits(64) { go! }
+  end
+
+  test "omitting the block to opts simply sets the value in the options hash and returns itself" do
+    switch = nil
+    negatable = nil
+    flag = nil
+    f = nil
+    other = nil
+    some_other = nil
+    main do
+      switch = options[:switch]
+      flag = options[:flag]
+      f = options[:f]
+      negatable = options[:negatable]
+      other = options[:other]
+      some_other = options[:some_other]
+    end
+
+    on("--switch")
+    on("--[no-]negatable")
+    on("--flag FLAG","-f","Some documentation string")
+    on("--other") do 
+      options[:some_other] = true
+    end
+
+    set_argv %w(--switch --flag value --negatable --other)
+
+    safe_go!
+
+    assert switch
+    assert some_other
+    refute other
+    assert_equal 'value',flag
+    assert_equal 'value',f,opts.to_s
+    assert_match /Some documentation string/,opts.to_s
+  end
+
+  test "without specifying options, [options] doesn't show up in our banner" do
+    main {}
+
+    refute_match /\[options\]/,opts.banner
+  end
+
+  test "when specifying an option, [options] shows up in the banner" do
+    main {}
+    on("-s")
+
+    assert_match /\[options\]/,opts.banner
+  end
+
+  test "I can specify which arguments my app takes and if they are required" do
+    main {}
+    
+    arg :db_name
+    arg :user, :required
+    arg :password, :optional
+
+    assert_match /db_name user \[password\]$/,opts.banner
+  end
+
+  test "I can specify which arguments my app takes and if they are singular or plural" do
+    main {}
+    
+    arg :db_name
+    arg :user, :required, :one
+    arg :tables, :many
+
+    assert_match /db_name user tables...$/,opts.banner
+  end
+
+  test "I can specify which arguments my app takes and if they are singular or optional plural" do
+    main {}
+    
+    arg :db_name
+    arg :user, :required, :one
+    arg :tables, :any
+
+    assert_match /db_name user \[tables...\]$/,opts.banner
+  end
+
+  test "I can set a description for my app" do
+    main {}
+    description "An app of total awesome"
+
+    assert_match /^An app of total awesome$/,opts.banner
+  end
+
+  test "when I override the banner, we don't automatically do anything" do
+    main {}
+    opts.banner = "FOOBAR"
+
+    on("-s")
+
+    assert_equal "FOOBAR",opts.banner
+  end
+
+  test "when I say an argument is required and its omitted, I get an error" do
+    main {}
+    arg :foo
+    arg :bar
+
+    set_argv %w(blah)
+
+    assert_exits(64) { go! }
+    assert_logged_at_error("parse error: 'bar' is required")
+  end
+
+  test "when I say an argument is many and its omitted, I get an error" do
+    main {}
+    arg :foo
+    arg :bar, :many
+
+    set_argv %w(blah)
+
+    assert_exits(64) { go! }
+    assert_logged_at_error("parse error: at least one 'bar' is required")
+  end
+
   private
 
   # Calls go!, but traps the exit

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: methadone
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-01 00:00:00.000000000Z
+date: 2011-10-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-expectations
-  requirement: &70156777550060 !ruby/object:Gem::Requirement
+  requirement: &70140138849040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *70156777550060
+  version_requirements: *70140138849040
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70156777549580 !ruby/object:Gem::Requirement
+  requirement: &70140138848500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70156777549580
+  version_requirements: *70140138848500
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70156777548800 !ruby/object:Gem::Requirement
+  requirement: &70140138847780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '3.9'
   type: :development
   prerelease: false
-  version_requirements: *70156777548800
+  version_requirements: *70140138847780
 - !ruby/object:Gem::Dependency
   name: aruba
-  requirement: &70156777548320 !ruby/object:Gem::Requirement
+  requirement: &70140138847360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70156777548320
+  version_requirements: *70140138847360
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70156777547600 !ruby/object:Gem::Requirement
+  requirement: &70140138846780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,7 +65,7 @@ dependencies:
         version: '0.5'
   type: :development
   prerelease: false
-  version_requirements: *70156777547600
+  version_requirements: *70140138846780
 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,