optparse-plus 3.0.0

data/lib/optparse_plus/cli_logging.rb

@@ -0,0 +1,138 @@
+module OptparsePlus
+  # Provides easier access to a shared OptparsePlus::CLILogger instance.
+  #
+  # Include this module into your class, and #logger provides access to a shared logger.
+  # This is handy if you want all of your clases to have access to the same logger, but 
+  # don't want to (or aren't able to) pass it around to each class.
+  #
+  # This also provides methods for direct logging without going through the #logger
+  #
+  # === Example
+  #
+  #     class MyClass
+  #       include OptparsePlus::CLILogging
+  #       
+  #       def doit
+  #         debug("About to doit!")
+  #         if results
+  #           info("We did it!"
+  #         else
+  #           error("Something went wrong")
+  #         end
+  #         debug("Done doing it")
+  #       end
+  #     end
+  #
+  # Note that every class that mixes this in shares the *same logger instance*, so if you call #change_logger, this
+  # will change the logger for all classes that mix this in.  This is likely what you want.
+  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
+      @@logger ||= CLILogger.new
+    end
+
+    # Change the global logger that includers will use.  Useful if you
+    # don't want the default configured logger.  Note that the +change_logger+
+    # version is preferred because Ruby will often parse <tt>logger = Logger.new</tt> as
+    # the declaration of, and assignment to, of a local variable.  You'd need to
+    # do <tt>self.logger=Logger.new</tt> to be sure.  This method
+    # is a bit easier.
+    #
+    # +new_logger+:: the new logger.  May not be nil and should be a logger of some kind
+    def change_logger(new_logger)
+      raise ArgumentError,"Logger may not be nil" if new_logger.nil?
+      @@logger = new_logger
+      @@logger.level = @log_level if defined?(@log_level) && @log_level
+    end
+
+    alias logger= change_logger
+
+
+    # pass-through to <tt>logger.debug(progname,&block)</tt>
+    def debug(progname = nil, &block); logger.debug(progname,&block); end
+    # pass-through to <tt>logger.info(progname,&block)</tt>
+    def info(progname = nil, &block); logger.info(progname,&block); end
+    # pass-through to <tt>logger.warn(progname,&block)</tt>
+    def warn(progname = nil, &block); logger.warn(progname,&block); end
+    # pass-through to <tt>logger.error(progname,&block)</tt>
+    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 OptparsePlus::Main to set up a <tt>--log-level</tt> option for your app
+    # that will allow the user to configure the logging level. You can pass an optional hash with
+    # <tt>:toggle_debug_on_signal => <SIGNAME></tt> to enable runtime toggling of the log level by sending the
+    # signal <tt><SIGNAME></tt> to your app
+    #
+    # +args+:: optional hash
+    #
+    # Example:
+    #
+    #     main do 
+    #       # your app
+    #     end
+    #
+    #     use_log_level_option
+    #
+    #     go!
+    #
+    # Example with runtime toggling:
+    #
+    #
+    #     main do 
+    #       # your app
+    #     end
+    #
+    #     use_log_level_option :toggle_debug_on_signal => 'USR1'
+    #
+    #     go!
+    def use_log_level_option(args = {})
+      on("--log-level LEVEL",LOG_LEVELS,'Set the logging level',
+                                        '(' + LOG_LEVELS.keys.join('|') + ')',
+                                        '(Default: info)') do |level|
+        @log_level = level
+        @log_level_original = level
+        @log_level_toggled = false
+        logger.level = level
+
+        setup_toggle_trap(args[:toggle_debug_on_signal])
+      end
+    end
+
+  private
+
+    # Call this to toggle the log level between <tt>debug</tt> and its initial value
+    def toggle_log_level
+      @log_level_original = logger.level unless @log_level_toggled
+      logger.level = if @log_level_toggled
+                       @log_level_original
+                     else
+                       LOG_LEVELS['debug']
+                     end
+      @log_level_toggled = !@log_level_toggled
+      @log_level = logger.level
+    end
+
+    def setup_toggle_trap(signal)
+      if signal
+        Signal.trap(signal) do
+          toggle_log_level
+        end
+      end
+    end
+  end
+end

data/lib/optparse_plus/cucumber.rb

@@ -0,0 +1,119 @@
+module OptparsePlus
+  #
+  # **NOTE!** Cucumber is not recommened or supported by optparse_plus, as Aruba has diverged too much. This
+  # file is left here to allow you to update optparse_plus but still use Cucumber & Aruba on older versions.
+  #
+  # By <tt>require</tt>'ing <tt>optparse_plus/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.  By default,
+  #   the options won't be required to be negatable.
+  #
+  #     Then the following options should be documented:
+  #       |--force|
+  #       |-x     |
+  #
+  #     Then the following options should be documented:
+  #       |--force| which is negatable     |
+  #       |-x     | which is not negatable |
+  #
+  # * Check an individual option for documentation:
+  #
+  #     Then the option "--force" should be documented
+  #     Then the option "--force" should be documented which is negatable
+  #
+  # * 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
+  #       |foo|which is optional|
+  #       |bar|which is required|
+  #
+  # * 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`)
+end
+
+Then /^the following options should be documented:$/ do |options|
+  options.raw.each do |option|
+    step %(the option "#{option[0]}" should be documented #{option[1]})
+  end
+end
+
+Then /^the option "([^"]*)" should be documented(.*)$/ do |options,qualifiers|
+  options.split(',').map(&:strip).each do |option|
+    if qualifiers.strip == "which is negatable"
+      option = option.gsub(/^--/,"--[no-]")
+    end
+    step %(the output should match /\\s*#{Regexp.escape(option)}[\\s\\W]+\\w[\\s\\w][\\s\\w]+/)
+  end
+end
+
+Then /^the banner should be present$/ do
+  step %(the output should match /Usage: #{@app_name}/)
+end
+
+Then /^the banner should document that this app takes options$/ do
+  step %(the output should match /\[options\]/)
+  step %(the output should contain "Options")
+end
+
+Then /^the banner should document that this app's arguments are:$/ do |table|
+  expected_arguments = table.raw.map { |row|
+    option = row[0]
+    option = "[#{option}]" if row[1] == 'optional' || row[1] == 'which is optional'
+    option
+  }.join(' ')
+  step %(the output should contain "#{expected_arguments}")
+end
+
+Then /^the banner should document that this app takes no options$/ do
+  step %(the output should not contain "[options]")
+  step %(the output should not contain "Options")
+end
+
+Then /^the banner should document that this app takes no arguments$/ do
+  step %(the output should match /Usage: #{@app_name}\\s*\(\\[options\\]\)?$/)
+end
+
+Then /^the banner should include the version$/ do
+  step %(the output should match /v\\d+\\.\\d+\\.\\d+/)
+end
+
+Then /^there should be a one line summary of what the app does$/ do
+  output_lines = all_output.split(/\n/)
+  output_lines.size.should >= 3
+  # [0] is our banner, which we've checked for
+  output_lines[1].should match(/^\s*$/)
+  output_lines[2].should match(/^\w+\s+\w+/)
+end

data/lib/optparse_plus/error.rb

@@ -0,0 +1,32 @@
+module OptparsePlus
+  # Standard exception you can throw to exit with a given 
+  # status code. Generally, you should prefer OptparsePlus::Main#exit_now! over using
+  # this directly, however you may wish to create a rich hierarchy of exceptions that extend from
+  # this in your app, so this is provided if you wish to do so.
+  class Error < StandardError
+    attr_reader :exit_code
+    # Create an Error with the given status code and message
+    def initialize(exit_code,message=nil)
+      super(message)
+      @exit_code = exit_code
+    end
+  end
+
+  # Thrown by certain methods when an externally-called command exits nonzero
+  class FailedCommandError < Error
+
+    # The command that caused the failure
+    attr_reader :command
+
+    # exit_code:: exit code of the command that caused this
+    # command:: the entire command-line that caused this
+    # custom_error_message:: an error message to show the user instead of the boilerplate one.  Useful
+    #                        for allowing this exception to bubble up and exit the program, but to give
+    #                        the user something actionable.
+    def initialize(exit_code,command,custom_error_message = nil)
+      error_message = String(custom_error_message).empty? ?  "Command '#{command}' exited #{exit_code}" : custom_error_message
+      super(exit_code,error_message)
+      @command = command
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/base.rb

@@ -0,0 +1,34 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # Base for any ExecutionStrategy implementation.  Currently, this is nothing more than an interface
+    # specification.
+    class Base
+      # Executes the command and returns the results back.  This
+      # should do no logging or other logic other than to execute the
+      # command and return the required results.  If command is an
+      # array, use exec directly bypassing any tokenization, shell or
+      # otherwise; otherwise use the normal shell interpretation of
+      # the command string.
+      #
+      # command:: the command-line to run, as an Array or a String
+      #
+      # Returns an array of size 3:
+      # <tt>[0]</tt>:: The standard output of the command as a String, never nil
+      # <tt>[1]</tt>:: The standard error output of the command as a String, never nil
+      # <tt>[2]</tt>:: A Process::Status-like objects that responds to <tt>exitstatus</tt> which returns
+      #                the exit code of the command (e.g. 0 for success).
+      def run_command(command)
+        subclass_must_implement!
+      end
+
+      # Returns the class that, if caught by calling #run_command, represents the underlying command
+      # not existing.  For example, in MRI Ruby, if you try to execute a non-existent command,
+      # you get a Errno::ENOENT.
+      def exception_meaning_command_not_found
+        subclass_must_implement!
+      end
+    protected
+      def subclass_must_implement!; raise "subclass must implement"; end
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/jvm.rb

@@ -0,0 +1,37 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # <b>OptparsePlus Internal - treat as private</b>
+    #
+    # OptparsePlus::ExecutionStrategy for the JVM that uses JVM classes to run the command and get its results.
+    class JVM < Base
+      def run_command(command)
+        process = case command
+                  when String then
+                    java.lang.Runtime.get_runtime.exec(command)
+                  else
+                    java.lang.Runtime.get_runtime.exec(*command)
+                  end
+        process.get_output_stream.close
+        stdout = input_stream_to_string(process.get_input_stream)
+        stderr = input_stream_to_string(process.get_error_stream)
+        exitstatus = process.wait_for
+        [stdout.chomp,stderr.chomp,OpenStruct.new(:exitstatus => exitstatus)]
+      end
+
+      def exception_meaning_command_not_found
+        NativeException
+      end
+
+    private
+      def input_stream_to_string(is)
+        ''.tap do |string|
+          ch = is.read
+          while ch != -1
+            string << ch
+            ch = is.read
+          end
+        end
+      end
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/mri.rb

@@ -0,0 +1,16 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # <b>OptparsePlus Internal - treat as private</b>
+    #
+    # Base strategy for MRI rubies.
+    class MRI < Base
+      def run_command(command)
+        raise "subclass must implement"
+      end
+
+      def exception_meaning_command_not_found
+        Errno::ENOENT
+      end
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/open_3.rb

@@ -0,0 +1,16 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # <b>OptparsePlus Internal - treat as private</b>
+    #
+    # Implementation for modern Rubies that uses the built-in Open3 library
+    class Open_3 < MRI
+      def run_command(command)
+        stdout,stderr,status = case command
+                               when String then Open3.capture3(command)
+                               else Open3.capture3(*command)
+                               end
+        [stdout.chomp,stderr.chomp,status]
+      end
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/open_4.rb

@@ -0,0 +1,22 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # <b>OptparsePlus Internal - treat as private</b>
+    #
+    # ExecutionStrategy for non-modern Rubies that must rely on
+    # Open4 to get access to the standard output AND error.
+    class Open_4 < MRI
+      def run_command(command)
+        pid, stdin_io, stdout_io, stderr_io =
+          case command
+          when String then Open4::popen4(command)
+          else Open4::popen4(*command)
+          end
+        stdin_io.close
+        stdout = stdout_io.read
+        stderr = stderr_io.read
+        _ , status = Process::waitpid2(pid)
+        [stdout.chomp,stderr.chomp,status]
+      end
+    end
+  end
+end

data/lib/optparse_plus/execution_strategy/rbx_open_4.rb

@@ -0,0 +1,12 @@
+module OptparsePlus
+  module ExecutionStrategy
+    # <b>OptparsePlus Internal - treat as private</b>
+    #
+    # For RBX; it throws a different exception when a command isn't found, so we override that here.
+    class RBXOpen_4 < Open_4
+      def exception_meaning_command_not_found
+        [Errno::EINVAL] + Array(super)
+      end
+    end
+  end
+end

data/lib/optparse_plus/exit_now.rb

@@ -0,0 +1,40 @@
+module OptparsePlus
+  # Provides #exit_now! and #help_now!.  You might mix this into your business logic classes if they will
+  # need to exit the program with a human-readable error message.
+  module ExitNow
+    def self.included(k)
+      k.extend(self)
+    end
+    # Call this to exit the program immediately
+    # with the given error code and message.
+    #
+    # +exit_code+:: exit status you'd like to exit with
+    # +message+:: message to display to the user explaining the problem
+    #
+    # If +exit_code+ is a String and +message+ is omitted, +exit_code+ will be used as the message
+    # and the actual exit code will be 1.
+    #
+    # === Examples
+    #
+    #     exit_now!(4,"Oh noes!") 
+    #       # => exit app with status 4 and show the user "Oh noes!" on stderr
+    #     exit_now!("Oh noes!")   
+    #       # => exit app with status 1 and show the user "Oh noes!" on stderr
+    #     exit_now!(4)            
+    #       # => exit app with status 4 and dont' give the user a message (how rude of you)
+    def exit_now!(exit_code,message=nil)
+      if exit_code.kind_of?(String) && message.nil?
+        raise OptparsePlus::Error.new(1,exit_code)
+      else
+        raise OptparsePlus::Error.new(exit_code,message)
+      end
+    end
+
+    # Exit the program as if the user made an error invoking your app, providing
+    # them the message as well as printing the help.  This is useful if
+    # you have complex UI validation that can't be done by OptionParser.
+    def help_now!(message)
+      raise OptionParser::ParseError.new(message)
+    end
+  end
+end