methadone-rehab 1.9.2

data/lib/methadone/cli_logger.rb

@@ -0,0 +1,133 @@
+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 <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 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:
+  # 
+  # * You can override the devices used by passing different devices to the constructor
+  # * You can adjust the level of message that goes to the error logger via error_level=
+  # * You can adjust the format for messages to the error logger separately via error_formatter=
+  #
+  # === Example
+  #
+  #     logger = CLILogger.new
+  #     logger.debug("Starting up") # => only the standard output gets this
+  #     logger.warn("careful!") # => only the standard error gets this
+  #     logger.error("Something went wrong!") # => only the standard error gets this
+  #
+  #     logger = CLILogger.new
+  #     logger.error_level = Logger::ERROR
+  #     logger.debug("Starting up") # => only the standard output gets this
+  #     logger.warn("careful!") # => only the standard OUTPUT gets this
+  #     logger.error("Something went wrong!") # => only the standard error gets this
+  #     
+  #     logger = CLILogger.new('logfile.txt')
+  #     logger.debug("Starting up") # => logfile.txt gets this
+  #     logger.error("Something went wrong!") # => BOTH logfile.txt AND the standard error get this
+  class CLILogger < Logger
+    BLANK_FORMAT = proc { |severity,datetime,progname,msg|
+      msg + "\n"
+    }
+
+    # Helper to proxy methods to the super class AND to the internal error logger
+    # 
+    # +symbol+:: Symbol for name of the method to proxy
+    def self.proxy_method(symbol) #:nodoc:
+      old_name = "old_#{symbol}".to_sym
+      alias_method old_name,symbol
+      define_method symbol do |*args,&block|
+        send(old_name,*args,&block)
+        @stderr_logger.send(symbol,*args,&block)
+      end
+    end
+
+    proxy_method :'formatter='
+    proxy_method :'datetime_format='
+
+    def add(severity, message = nil, progname = nil, &block) #:nodoc:
+      if @split_logs 
+        unless severity >= @stderr_logger.level
+          super(severity,message,progname,&block)
+        end
+      else
+        super(severity,message,progname,&block)
+      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
+    # pretty smart about doing the right thing.  If both log devices are
+    # ttys, e.g. one is going to standard error and the other to the standard output,
+    # messages only appear once in the overall output stream.  In other words,
+    # an ERROR logged will show up *only* in the standard error.  If either
+    # log device is NOT a tty, then all messages go to +log_device+ and only
+    # errors go to +error_device+
+    #
+    # +log_device+:: device where all log messages should go, based on level
+    # +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)
+
+      log_device_tty   = tty?(log_device)
+      error_device_tty = tty?(error_device)
+
+      @split_logs = log_device_tty && error_device_tty
+
+      self.level = Logger::Severity::INFO
+      @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 *unless* both devices are TTYs.
+    #
+    # +level+:: a constant from Logger::Severity for the level of messages that should go
+    #           to the error logger
+    def error_level=(level)
+      @stderr_logger.level = level
+    end
+
+    # Overrides the formatter for the error logger.  A future call to #formatter= will
+    # affect both, so the order of the calls matters.
+    #
+    # +formatter+:: Proc that handles the formatting, the same as for #formatter=
+    def error_formatter=(formatter)
+      @stderr_logger.formatter=formatter
+    end
+
+  private
+
+    def tty?(device_or_string)
+      return device_or_string.tty? if device_or_string.respond_to? :tty?
+      false
+    end
+
+  end
+end

data/lib/methadone/cli_logging.rb

@@ -0,0 +1,138 @@
+module Methadone
+  # Provides easier access to a shared Methadone::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 Methadone::CLILogger
+  #       
+  #       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 @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 Methadone::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)', :global) 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/methadone/cucumber.rb

@@ -0,0 +1,174 @@
+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.  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
+
+Given /^PENDING/ do
+  pending "test needs to be writen"
+end
+
+When /^I get help for "([^"]*)"$/ do |app_name|
+  @app_name = app_name
+  step %(I run `#{app_name} --help`)
+end
+
+When /^I get help for "([^"]*)" subcommand "([^"]*)"$/ do |app_name,subcommands|
+  @app_name = app_name
+  @subcommands = subcommands.split(/\s+/)
+  step %(I run `#{app_name} #{subcommands} --help`)
+end
+
+Then /^the following (argument|option)s should be documented:$/ do |type,table|
+  table.raw.each do |row|
+    step %(the #{type} "#{row[0]}" should be documented #{row[1]})
+  end
+end
+
+Then /^there should be (\d+) options listed$/ do |option_count|
+  match = all_output.match(/(?m)Options:\n((?:(?!\n\n).)*)(?:\n\n|\z)/)
+  real_option_count = match[1].chomp.split(/\n/).select {|l| l =~ /^ *-/}.length
+  real_option_count.should == option_count.to_i
+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 following (commands|global options) should be documented:$/ do |type, table|
+  table.raw.each do |row|
+    step %(the output should match /(?m)#{type.capitalize}:((?!\\n\\n).)*\\n +#{Regexp.escape(row[0])}/)
+  end
+end
+
+Then /^there should be (\d+) command listed$/ do |command_count|
+  match = all_output.match(/(?m)Commands:\n((?:  [^\n]*\n)+)(\n|\z)/)
+  real_command_count = match[1].chomp.split(/\n/).length
+  real_command_count.should == command_count.to_i.should
+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 takes global options$/ do
+  step %(the output should match /\[global options\]/)
+  step %(the output should contain "Global options")
+end
+
+Then /^the banner should document that this app takes commands$/ do
+  step %(the output should match /command \[command options and args...\]/)
+  step %(the output should contain "\\nCommands:")
+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] =~ /(?:which can take )?(many|any)( values)?/
+    option = "[#{option}]" if row[1] =~ /(which is optional|which can take any( values)?|optional|any)/
+    option
+  }.join(' ')
+  step %(the output should contain "#{expected_arguments}")
+end
+
+Then /^there should be (\d+) arguments? listed$/ do |arg_count|
+  match = all_output.match(/(?m)\nArguments:\n((?:    [^\n]*\n)+)(?:\n|\z)/)
+  real_arg_count = match[1].chomp.split(/\n    (?=[^ ])/).length
+  real_arg_count.should == arg_count.to_i
+end
+
+Then /^the argument "([^"]*)" should be documented(.*)$/ do |arg,qualifiers|
+  if qualifiers.strip == "which is optional"
+    arg += " (optional)"
+  end
+  step %(the output should match /(?m)Arguments:((?!\\n\\n).)*\\n    #{Regexp.escape(arg)}/)
+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 document that this app takes no commands$/ do
+  step %(the output should not match /command \[command options and args...\]/)
+  step %(the output should not contain "\\nCommands:")
+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 >= 4
+  # [0] is a blank line,
+  # [1] is our banner, which we've checked for
+  output_lines[2].should match(/^\s*$/)
+  output_lines[3].should match(/^\w+\s+\w+/)
+end

data/lib/methadone/error.rb

@@ -0,0 +1,32 @@
+module Methadone
+  # Standard exception you can throw to exit with a given 
+  # status code. Generally, you should prefer Methadone::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