bosonson 0.304.1

data/lib/boson/library.rb

@@ -0,0 +1,179 @@
+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, ModuleLibrary and LocalFileLibrary.
+  # See Loader for callbacks a library's module can have.
+  #
+  # == 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).
+  # * All libraries can be configured by passing a hash of {library attributes}[link:classes/Boson/Library.html#M000077] under
+  #   {the :libraries key}[link:classes/Boson/Repo.html#M000070] to the main config file ~/.boson/config/boson.yml.
+  #   For most libraries this may be the only way to configure a library's commands.
+  #   An example of a GemLibrary config:
+  #    :libraries:
+  #      httparty:
+  #       :class_commands:
+  #         delete: HTTParty.delete
+  #       :commands:
+  #         delete:
+  #           :alias: d
+  #           :desc: Http delete a given url
+  #
+  # When installing a third-party library, use the config file as a way to override default library and command attributes
+  # without modifying the library.
+  #
+  # === Creating Your Own Library
+  # 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, :indexed_namespace]
+    attr_reader *(ATTRIBUTES + [:commands_hash, :library_file, :object_namespace])
+    # Private attribute for use within Boson.
+    attr_reader :no_alias_creation, :new_module, :new_commands, :class_commands, :lib_file, :repo_dir
+    # 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][@attribute]. When loading libraries, attributes
+    # can also be set via a library module's config() method (see Loader).
+    #
+    # Attributes that can be configured:
+    # [*:dependencies*] An array of libraries that this library depends on. A library won't load
+    #                   unless its dependencies are loaded first.
+    # [*:commands*] A hash or array of commands that belong to this library. A hash configures command attributes
+    #               for the given commands with command names pointing to their configs. See Command.new for a
+    #               command's configurable attributes. If an array, the commands are set for the given library,
+    #               overidding default command detection. Example:
+    #                :commands=>{'commands'=>{:desc=>'Lists commands', :alias=>'com'}}
+    # [*:class_commands*] A hash of commands to create. A hash key-pair can map command names to any string of ruby code
+    #                     that ends with a method call. Or a key-pair can map a class to an array of its class methods
+    #                     to create commands of the same name. Example:
+    #                      :class_commands=>{'spy'=>'Bond.spy', 'create'=>'Alias.manager.create',
+    #                       'Boson::Util'=>['detect', 'any_const_get']}
+    # [*:force*] Boolean which forces a library to ignore when a library's methods are overriding existing ones.
+    #            Use with caution. Default is false.
+    # [*: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.
+    # [*: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.
+    #                To control the namespacing of all libraries see Boson::Repo.config.
+    # [*:no_alias_creation*] Boolean which doesn't create aliases for a library. Useful for libraries that configure command
+    #                        aliases outside of Boson's control. Default is false.
+    def initialize(hash)
+      repo = set_repo
+      @repo_dir = repo.dir
+      @name = set_name(hash.delete(:name)) or raise ArgumentError, "Library missing required key :name"
+      @loaded = false
+      @commands_hash = {}
+      @commands = []
+      set_config (repo.config[:libraries][@name] || {}).merge(hash), true
+      set_command_aliases(repo.config[:command_aliases])
+    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
+
+    def namespace(orig=@namespace)
+      @namespace = [String,FalseClass].include?(orig.class) ? orig : begin
+        if (@namespace == true || (Boson.repo.config[:auto_namespace] && !@index))
+          @namespace = clean_name
+        else
+          @namespace = false
+        end
+      end
+    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 local?
+      is_a?(LocalFileLibrary) || (Boson.local_repo && Boson.local_repo.dir == @repo_dir)
+    end
+
+    def set_name(name)
+      name.to_s
+    end
+
+    def set_config(config, force=false)
+      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, force
+    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=self.commands, command_array=Boson.commands)
+      command_array.select {|e| names.include?(e.name) && e.lib == self.name }
+    end
+
+    def command_object(name)
+      command_objects([name])[0]
+    end
+
+    def marshal_dump
+      [@name, @commands, @gems, @module.to_s, @repo_dir, @indexed_namespace]
+    end
+
+    def marshal_load(ary)
+      @name, @commands, @gems, @module, @repo_dir, @indexed_namespace = ary
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/loader.rb

@@ -0,0 +1,118 @@
+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() functionality.
+  # When creating your own Library subclass, you should override load_source_and_set_module
+  # You can override other methods in this module as needed.
+  #
+  # === Module Callbacks
+  # For libraries that have a module i.e. FileLibrary and GemLibrary, 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.
+  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 = false
+      set_library_commands
+      @indexed_namespace = (@namespace == false) ? nil : @namespace if @index
+      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
+
+    #: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
+        @method_conflict = true
+        $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].map {|e| e.to_s }
+      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
+      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
+
+      Manager.create_class_aliases(@module, @class_commands) unless @class_commands.nil? ||
+        @class_commands.empty? || @method_conflict
+      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
+      @module.after_included if lib_module.respond_to?(:after_included) && !@index
+      Boson::Universe.send :extend_object, Boson.main_object
+    end
+
+    def check_for_method_conflicts
+      conflicts = namespace ? (Boson.can_invoke?(namespace) ? [namespace] : []) :
+        (@module.instance_methods + @module.private_instance_methods) & (Boson.main_object.methods +
+          Boson.main_object.private_methods)
+      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.uniq!
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/manager.rb

@@ -0,0 +1,169 @@
+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
+
+  # Handles loading of libraries and commands.
+  class Manager
+    class <<self
+      attr_accessor :failed_libraries
+
+      # 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
+      # Any options that aren't listed here are passed as library attributes to the libraries (see Library.new)
+      # ==== Options:
+      # [:verbose] Boolean to print each library's loaded status along with more verbose errors. Default is false.
+      def load(libraries, options={})
+        Array(libraries).map {|e|
+          (@library = load_once(e, options)) ? after_load : false
+        }.all?
+      end
+
+      #:stopdoc:
+      def failed_libraries
+        @failed_libraries ||= []
+      end
+
+      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
+        warn "DEBUG: Library #{library} didn't load due to append_features" if Runner.debug
+      rescue LoaderError=>e
+        FileLibrary.reset_file_cache(library.to_s)
+        failed_libraries << library
+        $stderr.puts "Unable to #{load_method} library #{library}. Reason: #{e.message}"
+      rescue StandardError, SyntaxError, LoadError =>e
+        FileLibrary.reset_file_cache(library.to_s)
+        failed_libraries << library
+        message = "Unable to #{load_method} library #{library}. Reason: #{$!}"
+        if Runner.debug
+          message += "\n" + e.backtrace.map {|e| "  " + e }.join("\n")
+        elsif @options[:verbose]
+          message += "\n" + e.backtrace.slice(0,3).map {|e| "  " + e }.join("\n")
+        end
+        $stderr.puts message
+      ensure
+        Inspector.disable if Inspector.enabled
+      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 "Library #{lib.name} did not load successfully." if !options[:dependency]
+              $stderr.puts "  "+lib.inspect if Runner.debug
+              false
+            end
+          end
+        end
+      end
+
+      def lib_dependencies
+        @lib_dependencies ||= {}
+      end
+
+      def load_dependencies(lib, options={})
+        lib_dependencies[lib] = Array(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(@options.merge(:name=>source))
+      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 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)
+        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
+        redefine_commands(lib, commands)
+      end
+
+      def redefine_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.redefine_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)
+        class_commands.dup.each {|k,v|
+          if v.is_a?(Array)
+            class_commands.delete(k).each {|e| class_commands[e] = "#{k}.#{e}"}
+          end
+        }
+        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