boson 0.0.1

data/lib/boson/libraries/file_library.rb

@@ -0,0 +1,76 @@
+module Boson
+  # This library loads a file in the commands subdirectory of a Boson::Repo. This library looks for files
+  # in repositories in the order given by Boson.repos.
+  # TODO: explain file format, modules, inspectors
+  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
+        #td: tia other repos
+        @file_cache.delete(library_file(name, 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)
+      }
+      !!@repo
+    }
+
+    def library_file
+      self.class.library_file(@name, @repo_dir)
+    end
+
+    def set_repo
+      self.class.matched_repo
+    end
+
+    def load_source(reload=false)
+      library_string = self.class.read_library_file(library_file, reload)
+      Inspector.enable
+      Commands.module_eval(library_string, library_file)
+      Inspector.disable
+    end
+
+    def load_source_and_set_module
+      detected = detect_additions(:modules=>true) { load_source }
+      @module = determine_lib_module(detected[:modules]) unless @module
+    end
+
+    def reload_source_and_set_module
+      detected = detect_additions(:modules=>true) { load_source(true) }
+      if (@new_module = !detected[:modules].empty?)
+        @commands = []
+        @module = determine_lib_module(detected[:modules])
+      end
+    end
+
+    def determine_lib_module(detected_modules)
+      case detected_modules.size
+      when 1 then lib_module = detected_modules[0]
+      when 0 then raise LoaderError, "Can't detect module. Make sure at least one module is defined in the library."
+      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,21 @@
+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.
+  class GemLibrary < Library
+    #:stopdoc:
+    def self.is_a_gem?(name)
+      Object.const_defined?(:Gem) && 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/module_library.rb

@@ -0,0 +1,17 @@
+module Boson
+  # A library which takes a module as a library's name. Reload for this library
+  # subclass is disabled.
+  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
+      super Util.underscore(underscore_lib)
+    end
+
+    def reload; false; end
+    #:startdoc:
+  end
+end

data/lib/boson/libraries/require_library.rb

@@ -0,0 +1,11 @@
+# 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.
+class Boson::RequireLibrary < Boson::GemLibrary
+  handles {|source|
+    begin
+      Kernel.load("#{source}.rb", true)
+    rescue LoadError
+      false
+    end
+  }
+end

data/lib/boson/library.rb

@@ -0,0 +1,108 @@
+module Boson
+  # A library is a group of commands (Command objects) usually grouped together by a module.
+  # Libraries are loaded from different sources depending on the library subclass. Default library
+  # subclasses are FileLibrary, GemLibrary, RequireLibrary and ModuleLibrary.
+  #
+  # To create your own subclass you need to define what sources the subclass can handle with handles().
+  # If handles() returns true then the subclass is chosen to load. See Loader to see what instance methods
+  # to override for a subclass.
+  class Library
+    include Loader
+    class <<self
+      #:stopdoc:
+      attr_accessor :handle_blocks
+      def handles(&block)
+        (Library.handle_blocks ||= []) << [self,block]
+      end
+      #:startdoc:
+    end
+
+    # Public attributes for use outside of Boson.
+    ATTRIBUTES = [:gems, :dependencies, :commands, :loaded, :module, :name, :namespace]
+    attr_reader *(ATTRIBUTES + [:commands_hash, :library_file, :object_namespace])
+    # Private attribute for use within Boson.
+    attr_reader :except, :no_alias_creation, :new_module, :new_commands
+    # Optional namespace name for a library. When enabled defaults to a library's name.
+    attr_writer :namespace
+    # Creates a library object with a hash of attributes which must include a :name attribute.
+    # Each hash pair maps directly to an instance variable and value. Defaults for attributes
+    # are read from config[:libraries][@library_name]. See Boson::Repo.config for more details.
+    def initialize(hash)
+      @name = set_name hash.delete(:name)
+      @loaded = false
+      repo = set_repo
+      @repo_dir = repo.dir
+      @commands_hash = {}
+      @commands = []
+      set_config (repo.config[:libraries][@name] || {}).merge(hash)
+      @commands_hash = repo.config[:commands].merge @commands_hash
+      set_command_aliases(repo.config[:command_aliases])
+      @namespace = true if Boson.repo.config[:auto_namespace] && @namespace.nil? &&
+        !Boson::Runner.default_libraries.include?(@module)
+      @namespace = clean_name if @namespace
+    end
+
+    # A concise symbol version of a library type i.e. FileLibrary -> :file.
+    def library_type
+      str = self.class.to_s[/::(\w+)Library$/, 1] || 'library'
+      str.downcase.to_sym
+    end
+
+    # The object a library uses for executing its commands.
+    def namespace_object
+      @namespace_object ||= @namespace ? Boson.invoke(@namespace) : Boson.main_object
+    end
+
+    #:stopdoc:
+    # handles names under directories
+    def clean_name
+      @name[/\w+$/]
+    end
+
+    def set_name(name)
+      name.to_s or raise ArgumentError, "New library missing required key :name"
+    end
+
+    def set_config(config)
+      if (commands = config.delete(:commands))
+        if commands.is_a?(Array)
+          @commands += commands
+          @pre_defined_commands = true
+        elsif commands.is_a?(Hash)
+          @commands += commands.keys
+          @commands_hash = Util.recursive_hash_merge commands, @commands_hash
+        end
+      end
+      set_command_aliases config.delete(:command_aliases) if config[:command_aliases]
+      set_attributes config, true
+    end
+
+    def set_command_aliases(command_aliases)
+      (command_aliases || {}).each do |cmd, cmd_alias|
+        @commands_hash[cmd] ||= {}
+        @commands_hash[cmd][:alias] ||= cmd_alias
+      end
+    end
+
+    def set_repo
+      Boson.repo
+    end
+
+    def set_attributes(hash, force=false)
+      hash.each {|k,v| instance_variable_set("@#{k}", v) if instance_variable_get("@#{k}").nil? || force }
+    end
+
+    def command_objects(names)
+      Boson.commands.select {|e| names.include?(e.name) && e.lib == self.name }
+    end
+
+    def marshal_dump
+      [@name, @commands, @gems, @module.to_s, @repo_dir]
+    end
+
+    def marshal_load(ary)
+      @name, @commands, @gems, @module, @repo_dir = ary
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/loader.rb

@@ -0,0 +1,103 @@
+module Boson
+  # Raised if a library has a method which conflicts with existing methods in Boson.main_object.
+  class MethodConflictError < LoaderError; end
+
+  # This module is mixed into Library to give it load() and reload() functionality.
+  # When creating your own Library subclass, you should override load_source_and_set_module and
+  # reload_source_and_set_module. You can override other methods in this module as needed.
+  module Loader
+    # Loads a library and its dependencies and returns true if library loads correctly.
+    def load
+      @gems ||= []
+      load_source_and_set_module
+      module_callbacks if @module
+      yield if block_given?
+      (@module || @class_commands) ? detect_additions { load_module_commands } : @namespace = nil
+      @init_methods.each {|m| namespace_object.send(m) if namespace_object.respond_to?(m) } if @init_methods && !@index
+      set_library_commands
+      loaded_correctly? && (@loaded = true)
+    end
+
+    # Load the source and set instance variables necessary to make a library valid i.e. @module.
+    def load_source_and_set_module; end
+
+    # Boolean which indicates if library loaded correctly.
+    def loaded_correctly?
+      !!@module
+    end
+
+    # Reloads a library from its source and adds new commands.
+    def reload
+      original_commands = @commands
+      reload_source_and_set_module
+      detect_additions { load_module_commands } if @new_module
+      @new_commands = @commands - original_commands
+      true
+    end
+
+    # Same as load_source_and_set_module except it reloads.
+    def reload_source_and_set_module
+      raise LoaderError, "Reload not implemented"
+    end
+
+    #:stopdoc:
+    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
+    end
+
+    def load_module_commands
+        initialize_library_module
+    rescue MethodConflictError=>e
+      if Boson.repo.config[:error_method_conflicts] || @namespace
+        raise MethodConflictError, e.message
+      else
+        @namespace = clean_name
+        $stderr.puts "#{e.message}. Attempting load into the namespace #{@namespace}..."
+        initialize_library_module
+      end
+    end
+
+    def detect_additions(options={}, &block)
+      options[:object_methods] = @object_methods if !@object_methods.nil?
+      detected = Util.detect(options, &block)
+      @gems += detected[:gems] if detected[:gems]
+      @commands += detected[:methods]
+      detected
+    end
+
+    def initialize_library_module
+      @module = @module ? Util.constantize(@module) : Util.create_module(Boson::Commands, clean_name)
+      raise(LoaderError, "No module for library #{@name}") unless @module
+      Manager.create_class_aliases(@module, @class_commands) unless @class_commands.to_s.empty?
+      check_for_method_conflicts unless @force
+      @namespace = clean_name if @object_namespace
+      @namespace ? Namespace.create(@namespace, self) : include_in_universe
+    end
+
+    def include_in_universe(lib_module=@module)
+      Boson::Universe.send :include, lib_module
+      Boson::Universe.send :extend_object, Boson.main_object
+    end
+
+    def check_for_method_conflicts
+      conflicts = @namespace ? (Boson.can_invoke?(@namespace) ? [@namespace] : []) :
+        Util.common_instance_methods(@module, Boson::Universe)
+      unless conflicts.empty?
+        raise MethodConflictError,"The following commands conflict with existing commands: #{conflicts.join(', ')}"
+      end
+    end
+
+    def set_library_commands
+      aliases = @commands_hash.select {|k,v| @commands.include?(k) }.map {|k,v| v[:alias]}.compact
+      @commands -= aliases
+      @commands.delete(@namespace) if @namespace
+      @commands += Boson.invoke(@namespace).boson_commands if @namespace && !@pre_defined_commands
+      @commands -= @except if @except
+      @commands.uniq!
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/manager.rb

@@ -0,0 +1,184 @@
+module Boson
+  # Base class for library loading errors. Raised mostly in Boson::Loader and rescued by Boson::Manager.
+  class LoaderError < StandardError; end
+  # Raised when a library's append_features returns false.
+  class AppendFeaturesFalseError < StandardError; end
+
+  class Manager
+    class <<self
+      # Loads a library or an array of libraries with options. Manager loads the first library subclass
+      # to meet a library subclass' criteria in this order: ModuleLibrary, FileLibrary, GemLibrary, RequireLibrary.
+      # ==== Examples:
+      #   Manager.load 'my_commands'  -> Loads a FileLibrary object from ~/.boson/commands/my_commands.rb
+      #   Manager.load 'method_lister' -> Loads a GemLibrary object which requires the method_lister gem
+      # ==== Options:
+      # [:verbose] Boolean to print each library's loaded status along with more verbose errors. Default is false.
+      # [:index]   Boolean to load in index mode. Default is false.
+      def load(libraries, options={})
+        libraries = [libraries] unless libraries.is_a?(Array)
+        libraries.map {|e|
+          (@library = load_once(e, options)) ? after_load : false
+        }.all?
+      end
+
+      # Reloads a library or an array of libraries with the following options:
+      # * :verbose: Boolean to print reload status. Default is false.
+      def reload(source, options={})
+        if (lib = Boson.library(source))
+          if lib.loaded
+            command_size = Boson.commands.size
+            @options = options
+            if (result = rescue_load_action(lib.name, :reload) { lib.reload })
+              after_reload(lib)
+              puts "Reloaded library #{source}: Added #{Boson.commands.size - command_size} commands" if options[:verbose]
+            end
+            result
+          else
+            puts "Library hasn't been loaded yet. Loading library #{source}..." if options[:verbose]
+            load(source, options)
+          end
+        else
+          puts "Library #{source} doesn't exist." if options[:verbose]
+          false
+        end
+      end
+
+      #:stopdoc:
+      def add_library(lib)
+        Boson.libraries.delete(Boson.library(lib.name))
+        Boson.libraries << lib
+      end
+
+      def loaded?(lib_name)
+        ((lib = Boson.library(lib_name)) && lib.loaded) ? true : false
+      end
+
+      def rescue_load_action(library, load_method)
+        yield
+      rescue AppendFeaturesFalseError
+      rescue LoaderError=>e
+        FileLibrary.reset_file_cache(library.to_s)
+        print_error_message "Unable to #{load_method} library #{library}. Reason: #{e.message}"
+      rescue Exception=>e
+        FileLibrary.reset_file_cache(library.to_s)
+        print_error_message "Unable to #{load_method} library #{library}. Reason: #{$!}" + "\n" +
+          e.backtrace.slice(0,3).join("\n")
+      ensure
+        Inspector.disable if Inspector.enabled
+      end
+
+      def print_error_message(message)
+        $stderr.puts message if !@options[:index] || (@options[:index] && @options[:verbose])
+      end
+
+      def load_once(source, options={})
+        @options = options
+        rescue_load_action(source, :load) do
+          lib = loader_create(source)
+          if loaded?(lib.name)
+            $stderr.puts "Library #{lib.name} already exists" if options[:verbose] && !options[:dependency]
+            false
+          else
+            if lib.load { load_dependencies(lib, options) }
+              lib
+            else
+              $stderr.puts "Unable to load library #{lib.name}." if !options[:dependency]
+              false
+            end
+          end
+        end
+      end
+
+      def lib_dependencies
+        @lib_dependencies ||= {}
+      end
+
+      def load_dependencies(lib, options={})
+        lib_dependencies[lib] = (lib.dependencies || []).map do |e|
+          next if loaded?(e)
+          load_once(e, options.merge(:dependency=>true)) ||
+            raise(LoaderError, "Can't load dependency #{e}")
+        end.compact
+      end
+
+      def loader_create(source)
+        lib_class = Library.handle_blocks.find {|k,v| v.call(source) } or raise(LoaderError, "Library #{source} not found.")
+        lib_class[0].new(:name=>source, :index=>@options[:index])
+      end
+
+      def after_load
+        create_commands(@library)
+        add_library(@library)
+        puts "Loaded library #{@library.name}" if @options[:verbose]
+        (lib_dependencies[@library] || []).each do |e|
+          create_commands(e)
+          add_library(e)
+          puts "Loaded library dependency #{e.name}" if @options[:verbose]
+        end
+        true
+      end
+
+      def after_reload(lib)
+        Boson.commands.delete_if {|e| e.lib == lib.name } if lib.new_module
+        create_commands(lib, lib.new_commands)
+      end
+
+      def before_create_commands(lib)
+        lib.is_a?(FileLibrary) && lib.module && Inspector.add_method_data_to_library(lib)
+      end
+
+      def create_commands(lib, commands=lib.commands)
+        if lib.except
+          commands -= lib.except
+          lib.except.each {|e| lib.namespace_object.instance_eval("class<<self;self;end").send :undef_method, e }
+        end
+        before_create_commands(lib)
+        commands.each {|e| Boson.commands << Command.create(e, lib)}
+        create_command_aliases(lib, commands) if commands.size > 0 && !lib.no_alias_creation
+        create_option_commands(lib, commands)
+      end
+
+      def create_option_commands(lib, commands)
+        option_commands = lib.command_objects(commands).select {|e| e.option_command? }
+        accepted, rejected = option_commands.partition {|e| e.args(lib) || e.arg_size }
+        if @options[:verbose] && rejected.size > 0
+          puts "Following commands cannot have options until their arguments are configured: " +
+            rejected.map {|e| e.name}.join(', ')
+        end
+        accepted.each {|cmd| Scientist.create_option_command(lib.namespace_object, cmd) }
+      end
+
+      def create_command_aliases(lib, commands)
+        lib.module ? prep_and_create_instance_aliases(commands, lib.module) : check_for_uncreated_aliases(lib, commands)
+      end
+
+      def prep_and_create_instance_aliases(commands, lib_module)
+        aliases_hash = {}
+        select_commands = Boson.commands.select {|e| commands.include?(e.name)}
+        select_commands.each do |e|
+          if e.alias
+            aliases_hash[lib_module.to_s] ||= {}
+            aliases_hash[lib_module.to_s][e.name] = e.alias
+          end
+        end
+        create_instance_aliases(aliases_hash)
+      end
+
+      def create_instance_aliases(aliases_hash)
+        Alias.manager.create_aliases(:instance_method, aliases_hash)
+      end
+
+      def create_class_aliases(mod, class_commands)
+        Alias.manager.create_aliases(:any_to_instance_method, mod.to_s=>class_commands.invert)
+      end
+
+      def check_for_uncreated_aliases(lib, commands)
+        return if lib.is_a?(GemLibrary)
+        if (found_commands = Boson.commands.select {|e| commands.include?(e.name)}) && found_commands.find {|e| e.alias }
+          $stderr.puts "No aliases created for library #{lib.name} because it has no module"
+        end
+      end
+      #:startdoc:
+    end
+  end
+end