bosonson 0.304.1

data/lib/boson/inspectors/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, config and render_options 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, :render_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 Runner.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/inspectors/method_inspector.rb

@@ -0,0 +1,98 @@
+module Boson
+  # Gathers method attributes by redefining method_added and capturing method
+  # calls before a method. This module also saves method locations so CommentInspector
+  # can scrape their commented method attributes.
+  module MethodInspector
+    extend self
+    attr_accessor :current_module, :mod_store
+    @mod_store ||= {}
+    METHODS = [:config, :desc, :options, :render_options]
+    METHOD_CLASSES = {:config=>Hash, :desc=>String, :options=>Hash, :render_options=>Hash}
+    ALL_METHODS = METHODS + [:option]
+
+    # The method_added used while scraping method attributes.
+    def new_method_added(mod, meth)
+      return unless mod.to_s[/^Boson::Commands::/]
+      self.current_module = mod
+      store[:temp] ||= {}
+      METHODS.each do |e|
+        store[e][meth.to_s] = store[:temp][e] if store[:temp][e]
+      end
+      (store[:options][meth.to_s] ||= {}).merge! store[:temp][:option] if store[:temp][:option]
+
+      if store[:temp].size < ALL_METHODS.size
+        store[:method_locations] ||= {}
+        if (result = find_method_locations(caller))
+          store[:method_locations][meth.to_s] = result
+        end
+      end
+      store[:temp] = {}
+      scrape_arguments(meth) if has_inspector_method?(meth, :options) || has_inspector_method?(meth,:render_options)
+    end
+
+    METHODS.each do |e|
+      define_method(e) do |mod, val|
+        (@mod_store[mod] ||= {})[e] ||= {}
+        (store(mod)[:temp] ||= {})[e] = val
+      end
+    end
+
+    def option(mod, name, value)
+      (@mod_store[mod] ||= {})[:options] ||= {}
+      (store(mod)[:temp] ||= {})[:option] ||= {}
+      (store(mod)[:temp] ||= {})[:option][name] = value
+    end
+
+    # Scrapes a method's arguments using ArgumentInspector.
+    def scrape_arguments(meth)
+      store[:args] ||= {}
+
+      o = Object.new
+      o.extend(@current_module)
+      # private methods return nil
+      if (val = ArgumentInspector.scrape_with_eval(meth, @current_module, o))
+        store[:args][meth.to_s] = val
+      end
+    end
+
+    CALLER_REGEXP = RUBY_VERSION < '1.9' ? /in `load_source'/ : /in `<module:.*>'/
+    # Returns an array of the file and line number at which a method starts using
+    # a caller array. Necessary information for CommentInspector to function.
+    def find_method_locations(stack)
+      if (line = stack.find {|e| e =~ CALLER_REGEXP })
+        (line =~ /^(.*):(\d+)/) ? [$1, $2.to_i] : nil
+      end
+    end
+
+    #:stopdoc:
+    def find_method_locations_for_19(klass, meth)
+      if (klass = Util.any_const_get(klass)) && (meth_location = klass.method(meth).source_location) &&
+        meth_location[0]
+        meth_location
+      end
+    end
+
+    # Hash of a module's method attributes i.e. descriptions, options by method and then attribute
+    def store(mod=@current_module)
+      @mod_store[mod]
+    end
+
+    def current_module=(mod)
+      @current_module = mod
+      @mod_store[mod] ||= {}
+    end
+
+    def has_inspector_method?(meth, inspector)
+      (store[inspector] && store[inspector].key?(meth.to_s)) || inspector_in_file?(meth.to_s, inspector)
+    end
+
+    def inspector_in_file?(meth, inspector_method)
+      return false if !(file_line = store[:method_locations] && store[:method_locations][meth])
+      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
+    #: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 and render_options, 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 initialize_library_module
+      @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