boson-more 0.1.0

data/lib/boson/comment_inspector.rb

@@ -0,0 +1,100 @@
+module Boson
+  # Scrapes comments right before a method for its attributes. Method attributes must begin with '@' i.e.:
+  #    # @desc Does foo
+  #    # @options :verbose=>true
+  #    def foo(options={})
+  #
+  # Some rules about these attributes:
+  # * Attribute definitions can span multiple lines. When a new attribute starts a line or the comments end,
+  #   then a definition ends.
+  # * If no @desc is found in the comment block, then the first comment line directly above the method
+  #   is assumed to be the value for @desc. This means that no multi-line attribute definitions can occur
+  #   without a description since the last line is assumed to be a description.
+  # * options, option and config attributes can take any valid ruby since they're evaled in
+  #   their module's context.
+  # * desc attribute is not evaled and is simply text to be set as a string.
+  #
+  # This module was inspired by
+  # {pragdave}[http://github.com/pragdavespc/rake/commit/45231ac094854da9f4f2ac93465ed9b9ca67b2da].
+  module CommentInspector
+    extend self
+    EVAL_ATTRIBUTES = [:options, :config]
+
+    # Given a method's file string, line number and defining module, returns a hash
+    # of attributes defined for that method.
+    def scrape(file_string, line, mod, attribute=nil)
+      hash = scrape_file(file_string, line) || {}
+      options = (arr = hash.delete(:option)) ? parse_option_comments(arr, mod) : {}
+      hash.select {|k,v| v && (attribute.nil? || attribute == k) }.each do |k,v|
+        hash[k] = EVAL_ATTRIBUTES.include?(k) ? eval_comment(v.join(' '), mod, k) : v.join(' ')
+      end
+      (hash[:options] ||= {}).merge!(options) if !options.empty?
+      attribute ? hash[attribute] : hash
+    end
+
+    #:stopdoc:
+    def parse_option_comments(arr, mod)
+      arr.inject({}) {|t,e|
+        key, val = e.join(' ').split(/\s*,\s*/, 2)
+        if val
+          key = key.sub(/^\s*:/, '').to_sym
+          t[key] = eval_comment(val, mod, 'option')
+        end
+        t
+      }
+    end
+
+    def eval_comment(value, mod, mattr)
+      value = "{#{value}}" if !value[/^\s*\{/] && value[/=>/]
+      mod.module_eval(value)
+    rescue Exception
+      if Boson.debug
+        warn "DEBUG: Error while evaluating @#{mattr} in module #{mod.to_s[/\w+$/]}:\n  " +
+          $!.message.gsub(/\n/, "\n  ")
+      end
+      nil
+    end
+
+    # Scrapes a given string for commented @keywords, starting with the line above the given line
+    def scrape_file(file_string, line)
+      lines = file_string.split("\n")
+      saved = []
+      i = line -2
+      while lines[i] =~ /^\s*#\s*(\S+)/ && i >= 0
+        saved << lines[i]
+        i -= 1
+      end
+
+      saved.empty? ? {} : splitter(saved.reverse)
+    end
+
+    def splitter(lines)
+      hash = {}
+      i = 0
+      # to magically make the last comment a description
+      unless lines.any? {|e| e =~  /^\s*#\s*@desc/ }
+        last_line = lines.pop
+        hash[:desc] = (last_line =~ /^\s*#\s*([^@\s].*)/) ? [$1] : nil
+        lines << last_line unless hash[:desc]
+      end
+
+      option = []
+      while i < lines.size
+        while lines[i] =~ /^\s*#\s*@(\w+)\s*(.*)/
+          key = $1.to_sym
+          hash[key] = [$2]
+          i += 1
+          while lines[i] =~ /^\s*#\s*([^@\s].*)/
+            hash[key] << $1
+            i+= 1
+          end
+          option << hash.delete(:option) if key == :option
+        end
+        i += 1
+      end
+      hash[:option] = option if !option.empty?
+      hash
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/console.rb

@@ -0,0 +1,40 @@
+require 'boson/console_runner'
+
+module Boson
+  CONFIG.update console_defaults: []
+
+  # Additional options added to Repo:
+  # [:console_defaults] Array of libraries to load at start up when used in irb. Default is to load all library files and libraries
+  #                     defined in the config.
+  # [:console] Console to load when using --console from commandline. Default is irb.
+  module Console
+    # Start Boson by loading repositories and their configured libraries.
+    # See ConsoleRunner.start for its options.
+    def start(options={})
+      ConsoleRunner.start(options)
+    end
+  end
+  extend Console
+
+  # [:console] This drops Boson into irb after having loaded default commands and any explict libraries with
+  #            :load option. This is a good way to start irb with only certain libraries loaded.
+  module ConsoleOptions
+    def early_option?(args)
+      if @options[:console]
+        ConsoleRunner.bin_start(@options[:console], @options[:load])
+        true
+      else
+        super
+      end
+    end
+  end
+
+  if defined? BinRunner
+    class BinRunner < BareRunner
+      GLOBAL_OPTIONS.update console:
+        {:type=>:boolean,
+          :desc=>"Drops into irb with default and explicit libraries loaded"}
+      extend ConsoleOptions
+    end
+  end
+end

data/lib/boson/console_runner.rb

@@ -0,0 +1,60 @@
+require 'boson/save'
+
+module Boson
+  # Runner used when starting irb. To use in irb, drop this in your ~/.irbrc:
+  #   require 'boson'
+  #   Boson.start
+  class ConsoleRunner < BareRunner
+    class <<self
+      # Starts Boson by loading configured libraries. If no default libraries are specified in the config,
+      # it will load up all detected libraries. Options:
+      # [:libraries] Array of libraries to load.
+      # [:verbose] Boolean to be verbose about libraries loading. Default is true.
+      # [:no_defaults] Boolean or :all which turns off loading default libraries. If set to true,
+      #                effects loading user's console default libraries. If set to :all, effects
+      #                all libraries including boson's. Default is false.
+      # [:autoload_libraries] Boolean which makes any command execution easier. It redefines
+      #                       method_missing on Boson.main_object so that commands with unloaded
+      #                       libraries are automatically loaded. Default is false.
+      def start(options={})
+        super
+        @options = {:verbose=>true}.merge options
+        init unless @initialized
+        Manager.load(@options[:libraries], load_options) if @options[:libraries]
+      end
+
+      # Loads libraries and then starts irb (or the configured console) from the commandline.
+      def bin_start(repl, libraries)
+        start :no_defaults=>true, :libraries=>libraries
+        repl = Boson.repo.config[:console] if Boson.repo.config[:console]
+        repl = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb' unless repl.is_a?(String)
+        unless repl.index('/') == 0 || (repl = Util.which(repl))
+          abort "Console not found. Please specify full path in config[:console]."
+        else
+          load_repl(repl)
+        end
+      end
+
+      def load_repl(repl) #:nodoc:
+        ARGV.replace ['-f']
+        $progname = $0
+        alias $0 $progname
+        Kernel.load $0 = repl
+      end
+
+      def init #:nodoc:
+        super
+        define_autoloader if @options[:autoload_libraries]
+        @initialized = true
+      end
+
+      def default_libraries #:nodoc:
+        return [] if @options[:no_defaults] == :all
+        return super if @options[:no_defaults]
+        defaults = super + Boson.repos.map {|e| e.config[:console_defaults] }.flatten
+        defaults += detected_libraries if defaults.empty?
+        defaults.uniq
+      end
+    end
+  end
+end

data/lib/boson/index.rb

@@ -0,0 +1,48 @@
+module Boson
+  # This class manages indexing/storing all commands and libraries. See RepoIndex for details
+  # about the index created for each Repo.
+  module Index
+    extend self
+    # Array of indexes, one per repo in Boson.repos.
+    def indexes
+      @indexes ||= Boson.repos.map {|e| RepoIndex.new(e) }
+    end
+
+    # Updates all repo indexes.
+    def update(options={})
+      indexes.each {|e| e.update(options) }
+    end
+
+    #:stopdoc:
+    def read
+      indexes.each {|e| e.read }
+    end
+
+    def find_library(command, object=false)
+      indexes.each {|e|
+        (lib = e.find_library(command, object)) and return lib
+      }
+      nil
+    end
+
+    def find_command(command)
+      indexes.each {|e|
+        (cmd = Command.find(command, e.commands)) and return(cmd)
+      }
+      nil
+    end
+
+    def commands
+      indexes.map {|e| e.commands}.flatten
+    end
+
+    def libraries
+      indexes.map {|e| e.libraries}.flatten
+    end
+
+    def all_main_methods
+      indexes.map {|e| e.all_main_methods}.flatten
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/libraries/file_library.rb

@@ -0,0 +1,144 @@
+module Boson
+  # This class loads a file by its path relative to the commands directory of a repository.
+  # For example the library 'public/misc' could refer to the file '~/.boson/commands/public/misc.rb'.
+  # If a file's basename is unique in its repository, then it can be loaded with its basename i.e. 'misc'
+  # for the previous example. When loading a library, this class searches repositories in the order given by
+  # Boson.repos.
+  #
+  # === Creating a FileLibrary
+  # Start by creating a file with a module and some methods (See Library for naming a module).
+  # Non-private methods are automatically loaded as a library's commands.
+  #
+  # Take for example a library brain.rb:
+  #   # Drop this in ~/.boson/commands/brain.rb
+  #   module Brain
+  #     def take_over(destination)
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #     end
+  #   end
+  #
+  # Once loaded, this library can be run from the commandline or irb:
+  #  $ boson take_over world
+  #  >> take_over 'world'
+  #
+  # If the library is namespaced, the command would be run as brain.take_over.
+  #
+  # Let's give Brain an option in his conquest:
+  #   module Brain
+  #     options :execute=>:string
+  #     def take_over(destination, options={})
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #       system(options[:execute]) if options[:execute]
+  #     end
+  #   end
+  #
+  # From the commandline and irb this runs as:
+  #   $ boson take_over world -e initiate_brainiac
+  #   >> take_over 'world -e initiate_brainiac'
+  #
+  # Since Boson aims to make your libraries just standard ruby, we can achieve the above
+  # by making options a commented method attribute:
+  #   module Brain
+  #     # @options :execute=>:string
+  #     # Help Brain live the dream
+  #     def take_over(destination, options={})
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #       system(options[:execute]) if options[:execute]
+  #     end
+  #   end
+  #
+  # Some points about the above:
+  # * A '@' must prefix options and other method attributes that become comments.
+  # * Note the comment above the method. One-line comments right before a method set a command's description.
+  # * See Inspector for other method attributes, like config that can be placed above a method.
+  #
+  # Once a command has a defined option, a command can also recognize a slew of global options:
+  #   >> take_over '-h'
+  #   take_over [destination] [--execute=STRING]
+  #
+  #   # prints much more verbose help
+  #   >> take_over '-hv'
+  #
+  # For more about these global options see OptionCommand and View.
+  class FileLibrary < Library
+    #:stopdoc:
+    def self.library_file(library, dir)
+      File.join(Repo.commands_dir(dir), library + ".rb")
+    end
+
+    def self.matched_repo; @repo; end
+
+    def self.read_library_file(file, reload=false)
+      @file_cache ||= {}
+      @file_cache[file] = File.read(file) if (!@file_cache.has_key?(file) || reload)
+      @file_cache[file]
+    end
+
+    def self.reset_file_cache(name=nil)
+      if name && @file_cache
+        @file_cache.delete(library_file(name, (matched_repo || Boson.repo).dir))
+      else
+        @file_cache = nil
+      end
+    end
+
+    handles {|source|
+      @repo = Boson.repos.find {|e| File.exists? library_file(source.to_s, e.dir) } ||
+       Boson.repos.find {|e|
+        Dir["#{e.commands_dir}/**/*.rb"].grep(/\/#{source}\.rb/).size == 1
+        }
+      !!@repo
+    }
+
+    def library_file(name=@name)
+      self.class.library_file(name, @repo_dir)
+    end
+
+    def set_repo
+      self.class.matched_repo
+    end
+
+    def set_name(name)
+      @lib_file = File.exists?(library_file(name.to_s)) ? library_file(name.to_s) :
+        Dir[self.class.matched_repo.commands_dir.to_s+'/**/*.rb'].find {|e| e =~ /\/#{name}\.rb$/}
+      @lib_file.gsub(/^#{self.class.matched_repo.commands_dir}\/|\.rb$/, '')
+    end
+
+    def base_module
+      @base_module ||= @name.include?('/') ? create_module_from_path : Commands
+    end
+
+    def load_source(reload=false)
+      library_string = self.class.read_library_file(@lib_file, reload)
+      Inspector.enable
+      base_module.module_eval(library_string, @lib_file)
+      Inspector.disable
+    end
+
+    def create_module_from_path(index=-2)
+      @name.split('/')[0..index].inject(Boson::Commands) {|base, e|
+        base.const_defined?(sub_mod = Util.camelize(e)) ? base.const_get(sub_mod) :
+          Util.create_module(base, e)
+      }
+    end
+
+    def load_source_and_set_module
+      detected = detect_additions(:modules=>true) { load_source }
+      @module = determine_lib_module(detected[:modules]) unless @module
+    end
+
+    def determine_lib_module(detected_modules)
+      detected_modules = detected_modules.select {|e| e.to_s[/^#{base_module}::/] }
+      case detected_modules.size
+      when 1 then lib_module = detected_modules[0]
+      when 0 then lib_module = create_module_from_path(-1)
+      else
+        unless (lib_module = Util.constantize("boson/commands/#{@name}")) && lib_module.to_s[/^Boson::Commands/]
+          raise LoaderError, "Can't detect module. Specify a module in this library's config."
+        end
+      end
+      lib_module
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/libraries/gem_library.rb

@@ -0,0 +1,30 @@
+module Boson
+  # This library loads a gem by the given name. Unlike FileLibrary or ModuleLibrary, this library
+  # doesn't need a module to provide its functionality.
+  #
+  # Example:
+  #   >> load_library 'httparty', :class_commands=>{'put'=>'HTTParty.put',
+  #      'delete'=>'HTTParty.delete' }
+  #   => true
+  #   >> put 'http://someurl.com'
+  class GemLibrary < Library
+    #:stopdoc:
+    def self.is_a_gem?(name)
+      return false unless defined? Gem
+      Gem::VERSION >= '1.8.0' ?
+        Gem::Specification.find_all_by_name(name)[0].is_a?(Gem::Specification) :
+        Gem.searcher.find(name).is_a?(Gem::Specification)
+    end
+
+    handles {|source| is_a_gem?(source.to_s) }
+
+    def loaded_correctly?
+      !@gems.empty? || !@commands.empty? || !!@module
+    end
+
+    def load_source_and_set_module
+      detect_additions { Util.safe_require @name }
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/libraries/local_file_library.rb

@@ -0,0 +1,30 @@
+# This class loads any local file and is most commonly used to load a local
+# Bosonfile. Since this file doesn't exist inside a normal Repo, it is not indexed with any repo.
+# Since file-based libraries need to be associated with a repository, Boson associates it
+# with a local repository if it exists or defaults to Boson.repo. See Boson::FileLibrary
+# for more info about this library.
+#
+# Example:
+#   >> load_library 'Bosonfile'
+#   => true
+class Boson::LocalFileLibrary < Boson::FileLibrary
+  handles {|source|
+    @repo = (File.exists?(source.to_s) ? (Boson.local_repo || Boson.repo) : nil)
+    !!@repo
+  }
+
+  #:stopdoc:
+  def set_name(name)
+    @lib_file = File.expand_path(name.to_s)
+    File.basename(@lib_file).downcase
+  end
+
+  def base_module
+    Boson::Commands
+  end
+
+  def library_file
+    @lib_file
+  end
+  #:startdoc:
+end

data/lib/boson/libraries/module_library.rb

@@ -0,0 +1,37 @@
+module Boson
+  # This library takes a module or class as a library's name and loads its class methods
+  # as commands. If no commands are given it defaults to loading all of its class methods
+  # as commands. The only method callback (see Loader) this library calls on the
+  # original module/class is config().
+  #
+  # Example:
+  #  >> load_library Math, :commands=>%w{sin cos tan}
+  #  => true
+  #
+  #  # Let's brush up on ol trig
+  #  >> sin (Math::PI/2)
+  #  => 1.0
+  #  >> tan (Math::PI/4)
+  #  => 1.0
+  #  # Close enough :)
+  #  >> cos (Math::PI/2)
+  #  => 6.12323399573677e-17
+
+  class ModuleLibrary < Library
+    #:stopdoc:
+    handles {|source| source.is_a?(Module) }
+
+    def set_name(name)
+      @module = name
+      underscore_lib = name.to_s[/^Boson::Commands/] ? name.to_s.split('::')[-1] : name.to_s
+      Util.underscore(underscore_lib)
+    end
+
+    def load_commands
+      @class_commands = {@module.to_s=>Array(@commands).empty? ? @module.methods(false) : @commands }
+      @module = nil
+      super
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/libraries/require_library.rb

@@ -0,0 +1,23 @@
+# This library requires the given name. This is useful for loading standard libraries,
+# non-gem libraries (i.e. rip packages) and anything else in $LOAD_PATH.
+#
+# Example:
+#   >> load_library 'fileutils', :class_commands=>{'cd'=>'FileUtils.cd', 'cp'=>'FileUtils.cp'}
+#   => true
+#   >> cd '/home'
+#   => 0
+#   >> Dir.pwd
+#   >> '/home'
+class Boson::RequireLibrary < Boson::GemLibrary
+  EXTENSIONS = ['', '.rb', '.rbw', '.so', '.bundle', '.dll', '.sl', '.jar']
+  handles {|source|
+    extensions_glob = "{#{EXTENSIONS.join(',')}}"
+    ($LOAD_PATH - ['.']).any? {|dir|
+      Dir["#{File.expand_path source.to_s, dir}#{extensions_glob}"].size > 0
+    }
+  }
+
+  def loaded_correctly?
+    super || $".grep(/^#{@name}\.([a-z]+)?$/).size > 0
+  end
+end