boson 0.4.0 → 1.0.0

data/lib/boson/options.rb

@@ -2,9 +2,10 @@ module Boson
   # This module contains the methods used to define the default option types.
   #
   # === Creating Your Own Option Type
-  # Defining your own option type simply requires one method (create_@type) to parse the option value and create
-  # the desired object. To create an option type :date, you could create the following create_date method:
-  #   # Drop this in ~/.boson/commands/date_option.rb
+  # Defining your own option type simply requires one method (create_@type) to
+  # parse the option value and create the desired object. To create an option
+  # type :date, you could create the following create_date method:
+  #   # Drop this in ~/.bosonrc
   #   module Boson::Options::Date
   #     def create_date(value)
   #       # value should be mm/dd
@@ -13,46 +14,49 @@ module Boson
   #   end
   #   Boson::OptionParser.send :include, Boson::Options::Date
   #
-  # Modify your config to load this new library by default:
-  #   :defaults:
-  #   - date_option
-  #
-  # In a FileLibrary, we could then use this new option:
-  #   module Calendar
-  #     #@options :day=>:date
+  # In a Library, we could then use this new option:
+  #   class Calendar < Boson::Runner
+  #     options :day=>:date
   #     def appointments(options={})
   #       # ...
   #     end
   #   end
   #   # >> appointments '-d 10/10'   -> {:day=>#<Date: 4910229/2,0,2299161> }
-  # As you can see, a date object is created from the :date option's value and passed into appointments().
+  # As you can see, a date object is created from the :date option's value and
+  # passed into appointments().
   #
   # Some additional tips on the create_* method:
   # * The argument passed to the method is the option value from the user.
   # * To access the current option name use @current_option.
-  # * To access the hash of attributes the current option has use OptionParser.current_attributes. See
-  #   OptionParser.new for more about option attributes.
+  # * To access the hash of attributes the current option has use
+  #   OptionParser.current_attributes. See OptionParser.new for more about
+  #   option attributes.
   #
-  # There are two optional methods per option type: validate_@type and usage_for_@type i.e. validate_date and usage_for_date.
-  # Like create_@type, validate_@type takes the option's value. If the value validation fails, raise an
-  # OptionParser::Error with a proper message. All user-defined option types automatically validate for an option value's existence.
-  # The usage_for_* method takes an option's name (i.e. --day) and returns a usage string to be wrapped in '[ ]'. If no usage is defined
-  # the default would look like '[--day=:date]'. Consider using the OptionParser.default_usage helper method for your usage.
+  # There are two optional methods per option type: validate_@type and
+  # usage_for_@type i.e. validate_date and usage_for_date.  Like create_@type,
+  # validate_@type takes the option's value. If the value validation fails,
+  # raise an OptionParser::Error with a proper message. All user-defined option
+  # types automatically validate for an option value's existence.  The
+  # usage_for_* method takes an option's name (i.e. --day) and returns a usage
+  # string to be wrapped in '[ ]'. If no usage is defined the default would look
+  # like '[--day=:date]'. Consider using the OptionParser#default_usage helper
+  # method for your usage.
   module Options
-    #:stopdoc:
     # Parse/create methods
     def create_string(value)
-      if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s})
-        value = auto_alias_value(values, value)
-        validate_enum_values(values, value)
+      if (values = current_attributes[:values]) &&
+        (values = values.sort_by {|e| e.to_s})
+          value = auto_alias_value(values, value)
+          validate_enum_values(values, value)
       end
       value
     end
 
     def create_boolean(value)
-      if (!@opt_types.key?(dasherize(@current_option)) && @current_option =~ /^no-(\w+)$/)
-        opt = (opt = original_no_opt($1)) ? undasherize(opt) : $1
-        (@current_option.replace(opt) && false)
+      if (!@opt_types.key?(dasherize(@current_option)) &&
+         @current_option =~ /^no-(\w+)$/)
+           opt = (opt = original_no_opt($1)) ? undasherize(opt) : $1
+           (@current_option.replace(opt) && false)
       else
         true
       end
@@ -65,7 +69,8 @@ module Boson
     def create_array(value)
       splitter = current_attributes[:split] || ','
       array = value.split(splitter)
-      if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s })
+      if (values = current_attributes[:values]) &&
+        (values = values.sort_by {|e| e.to_s })
         if current_attributes[:regexp]
           array = array.map {|e|
             (new_values = values.grep(/#{e}/)).empty? ? e : new_values
@@ -98,25 +103,35 @@ module Boson
       end
 
       # Creates array pairs, grouping array of keys with a value
-      aoa = Hash[*value.split(/(?::)([^#{Regexp.quote(splitter)}]+)#{Regexp.quote(splitter)}?/)].to_a
-      aoa.each_with_index {|(k,v),i| aoa[i][0] = keys.join(splitter) if k == '*' } if keys
+      aoa = Hash[*value.split(
+        /(?::)([^#{Regexp.quote(splitter)}]+)#{Regexp.quote(splitter)}?/
+      )].to_a
+      if keys
+        aoa.each_with_index {|(k,v),i| aoa[i][0] = keys.join(splitter) if k == '*' }
+      end
       aoa.inject({}) {|t,(k,v)| k.split(splitter).each {|e| t[e] = v }; t }
     end
 
     # Validation methods
     def validate_string(value)
-      raise OptionParser::Error, "cannot pass '#{value}' as an argument to option '#{@current_option}'" if valid?(value)
+      if valid?(value)
+        raise OptionParser::Error,
+          "cannot pass '#{value}' as an argument to option '#{@current_option}'"
+      end
     end
 
     def validate_numeric(value)
       unless value =~ OptionParser::NUMERIC and $& == value
-        raise OptionParser::Error, "expected numeric value for option '#{@current_option}'; got #{value.inspect}"
+        raise OptionParser::Error,
+          "expected numeric value for option '#{@current_option}'; got " +
+          value.inspect
       end
     end
 
     def validate_hash(value)
       if !value.include?(':') && !current_attributes[:default_keys]
-        raise(OptionParser::Error, "invalid key:value pair for option '#{@current_option}'")
+        raise OptionParser::Error,
+          "invalid key:value pair for option '#{@current_option}'"
       end
     end
 
@@ -140,7 +155,6 @@ module Boson
     def usage_for_hash(opt)
       default_usage opt, "A:B,C:D"
     end
-    #:startdoc:
   end
 end
 Boson::OptionParser.send :include, Boson::Options

data/lib/boson/runner.rb

@@ -1,81 +1,73 @@
-module Boson
-  # Base class for runners.
-  class Runner
-    class<<self
-      attr_accessor :debug
-
-      # Enables view, adds local load path and loads default_libraries
-      def init
-        View.enable
-        add_load_path
-        Manager.load default_libraries, load_options
-      end
+require 'boson'
 
-      # Libraries that come with Boson
-      def default_libraries
-        Boson.repos.map {|e| e.config[:defaults] || [] }.flatten + [Boson::Commands::Core, Boson::Commands::WebCore]
-      end
-
-      # Libraries detected in repositories
-      def detected_libraries
-        Boson.repos.map {|e| e.detected_libraries }.flatten.uniq
-      end
+module Boson
+  # Defines a RunnerLibrary for use by executables as a simple way to map
+  # methods to subcommands
+  class Runner < BareRunner
+    def self.inherited(mod)
+      @help_added ||= add_command_help
+      Inspector.enable all_classes: true, module: mod.singleton_class
+    end
 
-      # Libraries specified in config files and detected_libraries
-      def all_libraries
-        Boson.repos.map {|e| e.all_libraries }.flatten.uniq
-      end
+    def self.default_libraries
+      [self]
+    end
 
-      # Returns true if commands are being executed from a non-ruby shell i.e. bash. Returns false if
-      # in a ruby shell i.e. irb.
-      def in_shell?
-        !!@in_shell
-      end
+    def self.start(args=ARGV)
+      ENV['BOSONRC'] ||= ''
+      super
+      init
+      command, options, args = parse_args(args)
 
-      # Returns true if in commandline with verbose flag or if set explicitly. Useful in plugins.
-      def verbose?
-        @verbose.nil? ? Boson.const_defined?(:BinRunner) && BinRunner.options[:verbose] : @verbose
+      if options[:help] || command.nil?
+        display_default_usage
+      else
+        execute_command(command, args)
       end
+    end
 
-      #:stopdoc:
-      def verbose=(val)
-        @verbose = val
-      end
+    def self.execute_command(cmd, args)
+      Command.find(cmd) ? super : no_command_error(cmd)
+    end
 
-      def in_shell=(val)
-        @in_shell = val
+    def self.display_help(cmd)
+      puts "Usage: #{app_name} #{cmd.name} #{cmd.basic_usage}".rstrip, ""
+      if cmd.options
+        puts "Options:"
+        cmd.option_parser.print_usage_table(no_headers: true)
+        puts ""
       end
+      puts "Description:\n  #{cmd.desc || 'TODO'}"
+    end
 
-      def add_load_path
-        Boson.repos.each {|repo|
-          if repo.config[:add_load_path] || File.exists?(File.join(repo.dir, 'lib'))
-            $: <<  File.join(repo.dir, 'lib') unless $:.include? File.expand_path(File.join(repo.dir, 'lib'))
-          end
-        }
-      end
+    def self.display_default_usage
+      commands = Boson.commands.sort_by(&:name).map {|c| [c.name, c.desc.to_s] }
+      puts "Usage: #{app_name} COMMAND [ARGS]", "", "Available commands:",
+        Util.format_table(commands), "",
+        "For help on a command: #{app_name} COMMAND -h"
+    end
 
-      def load_options
-        {:verbose=>@options[:verbose]}
-      end
+    def self.app_name
+      File.basename($0).split(' ').first
+    end
 
-      def autoload_command(cmd, opts={:verbose=>verbose?})
-        Index.read
-        (lib = Index.find_library(cmd)) && Manager.load(lib, opts)
-        lib
-      end
+    private
+    def self.add_command_help
+      # Overrides Scientist' default help
+      Scientist.extend(Module.new do
+        def run_help_option(cmd)
+          Boson::Runner.display_help(cmd)
+        end
+      end)
 
-      def define_autoloader
-        class << ::Boson.main_object
-          def method_missing(method, *args, &block)
-            if Runner.autoload_command(method.to_s)
-              send(method, *args, &block) if respond_to?(method)
-            else
-              super
-            end
-          end
+      # Ensure all commands have -h
+      Command.extend(Module.new do
+        def new_attributes(name, library)
+          super.update(option_command: true)
         end
-      end
-      #:startdoc:
+      end)
+      # Ensure this is only called once
+      true
     end
   end
-end
+end

data/lib/boson/runner_library.rb

@@ -0,0 +1,31 @@
+module Boson
+  # Library created by Runner
+  class RunnerLibrary < Library
+    handles {|source|
+      source.is_a?(Module) && defined?(Runner) && source.ancestors.include?(Runner)
+    }
+
+    def self.delegate_runner_methods(runner, mod)
+      mod.module_eval do
+        runner.public_instance_methods(false).each do |meth|
+          define_method(meth) do |*args, &block|
+            runner.new.send(meth, *args, &block)
+          end
+        end
+      end
+    end
+
+    def set_name(runner)
+      @runner = runner #reference needed elsewhere
+      @runner.to_s[/[^:]+$/].downcase
+    end
+
+    # Since Boson expects libraries to be modules, creates a temporary module
+    # and delegates its methods to it
+    def load_source_and_set_module
+      @module = Util.create_module Boson::Commands, @name
+      MethodInspector.instance.rename_store_key @runner, @module
+      self.class.delegate_runner_methods @runner, @module
+    end
+  end
+end

data/lib/boson/scientist.rb

@@ -1,15 +1,15 @@
 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).
+  # 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.
   #
-  # 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.
+  # 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:
@@ -18,7 +18,8 @@ module Boson
   #     args
   #   end
   #
-  # When Scientist wraps around foo(), it can take arguments normally or as a shell command:
+  # 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
   #
@@ -34,7 +35,7 @@ module Boson
     # Handles all Scientist errors.
     class Error < StandardError; end
 
-    attr_accessor :global_options, :rendered, :render
+    attr_accessor :global_options
     @no_option_commands ||= []
     @option_commands ||= {}
     @object_methods = {}
@@ -44,16 +45,17 @@ module Boson
       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)
+        obj.singleton_class.send(:define_method, e, cmd_block)
       }
     rescue Error
-      $stderr.puts "Error: #{$!.message}"
+      warn "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:
+    # 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})
@@ -81,49 +83,51 @@ module Boson
         raise Error, "No method exists to redefine command '#{command.name}'."
       end
       lambda {|*args|
-        Scientist.translate_and_render(obj, command, args) {|args|
+        Scientist.analyze(obj, command, args) {|args|
           Scientist.object_methods(obj)[command.name].call(*args)
         }
       }
     end
 
-    #:stopdoc:
+    # Returns hash of methods for an object
     def object_methods(obj)
       @object_methods[obj] ||= {}
     end
 
+    # option command for given command
     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
+    # Runs a command given its object and arguments
+    def analyze(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]
+      return run_help_option(@command) if @global_options[:help]
+      during_analyze(&block)
     rescue OptionParser::Error, Error
-      raise if Runner.in_shell?
-      message = @global_options[:verbose] ? "#{$!}\n#{$!.backtrace.inspect}" : $!.message
-      $stderr.puts "Error: " + message
+      raise if Boson.in_shell
+      warn "Error: #{$!}"
+    end
+
+    # Overridable method called during analyze
+    def during_analyze(&block)
+      process_result call_original_command(@args, &block)
+    end
+
+    # Hook method available after parse in translate_args
+    def after_parse; end
+
+    private
+    def call_original_command(args, &block)
+      block.call(args)
     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) }
+      after_parse
 
       if @current_options
         option_command.add_default_args(args, obj)
@@ -134,49 +138,12 @@ module Boson
       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
+    def run_help_option(cmd)
+      puts "#{cmd.full_name} #{cmd.usage}".rstrip
     end
 
-    def command_renders?
-      (!!@command.render_options ^ @global_options[:render]) && !Pipe.any_no_render_pipes?(@global_options)
+    def process_result(result)
+      result
     end
-    #:startdoc:
   end
 end