bosonson 0.304.1

data/lib/boson/scientist.rb

@@ -0,0 +1,182 @@
+module Boson
+  # Scientist wraps around and redefines an object's method to give it the following features:
+  # * Methods can take shell command input with options or receive its normal arguments. See the Commandification
+  #   section.
+  # * Methods have a slew of global options available. See OptionCommand for an explanation of basic global options.
+  # * Before a method returns its value, it pipes its return value through pipe commands if pipe options are specified. See Pipe.
+  # * Methods can have any number of optional views associated with them via global render options (see View). Views can be toggled
+  #   on/off with the global option --render (see OptionCommand).
+  #
+  # The main methods Scientist provides are redefine_command() for redefining an object's method with a Command object
+  # and commandify() for redefining with a hash of method attributes. Note that for an object's method to be redefined correctly,
+  # its last argument _must_ expect a hash.
+  #
+  # === Commandification
+  # Take for example this basic method/command with an options definition:
+  #   options :level=>:numeric, :verbose=>:boolean
+  #   def foo(*args)
+  #     args
+  #   end
+  #
+  # When Scientist wraps around foo(), it can take arguments normally or as a shell command:
+  #    foo 'one', 'two', :verbose=>true   # normal call
+  #    foo 'one two -v'                 # commandline call
+  #
+  #    Both calls return: ['one', 'two', {:verbose=>true}]
+  #
+  # Non-string arguments can be passed as well:
+  #    foo Object, 'two', :level=>1
+  #    foo Object, 'two -l1'
+  #
+  #    Both calls return: [Object, 'two', {:level=>1}]
+  module Scientist
+    extend self
+    # Handles all Scientist errors.
+    class Error < StandardError; end
+
+    attr_accessor :global_options, :rendered, :render
+    @no_option_commands ||= []
+    @option_commands ||= {}
+    @object_methods = {}
+
+    # Redefines an object's method with a Command of the same name.
+    def redefine_command(obj, command)
+      cmd_block = redefine_command_block(obj, command)
+      @no_option_commands << command if command.options.nil?
+      [command.name, command.alias].compact.each {|e|
+        obj.instance_eval("class<<self;self;end").send(:define_method, e, cmd_block)
+      }
+    rescue Error
+      $stderr.puts "Error: #{$!.message}"
+    end
+
+    # A wrapper around redefine_command that doesn't depend on a Command object. Rather you
+    # simply pass a hash of command attributes (see Command.new) or command methods and let OpenStruct mock a command.
+    # The only required attribute is :name, though to get any real use you should define :options and
+    # :arg_size (default is '*'). Example:
+    #   >> def checkit(*args); args; end
+    #   => nil
+    #   >> Boson::Scientist.commandify(self, :name=>'checkit', :options=>{:verbose=>:boolean, :num=>:numeric})
+    #   => ['checkit']
+    #   # regular ruby method
+    #   >> checkit 'one', 'two', :num=>13, :verbose=>true
+    #   => ["one", "two", {:num=>13, :verbose=>true}]
+    #   # commandline ruby method
+    #   >> checkit 'one two -v -n=13'
+    #   => ["one", "two", {:num=>13, :verbose=>true}]
+    def commandify(obj, hash)
+      raise ArgumentError, ":name required" unless hash[:name]
+      hash[:arg_size] ||= '*'
+      hash[:has_splat_args?] = true if hash[:arg_size] == '*'
+      fake_cmd = OpenStruct.new(hash)
+      fake_cmd.option_parser ||= OptionParser.new(fake_cmd.options || {})
+      redefine_command(obj, fake_cmd)
+    end
+
+    # The actual method which redefines a command's original method
+    def redefine_command_block(obj, command)
+      object_methods(obj)[command.name] ||= begin
+        obj.method(command.name)
+      rescue NameError
+        raise Error, "No method exists to redefine command '#{command.name}'."
+      end
+      lambda {|*args|
+        Scientist.translate_and_render(obj, command, args) {|args|
+          Scientist.object_methods(obj)[command.name].call(*args)
+        }
+      }
+    end
+
+    #:stopdoc:
+    def object_methods(obj)
+      @object_methods[obj] ||= {}
+    end
+
+    def option_command(cmd=@command)
+      @option_commands[cmd] ||= OptionCommand.new(cmd)
+    end
+
+    def call_original_command(args, &block)
+      block.call(args)
+    end
+
+    def translate_and_render(obj, command, args, &block)
+      @global_options, @command, original_args = {}, command, args.dup
+      @args = translate_args(obj, args)
+      return run_help_option if @global_options[:help]
+      run_pretend_option(@args)
+      render_or_raw call_original_command(@args, &block) unless @global_options[:pretend]
+    rescue OptionCommand::CommandArgumentError
+      run_pretend_option(@args ||= [])
+      return if !@global_options[:pretend] && run_verbose_help(option_command, original_args)
+      raise unless @global_options[:pretend]
+    rescue OptionParser::Error, Error
+      raise if Runner.in_shell?
+      message = @global_options[:verbose] ? "#{$!}\n#{$!.backtrace.inspect}" : $!.message
+      $stderr.puts "Error: " + message
+    end
+
+    def translate_args(obj, args)
+      option_command.modify_args(args)
+      @global_options, @current_options, args = option_command.parse(args)
+      return if @global_options[:help]
+
+      (@global_options[:delete_options] || []).map {|e|
+        @global_options.keys.map {|k| k.to_s }.grep(/^#{e}/)
+      }.flatten.each {|e| @global_options.delete(e.to_sym) }
+
+      if @current_options
+        option_command.add_default_args(args, obj)
+        return args if @no_option_commands.include?(@command)
+        args << @current_options
+        option_command.check_argument_size(args)
+      end
+      args
+    end
+
+    def run_verbose_help(option_command, original_args)
+      global_opts = option_command.parse_global_options(original_args)
+      if global_opts[:help] && global_opts[:verbose]
+        @global_options = global_opts
+        run_help_option
+        return true
+      end
+      false
+    end
+
+    def run_help_option
+      opts = @global_options[:verbose] ? ['--verbose'] : []
+      opts << "--render_options=#{@global_options[:usage_options]}" if @global_options[:usage_options]
+      Boson.invoke :usage, @command.full_name + " " + opts.join(' ')
+    end
+
+    def run_pretend_option(args)
+      if @global_options[:verbose] || @global_options[:pretend]
+        puts "Arguments: #{args.inspect}", "Global options: #{@global_options.inspect}"
+      end
+      @rendered = true if @global_options[:pretend]
+    end
+
+    def render_or_raw(result)
+      if (@rendered = can_render?)
+        if @global_options.key?(:class) || @global_options.key?(:method)
+          result = Pipe.scientist_process(result, @global_options, :config=>@command.config, :args=>@args, :options=>@current_options)
+        end
+        View.render(result, OptionCommand.delete_non_render_options(@global_options.dup), false)
+      else
+        Pipe.scientist_process(result, @global_options, :config=>@command.config, :args=>@args, :options=>@current_options)
+      end
+    rescue StandardError
+      raise Error, $!.message, $!.backtrace
+    end
+
+    def can_render?
+      render.nil? ? command_renders? : render
+    end
+
+    def command_renders?
+      (!!@command.render_options ^ @global_options[:render]) && !Pipe.any_no_render_pipes?(@global_options)
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/util.rb

@@ -0,0 +1,129 @@
+module Boson
+  # Collection of utility methods used throughout Boson.
+  module Util
+    extend self
+    # From Rails ActiveSupport, converts a camelcased string to an underscored string:
+    # 'Boson::MethodInspector' -> 'boson/method_inspector'
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+       gsub(/([a-z\d])([A-Z])/,'\1_\2').
+       tr("-", "_").
+       downcase
+    end
+
+    # From Rails ActiveSupport, does the reverse of underscore:
+    # 'boson/method_inspector' -> 'Boson::MethodInspector'
+    def camelize(string)
+      Hirb::Util.camelize(string)
+    end
+
+    # Converts a module/class string to the actual constant.
+    # Returns nil if not found.
+    def constantize(string)
+      any_const_get(camelize(string))
+    end
+
+    # Returns a constant like const_get() no matter what namespace it's nested in.
+    # Returns nil if the constant is not found.
+    def any_const_get(name)
+      Hirb::Util.any_const_get(name)
+    end
+
+    # Detects new object/kernel methods, gems and modules created within a block.
+    # Returns a hash of what's detected.
+    # Valid options and possible returned keys are :methods, :object_methods, :modules, :gems.
+    def detect(options={}, &block)
+      options = {:methods=>true, :object_methods=>true}.merge!(options)
+      original_gems = Object.const_defined?(:Gem) ? Gem.loaded_specs.keys : []
+      original_object_methods = Object.instance_methods
+      original_instance_methods = class << Boson.main_object; instance_methods end
+      original_modules = modules if options[:modules]
+      block.call
+      detected = {}
+      detected[:methods] = options[:methods] ? (class << Boson.main_object; instance_methods end -
+        original_instance_methods) : []
+      detected[:methods] -= (Object.instance_methods - original_object_methods) unless options[:object_methods]
+      detected[:gems] = Gem.loaded_specs.keys - original_gems if Object.const_defined? :Gem
+      detected[:modules] = modules - original_modules if options[:modules]
+      detected
+    end
+
+    # Safely calls require, returning false if LoadError occurs.
+    def safe_require(lib)
+      begin
+        require lib
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    # Returns all modules that currently exist.
+    def modules
+      all_modules = []
+      ObjectSpace.each_object(Module) {|e| all_modules << e}
+      all_modules
+    end
+
+    # Creates a module under a given base module and possible name. If the module already exists or conflicts
+    # per top_level_class_conflict, it attempts to create one with a number appended to the name.
+    def create_module(base_module, name)
+      desired_class = camelize(name)
+      possible_suffixes = [''] + %w{1 2 3 4 5 6 7 8 9 10}
+      if (suffix = possible_suffixes.find {|e| !base_module.const_defined?(desired_class+e) &&
+        !top_level_class_conflict(base_module, "#{base_module}::#{desired_class}#{e}") })
+        base_module.const_set(desired_class+suffix, Module.new)
+      end
+    end
+
+    # Behaves just like the unix which command, returning the full path to an executable based on ENV['PATH'].
+    def which(command)
+      ENV['PATH'].split(File::PATH_SEPARATOR).map {|e| File.join(e, command) }.find {|e| File.exists?(e) }
+    end
+
+    # Deep copies any object if it can be marshaled. Useful for deep hashes.
+    def deep_copy(obj)
+      Marshal::load(Marshal::dump(obj))
+    end
+
+    # Recursively merge hash1 with hash2.
+    def recursive_hash_merge(hash1, hash2)
+      hash1.merge(hash2) {|k,o,n| (o.is_a?(Hash)) ? recursive_hash_merge(o,n) : n}
+    end
+
+    # From Rubygems, determine a user's home.
+    def find_home
+      Hirb::Util.find_home
+    end
+
+    # Returns name of top level class that conflicts if it exists. For example, for base module Boson::Commands,
+    # Boson::Commands::Alias conflicts with Alias if Alias exists.
+    def top_level_class_conflict(base_module, conflicting_module)
+      (conflicting_module =~ /^#{base_module}.*::([^:]+)/) && Object.const_defined?($1) && $1
+    end
+
+    # Splits array into array of arrays with given element
+    def split_array_by(arr, divider)
+      arr.inject([[]]) {|results, element|
+        (divider == element) ? (results << []) : (results.last << element)
+        results
+      }
+    end
+
+    # Regular expression search of a list with underscore anchoring of words.
+    # For example 'some_dang_long_word' can be specified as 's_d_l_w'.
+    def underscore_search(input, list, first_match=false)
+      meth = first_match ? :find : :select
+      return (first_match ? input : [input]) if list.include?(input)
+      input = input.to_s
+      if input.include?("_")
+        underscore_regex = input.split('_').map {|e| Regexp.escape(e) }.join("([^_]+)?_")
+        list.send(meth) {|e| e.to_s =~ /^#{underscore_regex}/ }
+      else
+        escaped_input = Regexp.escape(input)
+        list.send(meth) {|e| e.to_s =~ /^#{escaped_input}/ }
+      end
+    end
+  end
+end

data/lib/boson/version.rb

@@ -0,0 +1,3 @@
+module Boson
+  VERSION = '0.304.1'
+end

data/lib/boson/view.rb

@@ -0,0 +1,95 @@
+module Boson
+  # This module generates views for a command by handing it to {Hirb}[http://tagaholic.me/hirb/]. Since Hirb can be customized
+  # to generate any view, commands can have any views associated with them!
+  #
+  # === Views with Render Options
+  # To pass rendering options to a Hirb helper as command options, a command has to define the options with
+  # the render_options method attribute:
+  #
+  #   # @render_options :fields=>[:a,:b]
+  #   def list(options={})
+  #     [{:a=>1, :b=>2}, {:a=>10,:b=>11}]
+  #   end
+  #
+  #   # To see that the render_options method attribute actually passes the :fields option by default:
+  #   >> list '-p'   # or list '--pretend'
+  #   Arguments: []
+  #   Global options: {:pretend=>true, :fields=>[:a, :b]}
+  #
+  #   >> list
+  #   +----+----+
+  #   | a  | b  |
+  #   +----+----+
+  #   | 1  | 2  |
+  #   | 10 | 11 |
+  #   +----+----+
+  #   2 rows in set
+  #
+  #   # To create a vertical table, we can pass --vertical, one of the default global render options.
+  #   >> list '-V'   # or list '--vertical'
+  #   *** 1. row ***
+  #   a: 1
+  #   b: 2
+  #   ...
+  #
+  #   # To get the original return value use the global option --render
+  #   >> list '-r'  # or list '--render'
+  #   => [{:a=>1, :b=>2}, {:a=>10,:b=>11}]
+  #
+  # === Boson and Hirb
+  # Since Boson uses {Hirb's auto table helper}[http://tagaholic.me/hirb/doc/classes/Hirb/Helpers/AutoTable.html]
+  # by default, you may want to read up on its many options. To use any of them in commands, define them locally
+  # with render_options or globally by adding them under the :render_options key of the main config.
+  # What if you want to use your own helper class? No problem. Simply pass it with the global :class option.
+  #
+  # When using the default helper, one of the most important options to define is :fields. Aside from controlling what fields
+  # are displayed, it's used to set :values option attributes for related options i.e. :sort and :query. This provides handy option
+  # value aliasing via OptionParser. If you don't set :fields, Boson will try to set its :values with field-related options i.e.
+  # :change_fields, :filters and :headers.
+  module View
+    extend self
+
+    # Enables hirb and reads a config file from the main repo's config/hirb.yml.
+    def enable
+      unless @enabled
+        Hirb::View.enable(:config_file=>File.join(Boson.repo.config_dir, 'hirb.yml'))
+        Hirb::Helpers::Table.filter_any = true
+      end
+      @enabled = true
+    end
+
+    # Renders any object via Hirb. Options are passed directly to
+    # {Hirb::Console.render_output}[http://tagaholic.me/hirb/doc/classes/Hirb/Console.html#M000011].
+    def render(object, options={}, return_obj=false)
+      if options[:inspect]
+        puts(object.inspect)
+      else
+        render_object(object, options, return_obj) unless silent_object?(object)
+      end
+    end
+
+    #:stopdoc:
+    def class_config(klass)
+      opts = (Hirb::View.formatter_config[klass] || {}).dup
+      opts.delete(:ancestor)
+      opts.merge!((opts.delete(:options) || {}).dup)
+      OptionParser.make_mergeable!(opts)
+      opts
+    end
+
+    def toggle_pager
+      Hirb::View.toggle_pager
+    end
+
+    def silent_object?(obj)
+      [nil,false,true].include?(obj)
+    end
+
+    def render_object(object, options={}, return_obj=false)
+      options[:class] ||= :auto_table
+      render_result = Hirb::Console.render_output(object, options)
+      return_obj ? object : render_result
+    end
+    #:startdoc:
+  end
+end

data/test/argument_inspector_test.rb

@@ -0,0 +1,62 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+describe "scrape_with_text" do
+  def args_from(file_string)
+    ArgumentInspector.scrape_with_text(file_string, "blah")
+  end
+
+  it "parses arguments of class method" do
+    args_from("    def YAML.blah( filepath )\n").should == [['filepath']]
+  end
+
+  it "parses arguments with no spacing" do
+    args_from("def bong; end\ndef blah(arg1,arg2='val2')\nend").should == [["arg1"], ['arg2', "'val2'"]]
+  end
+
+  it "parses arguments with spacing" do
+    args_from("\t def blah(  arg1=val1, arg2 = val2)").should == [["arg1","val1"], ["arg2", "val2"]]
+  end
+
+  it "parses arguments without parenthesis" do
+    args_from(" def blah arg1, arg2, arg3={}").should == [['arg1'], ['arg2'], ['arg3','{}']]
+  end
+end
+
+describe "scrape_with_eval" do
+  def args_from(string)
+    # methods need options to have their args parsed with ArgumentInspector
+    string.gsub!(/(def blah)/, 'options :a=>1; \1')
+    Inspector.enable
+    ::Boson::Commands::Aaa.module_eval(string)
+    Inspector.disable
+    MethodInspector.store[:args]['blah']
+  end
+
+  before_all { eval "module ::Boson::Commands::Aaa; end"; }
+  before { MethodInspector.mod_store[::Boson::Commands::Aaa] = {} }
+
+  it "determines arguments with literal defaults" do
+    args_from("def blah(arg1,arg2='val2'); end").should == [['arg1'], ['arg2','val2']]
+  end
+
+  it "determines splat arguments" do
+    args_from("def blah(arg1, *args); end").should == [['arg1'], ["*args"]]
+  end
+
+  it "determines arguments with local values before a method" do
+    body = "AWESOME='awesome'; def sweet; 'ok'; end; def blah(arg1=AWESOME, arg2=sweet); end"
+    args_from(body).should == [['arg1', 'awesome'], ['arg2', 'ok']]
+  end
+
+  it "doesn't get arguments with local values after a method" do
+    args_from("def blah(arg1=nope) end; def nope; 'nope'; end").should == nil
+  end
+
+  it "doesn't determine arguments of a private method" do
+    args_from("private; def blah(arg1,arg2); end").should == nil
+  end
+
+  it "doesn't determine arguments if an error occurs" do
+    args_from("def blah(arg1,arg2=raise); end").should == nil
+  end
+end