boson-more 0.1.0

data/lib/boson/libraries.rb

@@ -0,0 +1,183 @@
+require 'boson/save'
+require 'boson/namespace'
+require 'boson/more_util'
+# order of library subclasses matters
+%w{module file gem require local_file}.each {|e| require "boson/libraries/#{e}_library" }
+
+module Boson
+  # == Naming a Library Module
+  # Although you can name a library module almost anything, here's the fine print:
+  # * A module can have any name if it's the only module in a library.
+  # * If there are multiple modules in a file library, the module's name must
+  #   be a camelized version of the file's basename
+  #   i.e. ~/.boson/commands/ruby_core.rb -> RubyCore.
+  # * Although modules are evaluated under the Boson::Commands namespace, Boson
+  #   will warn you about creating modules whose name is the same as a top level
+  #   class/module. The warning is to encourage users to stay away from
+  #   error-prone libraries. Once you introduce such a module, _all_ libraries
+  #   assume the nested module over the top level module and the top level
+  #   module has to be prefixed with '::' _everywhere_.
+  #
+  # == Configuration
+  # Libraries and their commands can be configured in different ways in this order:
+  # * If library is a FileLibrary, commands be configured with a config method
+  #   attribute (see Inspector).
+  # * If a library has a module, you can set library + command attributes via
+  #   the config() callback (see Loader).
+  # === Module Callbacks
+  # For libraries that have a module i.e. RunnerLibrary, the following class methods
+  # are invoked in the order below when loading a library:
+  #
+  # [*:config*] This method returns a library's hash of attributes as explained by Library.new. This is useful
+  #             for distributing libraries with a default configuration. The library attributes specified here
+  #             are overridden by ones a user has in their config file except for the :commands attribute, which
+  #             is recursively merged together.
+  # [*:append_features*] In addition to its normal behavior, this method's return value determines if a
+  #                      library is loaded in the current environment. This is useful for libraries that you
+  #                      want loaded by default but not in some environments i.e. different ruby versions or
+  #                      in irb but not in script/console. Remember to use super when returning true.
+  # [*:included*] In addition to its normal behavior, this method should be used to require external libraries.
+  #               Although requiring dependencies could be done anywhere in a module, putting dependencies here
+  #               are encouraged. By not having dependencies hardcoded in a module, it's possible to analyze
+  #               and view a library's commands without having to install and load its dependencies.
+  #               If creating commands here, note that conflicts with existing commands won't be detected.
+  # [*:after_included*] This method is called after included() to initialize functionality. This is useful for
+  #                     libraries that are primarily executing ruby code i.e. defining ruby extensions or
+  #                     setting irb features. This method isn't called when indexing a library.
+  class Library
+    ATTRIBUTES << :gems
+
+    module Libraries
+      attr_reader :gems
+      def local?
+        is_a?(LocalFileLibrary) ||
+          (Boson.local_repo && Boson.local_repo.dir == repo_dir)
+      end
+    end
+    include Libraries
+
+    # [*:object_methods*] Boolean which detects any Object/Kernel methods created when loading a library and automatically
+    #                     adds them to a library's commands. Default is true.
+    module LibrariesLoader
+      def detect_additions(options={}, &block)
+        options[:object_methods] = @object_methods if !@object_methods.nil?
+        super(options, &block).tap do |detected|
+          if detected[:gems]
+            @gems ||= []
+            @gems.concat detected[:gems]
+          end
+        end
+      end
+
+      def module_callbacks
+        set_config(@module.config) if @module.respond_to?(:config)
+        if @module.respond_to?(:append_features)
+          raise AppendFeaturesFalseError unless @module.append_features(Module.new)
+        end
+        super
+      end
+
+      def before_load_commands
+        raise(LoaderError, "No module for library #{@name}") unless @module
+        if (conflict = Util.top_level_class_conflict(Boson::Commands, @module.to_s))
+          warn "Library module '#{@module}' may conflict with top level class/module '#{conflict}' references in"+
+            " your libraries. Rename your module to avoid this warning."
+        end
+        super
+      end
+
+      def after_include
+        @module.after_included if @module.respond_to?(:after_included) && !@index
+        super
+      end
+    end
+    include LibrariesLoader
+  end
+
+  # Raised when a library's append_features returns false.
+  class AppendFeaturesFalseError < StandardError; end
+
+  class Manager
+    module Libraries
+      def handle_load_action_error(library, load_method, err)
+        if err.is_a? Boson::AppendFeaturesFalseError
+          warn "DEBUG: Library #{library} didn't load due to append_features" if Boson.debug
+        else
+          super
+        end
+      end
+
+      def before_create_commands(lib)
+        super
+        if lib.is_a?(FileLibrary) && lib.module
+          Inspector.add_method_data_to_library(lib)
+        end
+      end
+
+      def add_failed_library(library)
+        FileLibrary.reset_file_cache(library.to_s)
+        super
+      end
+
+      def check_for_uncreated_aliases(lib, commands)
+        return if lib.is_a?(GemLibrary)
+        super
+      end
+    end
+    include Libraries
+  end
+
+  class Command
+    # hack: have to override
+    # Array of array args with optional defaults. Scraped with MethodInspector
+    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) &&
+            MethodInspector.scrape_arguments(file_string, meth))
+        end || false
+      end
+    end
+
+    module Libraries
+      def file_string_and_method_for_args(lib)
+        if !lib.is_a?(ModuleLibrary) && (klass_method = (lib.class_commands || {})[@name])
+          klass, meth = klass_method.split(NAMESPACE, 2)
+          if (meth_locations = MethodInspector.find_class_method_locations(klass, meth))
+            file_string = File.read meth_locations[0]
+          end
+        elsif File.exists?(lib.library_file || '')
+          file_string, meth = FileLibrary.read_library_file(lib.library_file), @name
+        end
+        [file_string, meth]
+      end
+    end
+    include Libraries
+  end
+
+  class MethodInspector
+    module Libraries
+      def find_class_method_locations(klass, meth)
+        if (klass = Util.any_const_get(klass)) && (meth_location = klass.method(meth).source_location) &&
+          meth_location[0]
+          meth_location
+        end
+      end
+    end
+    extend Libraries
+  end
+
+  module Scientist
+    module Libraries
+      def help_options
+        @global_options[:verbose] ? ['--verbose'] : []
+      end
+
+      def run_help_option(cmd)
+        Boson.invoke :usage, cmd.full_name + " " + help_options.join(' ')
+      end
+    end
+    extend Libraries
+  end
+end

data/lib/boson/more/version.rb

@@ -0,0 +1,5 @@
+module Boson
+  module More
+    VERSION = '0.1.0'
+  end
+end

data/lib/boson/more.rb

@@ -0,0 +1,18 @@
+require 'boson/alias'
+require 'boson/namespacer'
+require 'boson/more_util'
+require 'boson/more_manager'
+require 'boson/save'
+require 'boson/libraries'
+require 'boson/more_commands'
+require 'boson/pipe_runner'
+require 'boson/more_inspector'
+require 'boson/more_method_inspector'
+require 'boson/more_scientist'
+require 'boson/science'
+require 'boson/runner_options'
+require 'boson/console'
+require 'boson/viewable'
+
+module Boson::More
+end

data/lib/boson/more_commands.rb

@@ -0,0 +1,14 @@
+require 'boson/commands/core'
+require 'boson/commands/web_core'
+require 'boson/commands/view_core'
+require 'boson/bare_runner'
+require 'fileutils'
+
+Boson::BareRunner::DEFAULT_LIBRARIES << Boson::Commands::Core
+Boson::BareRunner::DEFAULT_LIBRARIES << Boson::Commands::WebCore
+Boson::BareRunner::DEFAULT_LIBRARIES << Boson::Commands::ViewCore
+
+# TODO: Use Boson.home when it exists
+dir = Dir.home + '/.boson/.more_commands'
+FileUtils.mkdir_p dir
+Boson.repos << Boson::Repo.new(dir)

data/lib/boson/more_inspector.rb

@@ -0,0 +1,42 @@
+require 'boson/comment_inspector'
+require 'boson/more_method_inspector'
+
+module Boson
+  # 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.
+  class Inspector
+    module MoreInspector
+      def add_data
+        super
+        add_comment_scraped_data
+      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.instance.current_module)
+          @commands_hash[cmd] ||= {}
+          MethodInspector::METHODS.each do |e|
+            add_valid_data_to_config(e, scraped[e], cmd)
+          end
+        end
+      end
+    end
+    include MoreInspector
+  end
+
+  # This module also saves method locations so CommentInspector
+  # can scrape their commented method attributes.
+  class MethodInspector
+    module MoreInspector
+      def inspector_in_file?(meth, inspector_method)
+        return false if !super
+        if File.exists?(file_line[0]) && (options = CommentInspector.scrape(
+          FileLibrary.read_library_file(file_line[0]), file_line[1], @current_module, inspector_method) )
+          (store[inspector_method] ||= {})[meth] = options
+        end
+      end
+    end
+    include MoreInspector
+  end
+end

data/lib/boson/more_manager.rb

@@ -0,0 +1,34 @@
+# Adds dependencies to manager
+module Boson
+  class Manager
+    module MoreManager
+      def load_dependencies(lib, options={})
+        lib_dependencies[lib] = Array(lib.dependencies).map do |e|
+          next if self.class.loaded?(e)
+          load_once(e, options.merge(:dependency=>true)) ||
+            raise(LoaderError, "Can't load dependency #{e}")
+        end.compact
+      end
+
+      def lib_dependencies
+        @lib_dependencies ||= {}
+      end
+
+      def during_after_load
+        (lib_dependencies[@library] || []).each do |e|
+          create_commands(e)
+          self.class.add_library(e)
+          puts "Loaded library dependency #{e.name}" if verbose
+        end
+      end
+    end
+    include MoreManager
+  end
+
+  # [*:dependencies*] An array of libraries that this library depends on. A library won't load
+  #                   unless its dependencies are loaded first.
+  class Library
+    ATTRIBUTES << :dependencies
+    attr_reader :dependencies
+  end
+end

data/lib/boson/more_method_inspector.rb

@@ -0,0 +1,74 @@
+module Boson
+  class MethodInspector
+    # Returns argument arrays
+    def self.scrape_arguments(file_string, meth)
+      tabspace = "[ \t]"
+      if match = /^#{tabspace}*def#{tabspace}+(?:\w+\.)?#{Regexp.quote(meth)}#{tabspace}*($|(?:\(|\s+)([^\n\)]+)\s*\)?\s*$)/.match(file_string)
+        (match.to_a[2] || '').strip.split(/\s*,\s*/).map {|e| e.split(/\s*=\s*/)}
+      end
+    end
+
+    # investigate why this can't be included
+    def inspector_in_file?(meth, inspector_method)
+      !(file_line = store[:method_locations] && store[:method_locations][meth]) ?
+        false : true
+    end
+
+    module MoreMethodInspector
+      def during_new_method_added(mod, meth)
+        if store[:temp].size < ALL_METHODS.size
+          store[:method_locations] ||= {}
+          if (result = find_method_locations(mod, meth))
+            store[:method_locations][meth.to_s] = result
+          end
+        end
+      end
+
+      def set_arguments(mod, meth)
+        store[:args] ||= {}
+        file = find_method_locations(mod, meth)[0]
+
+        if File.exists?(file)
+          body = File.read(file)
+          store[:args][meth.to_s] = self.class.scrape_arguments body, meth
+        end
+      end
+
+      def has_inspector_method?(meth, inspector)
+        (store[inspector] && store[inspector].key?(meth.to_s)) ||
+          inspector_in_file?(meth.to_s, inspector)
+      end
+
+      # Returns an array of the file and line number at which a method starts
+      # using a method
+      def find_method_locations(mod, meth)
+        mod.instance_method(meth).source_location
+      end
+    end
+    include MoreMethodInspector
+  end
+
+  class Command
+    module MoreMethodInspector
+      # One-line usage of args with default values
+      def basic_usage
+        return '' if options.nil? && args.nil?
+        args ? usage_args.map {|e|
+          (e.size < 2) ? "[#{e[0]}]" :
+            "[#{e[0]}=#{@file_parsed_args ? e[1] : e[1].inspect}]"
+        }.join(' ') : '[*unknown]'
+      end
+
+      # Help string for options if a command has it.
+      def option_help
+        @options ? option_parser.to_s : ''
+      end
+
+      # keep?
+      def usage
+        basic_usage + option_help
+      end
+    end
+    include MoreMethodInspector
+  end
+end

data/lib/boson/more_option_parser.rb

@@ -0,0 +1,28 @@
+module Boson
+  class OptionParser
+    module MoreOptionParser
+      # Given options to pass to OptionParser.new, this method parses ARGV and
+      # returns the remaining arguments and a hash of parsed options. This is
+      # useful for scripts outside of Boson.
+      def parse(options, args=ARGV)
+        @opt_parser ||= new(options)
+        parsed_options = @opt_parser.parse(args)
+        [@opt_parser.non_opts, parsed_options]
+      end
+
+      # Usage string summarizing options defined in parse
+      def usage
+        @opt_parser.to_s
+      end
+
+      def make_mergeable!(opts)
+        opts.each {|k,v|
+          if !v.is_a?(Hash) && !v.is_a?(Symbol)
+            opts[k] = {:default=>v}
+          end
+        }
+      end
+    end
+    extend MoreOptionParser
+  end
+end

data/lib/boson/more_scientist.rb

@@ -0,0 +1,68 @@
+module Boson
+  # Any command with options comes with basic global options. For example '-hv'
+  # on an option command prints a help summarizing global and local options.
+  # Another basic global option is --pretend. This option displays what global
+  # options have been parsed and the actual arguments to be passed to a
+  # command if executed. For example:
+  #
+  #   # Define this command in a library
+  #   options :level=>:numeric, :verbose=>:boolean
+  #   def foo(*args)
+  #     args
+  #   end
+  #
+  #   irb>> foo 'testin -p -l=1'
+  #   Arguments: ["testin", {:level=>1}]
+  #   Global options: {:pretend=>true}
+  #
+  # If a global option conflicts with a local option, the local option takes
+  # precedence. You can get around this by passing global options after a '-'.
+  # For example, if the global option -h (--help) conflicts with a local -h
+  # (--force):
+  #   foo 'arg1 -v -f - -f=f1,f2'
+  #   # is the same as
+  #   foo 'arg1 -v --fields=f1,f2 -f'
+  class OptionCommand
+    BASIC_OPTIONS.update(
+      :verbose=>{:type=>:boolean, :desc=>"Increase verbosity for help, errors, etc."},
+      :pretend=>{:type=>:boolean,
+        :desc=>"Display what a command would execute without executing it"}
+    )
+  end
+  module Scientist
+    module MoreScientist
+      def during_analyze(&block)
+        run_pretend_option(@args)
+        super unless @global_options[:pretend]
+      end
+
+      def analyze(*)
+        super
+      rescue OptionCommand::CommandArgumentError
+        run_pretend_option(@args ||= [])
+        return if !@global_options[:pretend] &&
+          run_verbose_help(option_command, @original_args)
+        raise unless @global_options[:pretend]
+      end
+
+      private
+      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 @command
+          return true
+        end
+        false
+      end
+
+      def run_pretend_option(args)
+        if @global_options[:verbose] || @global_options[:pretend]
+          puts "Arguments: #{args.inspect}",
+            "Global options: #{@global_options.inspect}"
+        end
+      end
+    end
+    extend MoreScientist
+  end
+end

data/lib/boson/more_util.rb

@@ -0,0 +1,30 @@
+module Boson
+  module MoreUtil
+    # 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
+
+    # Safely calls require, returning false if LoadError occurs.
+    def safe_require(lib)
+      begin
+        require lib
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    # Returns name of top level class that conflicts if it exists. For example, for base module Boson::Commands,
+    # Boson::Commands::Hirb conflicts with Hirb if Hirb exists.
+    def top_level_class_conflict(base_module, conflicting_module)
+      (conflicting_module =~ /^#{base_module}.*::([^:]+)/) && Object.const_defined?($1) && $1
+    end
+  end
+  Util.extend MoreUtil
+end

data/lib/boson/namespace.rb

@@ -0,0 +1,31 @@
+module Boson
+  # Used in all things namespace.
+  class Namespace
+    # Hash of created namespace names to namespace objects
+    def self.namespaces
+      @namespaces ||= {}
+    end
+
+    # Creates a namespace given its name and the library it belongs to.
+    def self.create(name, library)
+      namespaces[name.to_s] = new(name, library)
+      Commands::Namespace.send(:define_method, name) { Boson::Namespace.namespaces[name.to_s] }
+    end
+
+    def initialize(name, library)
+      raise ArgumentError unless library.module
+      @name, @library = name.to_s, library
+      class <<self; self end.send :include, @library.module
+    end
+
+    def method_missing(method, *args, &block)
+      Boson.can_invoke?(method) ? Boson.invoke(method, *args, &block) : super
+    end
+
+    #:startdoc:
+    # List of subcommands for the namespace.
+    def boson_commands
+      @library.module.instance_methods.map {|e| e.to_s }
+    end
+  end
+end

data/lib/boson/namespacer.rb

@@ -0,0 +1,117 @@
+require 'boson/namespace'
+
+module Boson
+  NAMESPACE = '.' # Delimits namespace from command
+  module Commands
+    # Used for defining namespaces.
+    module Namespace; end
+  end
+  Universe.send :include, Commands::Namespace
+
+  module Namespacer
+    # Invoke command string even with namespaces
+    def full_invoke(cmd, args) #:nodoc:
+      command, subcommand = cmd.include?(NAMESPACE) ? cmd.split(NAMESPACE, 2) : [cmd, nil]
+      dispatcher = subcommand ? Boson.invoke(command) : Boson.main_object
+      dispatcher.send(subcommand || command, *args)
+    end
+  end
+  extend Namespacer
+
+  class Command
+    INIT_ATTRIBUTES << :namespace
+    module NamespacerClass
+      def library_attributes(library)
+        super.update(namespace: library.namespace)
+      end
+
+      def 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}
+        end
+      end
+    end
+    extend NamespacerClass
+
+    module Namespacer
+      attr_accessor :namespace
+
+      # 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
+      end
+    end
+    include Namespacer
+  end
+
+  class Library
+    # [*:namespace*] Boolean or string which namespaces a library. When true, the library is automatically namespaced
+    #                to the library's name. When a string, the library is namespaced to the string. Default is nil.
+    module Namespacer
+      # Optional namespace name for a library. When enabled defaults to a library's name.
+      attr_writer :namespace
+
+      # The object a library uses for executing its commands.
+      def namespace_object
+        @namespace_object ||= namespace ? Boson.invoke(namespace) : Boson.main_object
+      end
+
+      def namespace(orig=@namespace)
+        @namespace = [String,FalseClass].include?(orig.class) ? orig : begin
+          if (@namespace == true || (Boson.config[:auto_namespace] && !@index))
+            @namespace = clean_name
+          else
+            @namespace = false
+          end
+        end
+      end
+    end
+    include Namespacer
+
+    module NamespaceLoader
+      attr_reader :indexed_namespace, :object_namespace
+
+      def handle_method_conflict_error(err)
+        if Boson.config[:error_method_conflicts] || namespace
+          raise err
+        else
+          @namespace = clean_name
+          @method_conflict = true
+          $stderr.puts "#{err.message}. Attempting load into the namespace #{@namespace}..."
+          load_commands
+        end
+      end
+
+      def actual_load_commands
+        @namespace = clean_name if @object_namespace
+        namespace ? Namespace.create(namespace, self) : include_in_universe
+      end
+
+      def method_conflicts
+        namespace ?
+          (Boson.can_invoke?(namespace) ?  [namespace] : []) :
+          super
+      end
+
+      def clean_library_commands
+        @commands.delete(namespace) if namespace
+        @commands += Boson.invoke(namespace).boson_commands if namespace && !@pre_defined_commands
+        super
+      end
+
+      def set_library_commands
+        @namespace = false if !(@module || @class_commands)
+        super
+        @indexed_namespace = (@namespace == false) ? nil : @namespace if @index
+      end
+    end
+    include NamespaceLoader
+  end
+end