boson 0.0.1

data/lib/boson/commands/web_core.rb

@@ -0,0 +1,36 @@
+module Boson::Commands::WebCore #:nodoc:
+  def self.config
+    descriptions = {
+      :install=>"Installs a library by url. Library should then be loaded with load_library.",
+      :browser=>"Opens urls in a browser", :get=>"Gets the body of a url" }
+    commands = descriptions.inject({}) {|h,(k,v)| h[k.to_s] = {:description=>v}; h}
+    commands['install'][:options] = {:name=>:string, :force=>:boolean}
+    {:library_file=>File.expand_path(__FILE__), :commands=>commands}
+  end
+
+  def get(url)
+    %w{uri net/http}.each {|e| require e }
+    Net::HTTP.get(URI.parse(url))
+  rescue
+    raise "Error opening #{url}"
+  end
+
+  def install(url, options={})
+    options[:name] ||= strip_name_from_url(url)
+    return puts("Please give a library name with this url.") unless options[:name]
+    filename = File.join Boson.repo.commands_dir, "#{options[:name]}.rb"
+    return puts("Library name #{options[:name]} already exists. Try a different name.") if File.exists?(filename) && !options[:force]
+    File.open(filename, 'w') {|f| f.write get(url) }
+    puts "Saved to #{filename}."
+  end
+
+  # non-mac users should override this with the launchy gem
+  def browser(*urls)
+    system('open', *urls)
+  end
+
+  private
+  def strip_name_from_url(url)
+    url[/\/([^\/.]+)(\.[a-z]+)?$/, 1]
+  end
+end

data/lib/boson/index.rb

@@ -0,0 +1,95 @@
+require 'digest/md5'
+module Boson
+  module Index
+    extend self
+    attr_reader :libraries, :commands
+
+    def read_and_transfer(ignored_libraries=[])
+      read
+      existing_libraries = (Boson.libraries.map {|e| e.name} + ignored_libraries).uniq
+      Boson.libraries += @libraries.select {|e| !existing_libraries.include?(e.name)}
+      existing_commands = Boson.commands.map {|e| e.name} #td: consider namespace
+      Boson.commands += @commands.select {|e| !existing_commands.include?(e.name) && !ignored_libraries.include?(e.lib)}
+    end
+
+    def update(options={})
+      options[:all] = true if !exists? && !options.key?(:all)
+      libraries_to_update = options[:all] ? Runner.all_libraries : changed_libraries
+      read_and_transfer(libraries_to_update)
+      if options[:verbose]
+        puts options[:all] ? "Generating index for all #{libraries_to_update.size} libraries. Patience ... is a bitch" :
+          (libraries_to_update.empty? ? "No libraries indexed" :
+          "Indexing the following libraries: #{libraries_to_update.join(', ')}")
+      end
+      Manager.load(libraries_to_update, options.merge(:index=>true)) unless libraries_to_update.empty?
+      write
+    end
+
+    def exists?
+      File.exists? marshal_file
+    end
+
+    def write
+      save_marshal_index Marshal.dump([Boson.libraries, Boson.commands, latest_hashes])
+    end
+
+    def save_marshal_index(marshal_string)
+      File.open(marshal_file, 'w') {|f| f.write marshal_string }
+    end
+
+    def read
+      return if @read
+      @libraries, @commands, @lib_hashes = exists? ? Marshal.load(File.read(marshal_file)) : [[], [], {}]
+      set_latest_namespaces
+      @read = true
+    end
+
+    # get latest namespaces from config files
+    def set_latest_namespaces
+      namespace_libs = Boson.repo.config[:auto_namespace] ? @libraries.map {|e| [e.name, {:namespace=>true}]} :
+        Boson.repo.config[:libraries].select {|k,v| v && v[:namespace] }
+      lib_commands = @commands.inject({}) {|t,e| (t[e.lib] ||= []) << e; t }
+      namespace_libs.each {|name, hash|
+        if (lib = @libraries.find {|l| l.name == name})
+          lib.namespace = (hash[:namespace] == true) ? lib.clean_name : hash[:namespace]
+          (lib_commands[lib.name] || []).each {|e| e.namespace = lib.namespace }
+        end
+      }
+    end
+
+    def namespaces
+      @libraries.map {|e| e.namespace }.compact
+    end
+
+    def all_main_methods
+      @commands.reject {|e| e.namespace }.map {|e| [e.name, e.alias]}.flatten.compact + namespaces
+    end
+
+    def marshal_file
+      File.join(Boson.repo.config_dir, 'index.marshal')
+    end
+
+    def find_library(command)
+      read
+      namespace_command = command.split('.')[0]
+      if (lib = @libraries.find {|e| e.namespace == namespace_command })
+        lib.name
+      elsif (cmd = Command.find(command, @commands))
+        cmd.lib
+      end
+    end
+
+    def changed_libraries
+      read
+      latest_hashes.select {|lib, hash| @lib_hashes[lib] != hash}.map {|e| e[0]}
+    end
+
+    def latest_hashes
+      Runner.all_libraries.inject({}) {|h, e|
+        lib_file = FileLibrary.library_file(e, Boson.repo.dir)
+        h[e] = Digest::MD5.hexdigest(File.read(lib_file)) if File.exists?(lib_file)
+        h
+      }
+    end
+  end
+end

data/lib/boson/inspector.rb

@@ -0,0 +1,80 @@
+module Boson
+  # Scrapes and processes method metadata with the inspectors (MethodInspector, CommentInspector
+  # and ArgumentInspector) and hands off the usable data to FileLibrary objects.
+  module Inspector
+    extend self
+    attr_reader :enabled
+
+    # Enable scraping by overridding method_added to snoop on a library while it's
+    # loading its methods.
+    def enable
+      @enabled = true
+      body = MethodInspector::METHODS.map {|e|
+        %[def #{e}(val)
+            Boson::MethodInspector.#{e}(self, val)
+          end]
+      }.join("\n") +
+      %[
+        def new_method_added(method)
+          Boson::MethodInspector.new_method_added(self, method)
+        end
+
+        alias_method :_old_method_added, :method_added
+        alias_method :method_added, :new_method_added
+      ]
+    ::Module.module_eval body
+    end
+
+    # Disable scraping method data.
+    def disable
+      ::Module.module_eval %[
+        Boson::MethodInspector::METHODS.each {|e| remove_method e }
+        alias_method :method_added, :_old_method_added
+      ]
+      @enabled = false
+    end
+
+    # Adds method data scraped for the library's module to the library's commands.
+    def add_method_data_to_library(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
+    end
+
+    #:stopdoc:
+    def add_method_scraped_data
+      (MethodInspector::METHODS + [:method_args]).each do |e|
+        key = command_key(e)
+        (@store[e] || []).each do |cmd, val|
+          if no_command_config_for(cmd, key)
+            (@commands_hash[cmd] ||= {})[key] = val
+          end
+        end
+      end
+    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)
+        MethodInspector::METHODS.each do |e|
+          if no_command_config_for(cmd, e)
+            (@commands_hash[cmd] ||= {})[command_key(e)] = scraped[e]
+          end
+        end
+      end
+    end
+
+    # translates from inspector attribute name to command attribute name
+    def command_key(key)
+      {:method_args=>:args, :desc=>:description}[key] || key
+    end
+
+    def no_command_config_for(cmd, attribute)
+      !@commands_hash[cmd] || (@commands_hash[cmd] && !@commands_hash[cmd].key?(attribute))
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/inspectors/argument_inspector.rb

@@ -0,0 +1,92 @@
+# Extracts arguments and their default values from methods either by
+# by scraping a method's text or with method_added and brute force eval (thanks to
+# {eigenclass}[http://eigenclass.org/hiki/method+arguments+via+introspection]).
+module Boson::ArgumentInspector
+  extend self
+  # Returns same argument arrays as scrape_with_eval but argument defaults haven't been evaluated.
+  def scrape_with_text(file_string, meth)
+    tabspace = "[ \t]"
+    if match = /^#{tabspace}*def#{tabspace}+#{meth}#{tabspace}*($|\(?\s*([^\)]+)\s*\)?\s*$)/.match(file_string)
+      (match.to_a[2] || '').split(/\s*,\s*/).map {|e| e.split(/\s*=\s*/)}
+    end
+  end
+
+  # Max number of arguments extracted per method with scrape_with_eval
+  MAX_ARGS = 10
+  # Scrapes non-private methods for argument names and default values.
+  # Returns arguments as array of argument arrays with optional default value as a second element.
+  # ====Examples:
+  #   def meth1(arg1, arg2='val', options={}) -> [['arg1'], ['arg2', 'val'], ['options', {}]]
+  #   def meth2(*args) -> [['*args']]
+  def scrape_with_eval(meth, klass, object)
+    unless %w[initialize].include?(meth.to_s)
+      return if class << object; private_instance_methods(true) end.include?(meth.to_s)
+    end
+    params, values, arity, num_args = trace_method_args(meth, klass, object)
+    return if local_variables == params # nothing new found
+    format_arguments(params, values, arity, num_args)
+    rescue Exception
+      # puts "#{klass}.#{meth}: #{$!.message}"
+    ensure
+      set_trace_func(nil)
+  end
+
+  # process params + values to return array of argument arrays
+  def format_arguments(params, values, arity, num_args) #:nodoc:
+    params ||= []
+    params = params[0,num_args]
+    params.inject([[], 0]) do |(a, i), x|
+      if Array === values[i]
+        [a << ["*#{x}"], i+1]
+      else
+        if arity < 0 && i >= arity.abs - 1
+          [a << [x, values[i]], i + 1]
+        else
+          [a << [x], i+1]
+        end
+      end
+    end.first
+  end
+
+  def trace_method_args(meth, klass, object) #:nodoc:
+    file = line = params = values = nil
+    arity = klass.instance_method(meth).arity
+    set_trace_func lambda{|event, file, line, id, binding, classname|
+      begin
+        if event[/call/] && classname == klass && id == meth
+          params = eval("local_variables", binding)
+          values = eval("local_variables.map{|x| eval(x)}", binding)
+          throw :done
+        end
+      rescue Exception
+      end
+    }
+    if arity >= 0
+      num_args = arity
+      catch(:done){ object.send(meth, *(0...arity)) }
+    else
+      num_args = 0
+      # determine number of args (including splat & block)
+      MAX_ARGS.downto(arity.abs - 1) do |i|
+        catch(:done) do 
+          begin
+            object.send(meth, *(0...i)) 
+          rescue Exception
+          end
+        end
+        # all nils if there's no splat and we gave too many args
+        next if !values || values.compact.empty? 
+        k = nil
+        values.each_with_index{|x,j| break (k = j) if Array === x}
+        num_args = k ? k+1 : i
+        break
+      end
+      args = (0...arity.abs-1).to_a
+      catch(:done) do 
+        args.empty? ? object.send(meth) : object.send(meth, *args)
+      end
+    end
+    set_trace_func(nil)
+    return [params, values, arity, num_args]
+  end
+end

data/lib/boson/inspectors/comment_inspector.rb

@@ -0,0 +1,79 @@
+module Boson
+  # Scrapes comments right before a method for its metadata. Metadata attributes are the
+  # same as MethodInspector: desc, options, render_options. Attributes must begin with '@' i.e.:
+  #
+  #    # @desc Does foo
+  #    # @options :verbose=>true
+  #    def foo(options={})
+  #
+  # Some rules about comment 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 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]
+
+    # 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) || {}
+      hash.select {|k,v| v && (attribute.nil? || attribute == k) }.each do |k,v|
+        hash[k] = EVAL_ATTRIBUTES.include?(k) ? eval_comment(v.join(' '), mod) : v.join(' ')
+      end
+      attribute ? hash[attribute] : hash
+    end
+
+    #:stopdoc:
+    def eval_comment(value, mod)
+      value = "{#{value}}" if !value[/^\s*\{/] && value[/=>/]
+      begin mod.module_eval(value); rescue(Exception); nil end
+    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
+
+      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
+        end
+        i += 1
+      end
+      hash
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/inspectors/method_inspector.rb

@@ -0,0 +1,94 @@
+module Boson
+  # Allows for defining method metadata with new_method_added and the
+  # following Module methods:
+  # * desc: Defines a description for a method/command
+  # * options: Defines an OptionParser object for a method's options.
+  # * render_options: Defines an OptionParser object for a method's rendering options.
+  #
+  # These method calls must come immediately before a method i.e.:
+  #
+  #     desc "Does foo"
+  #     options :verbose=>:boolean
+  #     def foo(options={})
+  #
+  # This module also allows for defining method metadata as comments. Although the actual
+  # scraping of comments is handled by CommentInspector, MethodInspector gather's the method
+  # location it needs with with find_method_locations().
+  module MethodInspector
+    extend self
+    attr_accessor :current_module
+    attr_reader :mod_store
+    @mod_store ||= {}
+    METHODS = [:desc, :options, :render_options]
+
+    # The method_added used while scraping method metadata.
+    def new_method_added(mod, meth)
+      return unless mod.name[/^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
+
+      if store[:temp].size < 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|
+        store(mod)[e] ||= {}
+        (store(mod)[:temp] ||= {})[e] = val
+      end
+    end
+
+    # Scrapes a method's arguments using ArgumentInspector.
+    def scrape_arguments(meth)
+      store[:method_args] ||= {}
+
+      o = Object.new
+      o.extend(@current_module)
+      # private methods return nil
+      if (val = ArgumentInspector.scrape_with_eval(meth, @current_module, o))
+        store[:method_args][meth.to_s] = val
+      end
+    end
+
+    # 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 =~ /in `load_source'/ })
+        (line =~ /^(.*):(\d+)/) ? [$1, $2.to_i] : nil
+      end
+    end
+
+    #:stopdoc:
+    # 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