boson 0.4.0 → 1.0.0

data/lib/boson/bin_runner.rb

@@ -0,0 +1,114 @@
+module Boson
+  # This class handles the boson executable.
+  #
+  # Usage for the boson shell command looks like this:
+  #   boson [GLOBAL OPTIONS] [COMMAND] [ARGS] [COMMAND OPTIONS]
+  #
+  # The boson executable comes with several global options: :version, :execute,
+  # :ruby_debug, :debug, and :load_path.
+  class BinRunner < BareRunner
+    GLOBAL_OPTIONS.update(
+      version: {type: :boolean, desc: "Prints the current version"},
+      execute: {type: :string,
+        desc: "Executes given arguments as a one line script"},
+      ruby_debug: {type: :boolean, desc: "Sets $DEBUG", alias: 'D'},
+      debug: {type: :boolean, desc: "Prints debug info for boson"},
+      load_path: {type: :string, desc: "Add to front of $LOAD_PATH", alias: 'I'}
+    )
+
+    module API
+      attr_accessor :command
+
+      # Executes functionality from either an option or a command
+      def execute_option_or_command(options, command, args)
+        options[:execute] ? eval_execute_option(options[:execute]) :
+          execute_command(command, args)
+      end
+
+      # Evaluates :execute option.
+      def eval_execute_option(str)
+        Boson.main_object.instance_eval str
+      end
+
+      # Returns true if an option does something and exits early
+      def early_option?(args)
+        if @options[:version]
+          puts("boson #{Boson::VERSION}")
+          true
+        elsif args.empty? || (@command.nil? && !@options[:execute])
+          print_usage
+          true
+        else
+          false
+        end
+      end
+
+      # Determines verbosity of this class
+      def verbose
+        false
+      end
+
+      # Handles no method errors
+      def no_method_error_message(err)
+        @command = @command.to_s
+        if err.backtrace.grep(/`(invoke|full_invoke)'$/).empty? ||
+          !err.message[/undefined method `(\w+\.)?#{command_name(@command)}'/]
+            default_error_message($!)
+        else
+          command_not_found?(@command) ?
+            "Error: Command '#{@command}' not found" : default_error_message(err)
+        end
+      end
+
+      # Determine command name given full command name. Overridden by namespaces
+      def command_name(cmd)
+        cmd
+      end
+
+      # Determines if a NoMethodError is a command not found error
+      def command_not_found?(cmd)
+        cmd[/\w+/]
+      end
+
+      # Constructs error message
+      def default_error_message(err)
+        "Error: #{err.message}"
+      end
+
+      def print_usage_header
+        puts "boson [GLOBAL OPTIONS] [COMMAND] [ARGS] [COMMAND OPTIONS]\n\n"
+      end
+
+      # prints full usage
+      def print_usage
+        print_usage_header
+        @option_parser.print_usage_table
+      end
+    end
+    extend API
+
+    # Starts, processes and ends a commandline request.
+    def self.start(args=ARGV)
+      super
+      @command, @options, @args = parse_args(args)
+
+      $:.unshift(*options[:load_path].split(":")) if options[:load_path]
+      Boson.debug = true if options[:debug]
+      $DEBUG = true if options[:ruby_debug]
+      return if early_option?(args)
+      Boson.in_shell = true
+
+      init
+      execute_option_or_command(@options, @command, @args)
+    rescue NoMethodError
+      abort_with no_method_error_message($!)
+    rescue
+      abort_with default_error_message($!)
+    end
+
+    # Hash of global options passed in from commandline
+    def self.options
+      @options ||= {}
+    end
+  end
+end

data/lib/boson/command.rb

@@ -1,74 +1,78 @@
 module Boson
-  # A command starts with the functionality of a ruby method and adds benefits with options, render_options, etc.
+  # A command starts with the functionality of a ruby method and adds benefits
+  # with options, etc.
   class Command
-    class <<self; attr_accessor :all_option_commands ; end
+    module APIClassMethods
+      # Creates a command given its name and a library.
+      def create(name, library)
+        new(new_attributes(name, library))
+      end
 
-    # Creates a command given its name and a library.
-    def self.create(name, library)
-      obj = new(new_attributes(name, library))
-      if @all_option_commands && !%w{get method_missing}.include?(name)
-        obj.make_option_command(library)
+      # Attributes passed to commands from its library
+      def library_attributes(library)
+        {lib: library.name}
       end
-      obj
-    end
 
-    # Used to generate a command's initial attributes when creating a command object
-    def self.new_attributes(name, library)
-      (library.commands_hash[name] || {}).merge({:name=>name, :lib=>library.name, :namespace=>library.namespace})
-    end
+      # Finds a command, aliased or not. If found returns the command object,
+      # otherwise returns nil.
+      def find(command, commands=Boson.commands)
+        command && commands.find {|e| [e.name, e.alias].include?(command) }
+      end
 
-    # Finds a command, namespaced or not and aliased or not. If found returns the
-    # command object, otherwise returns nil.
-    def self.find(command, commands=Boson.commands)
-      if command.to_s.include?(NAMESPACE)
-        command, subcommand = command.to_s.split(NAMESPACE, 2)
-        commands.find {|current_command|
-          [current_command.name, current_command.alias].include?(subcommand) &&
-          current_command.library && (current_command.library.namespace == command)
-        }
-      else
-        commands.find {|e| [e.name, e.alias].include?(command) && !e.namespace}
+      # Generates a command's initial attributes when creating a command object
+      def new_attributes(name, library)
+        (library.commands_hash[name] || {}).merge(name: name).
+          update(library_attributes(library))
       end
     end
+    extend APIClassMethods
 
     # One line usage for a command if it exists
     def self.usage(command)
-      (cmd = find(command)) ? "#{command} #{cmd.usage}" : "Command '#{command}' not found"
+      (cmd = find(command)) ? "#{command} #{cmd.usage}" : ''
     end
 
+    # Attributes that are defined as accessors
     ATTRIBUTES = [:name, :lib, :alias, :desc, :options, :args, :config]
-    attr_accessor *(ATTRIBUTES + [:render_options, :namespace, :default_option])
-    # A hash of attributes which map to instance variables and values. :name
-    # and :lib are required keys.
+    attr_accessor *(ATTRIBUTES + [:default_option])
+    # Attributes that can be passed in at initialization
+    INIT_ATTRIBUTES = [:alias, :desc, :options, :default_option, :option_command]
+    attr_reader :file_parsed_args
+
+    # Takes a hash of attributes which map to instance variables and values.
+    # :name and :lib are required keys.
     #
-    # Attributes that can be configured:
-    # [*:desc*] Description that shows up in command listings
-    # [*:alias*] Alternative name for command
-    # [*:options*] Hash of options passed to OptionParser
-    # [*:render_options*] Hash of rendering options to pass to OptionParser. If the key :output_class is passed,
-    #                     that class's Hirb config will serve as defaults for this rendering hash.
-    # [*:option_command*] Boolean to wrap a command with an OptionCommand object i.e. allow commands to have options.
-    # [*:args*] Should only be set if not automatically set. This attribute is only
-    #           important for commands that have options/render_options. Its value can be an array
-    #           (as ArgumentInspector.scrape_with_eval produces), a number representing
-    #           the number of arguments or '*' if the command has a variable number of arguments.
-    # [*:default_option*] Only for an option command that has one or zero arguments. This treats the given
-    #                     option as an optional first argument. Example:
-    #                       # For a command with default option 'query' and options --query and -v
-    #                       'some -v'   -> '--query=some -v'
-    #                       '-v'        -> '-v'
-    # [*:config*] A hash for third party libraries to get and set custom command attributes.
+    # @param [Hash] attributes
+    # @option attributes [String] :desc Description that shows up once in
+    #   command listings
+    # @option attributes [String] :alias Alternative name for command
+    # @option attributes [Hash] :options Options passed to OptionParser
+    # @option attributes [Array,Integer,String] :args Should only be set if
+    #   not automatically set. This attribute is only important for commands
+    #   that have options. Its value can be an array, a number representing
+    #   the number of arguments or '*' if the command has a variable number of
+    #   arguments.
+    # @option attributes [String] :default_option Only for an option command
+    #   that has one or zero arguments. This treats the given option as an optional
+    #   first argument. Example:
+    #     # For a command with default option 'query' and options --query and -v
+    #     'some -v'   -> '--query=some -v'
+    #     '-v'        -> '-v'
+    # @option attributes [Hash] :config used by third party libraries to get and
+    #   set custom command attributes.
+    # @option attributes [Boolean] :option_command Wraps a command with an
+    #   OptionCommand object i.e. allow commands to have options.
     def initialize(attributes)
       hash = attributes.dup
       @name = hash.delete(:name) or raise ArgumentError
       @lib = hash.delete(:lib) or raise ArgumentError
-      [:alias, :desc, :options, :namespace, :default_option, :option_command].each do |e|
-          instance_variable_set("@#{e}", hash.delete(e)) if hash.key?(e)
+      # since MethodInspector scrapes arguments from file by default
+      @file_parsed_args = true
+      INIT_ATTRIBUTES.each do |e|
+        instance_variable_set("@#{e}", hash.delete(e)) if hash.key?(e)
       end
 
-      if hash[:render_options] && (@render_options = hash.delete(:render_options))[:output_class]
-        @render_options = Util.recursive_hash_merge View.class_config(@render_options[:output_class]), @render_options
-      end
+      after_initialize(hash)
 
       if (args = hash.delete(:args))
         if args.is_a?(Array)
@@ -82,20 +86,34 @@ module Boson
       @config = Util.recursive_hash_merge hash, hash.delete(:config) || {}
     end
 
+    module API
+      # Called after initialize
+      def after_initialize(hash)
+      end
+
+      # Alias for a name but plugins may use it to give a more descriptive name
+      def full_name
+        name
+      end
+
+      # One-line usage of args
+      def basic_usage
+        return '' if args.nil?
+        usage_args.map {|e|
+          (e.size < 2) ? e[0].upcase : "[#{e[0].upcase}]"
+        }.join(' ')
+      end
+      alias_method :usage, :basic_usage
+    end
+    include API
+
     # Library object a command belongs to.
     def library
       @library ||= Boson.library(@lib)
     end
 
-    # Array of array args with optional defaults. Scraped with ArgumentInspector.
     def args(lib=library)
-      @args = !@args.nil? ? @args : begin
-        if lib
-          file_string, meth = file_string_and_method_for_args(lib)
-          (file_string && meth && (@file_parsed_args = true) &&
-            ArgumentInspector.scrape_with_text(file_string, meth))
-        end || false
-      end
+      @args
     end
 
     # Option parser for command as defined by @options.
@@ -103,94 +121,36 @@ module Boson
       @option_parser ||= OptionParser.new(@options || {})
     end
 
-    # Option parser for command as defined by @render_options.
-    def render_option_parser
-      option_command? ? Boson::Scientist.option_command(self).option_parser : nil
-    end
-
-    # Help string for options if a command has it.
-    def option_help
-      @options ? option_parser.to_s : ''
-    end
-
-    # Usage string for command, created from options and args.
-    def usage
-      return '' if options.nil? && args.nil?
-      usage_args = args && @options && !has_splat_args? ?
-        (@default_option ? [[@default_option.to_s, @file_parsed_args ? ''.inspect : '']] + args[0..-2] :
-        args[0..-2]) : args
-      str = args ? usage_args.map {|e|
-        (e.size < 2) ? "[#{e[0]}]" : "[#{e[0]}=#{@file_parsed_args ? e[1] : e[1].inspect}]"
-      }.join(' ') : '[*unknown]'
-      str + option_help
-    end
-
-    # Full name is only different than name if a command has a namespace.
-    # The full name should be what you would type to execute the command.
-    def full_name
-      @namespace ? "#{@namespace}.#{@name}" : @name
+    # Indicates if an OptionCommand
+    def option_command?
+      options || @option_command
     end
 
-    #:stopdoc:
     # until @config is consistent in index + actual loading
     def config
       @config ||= {}
     end
 
-    def file_string_and_method_for_args(lib)
-      if !lib.is_a?(ModuleLibrary) && (klass_method = (lib.class_commands || {})[@name])
-        if RUBY_VERSION >= '1.9'
-          klass, meth = klass_method.split(NAMESPACE, 2)
-          if (meth_locations = MethodInspector.find_method_locations_for_19(klass, meth))
-            file_string = File.read meth_locations[0]
-          end
-        end
-      elsif File.exists?(lib.library_file || '')
-        file_string, meth = FileLibrary.read_library_file(lib.library_file), @name
-      end
-      [file_string, meth]
-    end
-
+    # Indicates if any arg has a splat
     def has_splat_args?
       !!(args && @args[-1] && @args[-1][0][/^\*/])
     end
 
-    def make_option_command(lib=library)
-      @option_command = true
-      @args = [['*args']] unless args(lib) || arg_size
-    end
-
-    def option_command?
-      options || render_options || @option_command
-    end
-
+    # Number of arguments
     def arg_size
-      @arg_size = args ? args.size : nil unless instance_variable_defined?("@arg_size")
-      @arg_size
-    end
-
-    def file_parsed_args?
-      @file_parsed_args
-    end
-
-    # Deprecated method
-    def description
-      puts "@command.description has been changed to @command.desc. Delete your old " +
-        "Boson index at ~/.boson/command/index.marshal for Boson to work from the commandline."
-      Kernel.exit
-    end
-
-    def marshal_dump
-      if @args && @args.any? {|e| e[1].is_a?(Module) }
-        @args.map! {|e| e.size == 2 ? [e[0], e[1].inspect] : e }
-        @file_parsed_args = true
+      unless instance_variable_defined?("@arg_size")
+        @arg_size = args ? args.size : nil
       end
-      [@name, @alias, @lib, @desc, @options, @render_options, @args, @default_option]
+      @arg_size
     end
 
-    def marshal_load(ary)
-      @name, @alias, @lib, @desc, @options, @render_options, @args, @default_option = ary
+    private
+    def usage_args
+      args && @options && !has_splat_args? ?
+        (@default_option ?
+         [[@default_option.to_s, @file_parsed_args ? ''.inspect : '']] +
+         args[0..-2] : args[0..-2])
+        : args
     end
-    #:startdoc:
   end
-end
+end

data/lib/boson/inspector.rb

@@ -1,13 +1,11 @@
 module Boson
-  # Scrapes and processes method attributes with the inspectors (MethodInspector, CommentInspector
-  # and ArgumentInspector) and hands off the data to FileLibrary objects.
+  # Uses method decorators to scrape, process and hand off method attributes as
+  # data to Library objects.
   #
-  # === Method Attributes
-  # Method attributes refer to (commented) Module methods placed before a command's method
-  # in a FileLibrary module:
-  #   module SomeMod
-  #      # @render_options :fields=>%w{one two}
-  #      # @config :alias=>'so'
+  # === Method Decorators
+  # Method decorators refer to methods placed before a command's method in a
+  # library:
+  #   class SomeRunner < Boson::Runner
   #      options :verbose=>:boolean
   #      option :count, :numeric
   #      # Something descriptive perhaps
@@ -16,24 +14,26 @@ module Boson
   #      end
   #   end
   #
-  # Method attributes serve as configuration for a method's command. All attributes should only be called once per
-  #   method except for option. Available method attributes:
+  # Method decorators serve as configuration for a method's command. All
+  # decorators should only be called once per method except for option.
+  # Available method decorators:
   # * config: Hash to define any command attributes (see Command.new).
-  # * desc: String to define a command's description for a command. Defaults to first commented line above a method.
+  # * desc: String to define a command's description for a command. Defaults to
+  #   first commented line above a method.
   # * options: Hash to define an OptionParser object for a command's options.
-  # * option: Option name and value to be merged in with options. See OptionParser for what an option value can be.
-  # * render_options: Hash to define an OptionParser object for a command's local/global render options (see View).
-  #
-  # When deciding whether to use commented or normal Module methods, remember that commented Module methods allow
-  # independence from Boson (useful for testing). See CommentInspector for more about commented method attributes.
-  module Inspector
-    extend self
-    attr_reader :enabled
+  # * option: Option name and value to be merged in with options. See
+  #   OptionParser for what an option value can be.
+  class Inspector
+    class << self; attr_reader :enabled; end
+
+    # Enable scraping by overridding method_added to snoop on a library while
+    # it's loading its methods.
+    def self.enable(options = {})
+      method_inspector_meth = options[:all_classes] ?
+        :new_method_added : :safe_new_method_added
+      klass = options[:module] || ::Module
+      @enabled = true unless options[:module]
 
-    # Enable scraping by overridding method_added to snoop on a library while it's
-    # loading its methods.
-    def enable
-      @enabled = true
       body = MethodInspector::ALL_METHODS.map {|e|
         %[def #{e}(*args)
             Boson::MethodInspector.#{e}(self, *args)
@@ -41,17 +41,17 @@ module Boson
       }.join("\n") +
       %[
         def new_method_added(method)
-          Boson::MethodInspector.new_method_added(self, method)
+          Boson::MethodInspector.#{method_inspector_meth}(self, method)
         end
 
         alias_method :_old_method_added, :method_added
         alias_method :method_added, :new_method_added
       ]
-    ::Module.module_eval body
+      klass.module_eval body
     end
 
     # Disable scraping method data.
-    def disable
+    def self.disable
       ::Module.module_eval %[
         Boson::MethodInspector::ALL_METHODS.each {|e| remove_method e }
         alias_method :method_added, :_old_method_added
@@ -59,17 +59,27 @@ module Boson
       @enabled = false
     end
 
-    # Adds method attributes scraped for the library's module to the library's commands.
-    def add_method_data_to_library(library)
+    # Adds method attributes to the library's commands
+    def self.add_method_data_to_library(library)
+      new(library).add_data
+    end
+
+    def initialize(library)
       @commands_hash = library.commands_hash
       @library_file = library.library_file
-      MethodInspector.current_module = library.module
-      @store = MethodInspector.store
-      add_method_scraped_data
-      add_comment_scraped_data
+      MethodInspector.instance.current_module = library.module
+      @store = MethodInspector.instance.store
     end
 
-    #:stopdoc:
+    module API
+      # Adds scraped data from all inspectors
+      def add_data
+        add_method_scraped_data
+      end
+    end
+    include API
+
+    private
     def add_method_scraped_data
       (MethodInspector::METHODS + [:args]).each do |key|
         (@store[key] || []).each do |cmd, val|
@@ -83,8 +93,9 @@ module Boson
       if valid_attr_value?(key, value)
         add_scraped_data_to_config(key, value, cmd)
       else
-        if Runner.debug
-          warn "DEBUG: Command '#{cmd}' has #{key.inspect} attribute with invalid value '#{value.inspect}'"
+        if Boson.debug
+          warn "DEBUG: Command '#{cmd}' has #{key.inspect} attribute with " +
+            "invalid value '#{value.inspect}'"
         end
       end
     end
@@ -94,7 +105,8 @@ module Boson
         if key == :config
           @commands_hash[cmd] = Util.recursive_hash_merge value, @commands_hash[cmd]
         else
-          @commands_hash[cmd][key] = Util.recursive_hash_merge value, @commands_hash[cmd][key] || {}
+          @commands_hash[cmd][key] = Util.recursive_hash_merge value,
+            @commands_hash[cmd][key] || {}
         end
       else
         @commands_hash[cmd][key] ||= value
@@ -105,16 +117,5 @@ module Boson
       return true if (klass = MethodInspector::METHOD_CLASSES[key]).nil?
       value.is_a?(klass) || value.nil?
     end
-
-    def add_comment_scraped_data
-      (@store[:method_locations] || []).select {|k,(f,l)| f == @library_file }.each do |cmd, (file, lineno)|
-        scraped = CommentInspector.scrape(FileLibrary.read_library_file(file), lineno, MethodInspector.current_module)
-        @commands_hash[cmd] ||= {}
-        MethodInspector::METHODS.each do |e|
-          add_valid_data_to_config(e, scraped[e], cmd)
-        end
-      end
-    end
-    #:startdoc:
   end
-end
+end