library 0.1.0

data/lib/library/autoload.rb

@@ -0,0 +1,14 @@
+# Ruby's autoload method does not use the normal require
+# mechanisms, therefore if we wish to support it we will
+# have to override and create our own system. OTOH Matz
+# has said autoload will go away in Ruby 2.0, so maybe
+# we can just let this go and not worry about it.
+
+module Kernel
+  #alias __autoload__ autoload
+end
+
+#class ::Module
+#  alias __autoload__ autoload
+#end
+

data/lib/library/core_ext.rb

@@ -0,0 +1,34 @@
+class File
+
+  #
+  RE_PATH_SEPERATOR = Regexp.new('[' + Regexp.escape(File::Separator) + %q{\\\/} + ']')
+
+  #
+  def self.split_root(path)
+    path.split(RE_PATH_SEPERATOR, 2)
+  end
+
+end
+
+class Hash
+
+  #
+  # Transform keys of hash returning a new hash.
+  #
+  def rekey #:yield:
+    if block_given?
+      inject({}){|h,(k,v)| h[yield(k)]=v; h}
+    else
+      inject({}){|h,(k,v)| h[k.to_sym]=v; h}
+    end
+  end
+
+  #
+  # In-place rekey.
+  #
+  def rekey! #:yield:
+    replace(rekey{|k| yield(k) })
+  end
+
+end
+

data/lib/library/domain.rb

@@ -0,0 +1,244 @@
+class Library
+
+  # This extension encapsulates Library's class methods.
+  #
+  module Domain
+
+    #
+    # Access to library ledger.
+    #
+    # @return [Array] The `$LEDGER` array.
+    #
+    def ledger
+      $LEDGER
+    end
+
+    #
+    # Library names from ledger.
+    #
+    # @return [Array] The keys from `$LEDGER` array.
+    #
+    def names
+      $LEDGER.keys
+    end
+
+    alias_method :list, :names
+
+    #
+    # Find matching library features. This is the "mac daddy" method used by
+    # the #require and #load methods to find the specified +path+ among
+    # the various libraries and their load paths.
+    #
+    def find(path, options={})
+      $LEDGER.find_feature(path, options)
+    end
+
+    #
+    # Brute force variation of `#find` looks through all libraries for a 
+    # matching features. This serves as the fallback method if `#find` comes
+    # up empty.
+    #
+    # @param [String] path
+    #   path name for which to search
+    #
+    # @param [Hash] options
+    #   Search options.
+    #
+    # @option options [Boolean] :latest
+    #   Search only the active or most current version of any library.
+    #
+    # @option options [Boolean] :suffix
+    #   Automatically try standard extensions if pathname has none.
+    #
+    # @option options [Boolean] :legacy
+    #   Do not match within library's +name+ directory, eg. `lib/foo/*`.
+    #
+    # @return [Feature,Array] Matching feature(s).
+    #
+    def find_any(path, options={})
+      $LEDGER.find_any(path, options)
+    end
+
+    #
+    # Brute force search looks through all libraries for matching features.
+    # This is the same as #find_any, but returns a list of matches rather
+    # then the first matching feature found.
+    #
+    # @param [String] path
+    #   path name for which to search
+    #
+    # @param [Hash] options
+    #   Search options.
+    #
+    # @option options [Boolean] :latest
+    #   Search only the active or most current version of any library.
+    #
+    # @option options [Boolean] :suffix
+    #   Automatically try standard extensions if pathname has none.
+    #
+    # @option options [Boolean] :legacy
+    #   Do not match within library's +name+ directory, eg. `lib/foo/*`.
+    #
+    # @return [Feature,Array] Matching feature(s).
+    #
+    def search(path, options={})
+      $LEDGER.search(path, options)
+    end
+
+    #
+    # Search for all matching library files that match the given pattern.
+    # This could be of useful for plugin loader.
+    #
+    # @param [Hash] options
+    #   Glob matching options.
+    #
+    # @option options [Boolean] :latest
+    #   Search only activated libraries or the most recent version
+    #   of a given library.
+    #
+    # @return [Array] Matching file paths.
+    #
+    # @todo Should this return list of Feature objects instead of file paths?
+    #
+    def glob(match, options={})
+      $LEDGER.glob(match, options)
+    end
+
+    #
+    # @deprecated
+    #
+    def find_files(match, options={})
+      glob(match, options)
+    end
+
+    #
+    # Access to global load stack.
+    #
+    # @return [Array] The `$LOAD_STACK` array.
+    #
+    def load_stack
+      $LOAD_STACK
+    end
+
+    #
+    # Require a feature from the library.
+    #
+    # @param [String] pathname
+    #   The pathname of feature relative to library's loadpath.
+    #
+    # @param [Hash] options
+    #
+    # @return [true,false] If feature was newly required or successfully loaded.
+    #
+    def require(pathname, options={})
+      if file = $LOAD_CACHE[pathname]
+        if options[:load]
+          return file.load
+        else
+          return false
+        end
+      end
+
+      if feature = Library.find(pathname, options)
+        #file.library_activate
+        $LOAD_CACHE[pathname] = feature
+        return feature.acquire(options)
+      end
+
+      # fallback to Ruby's own load mechinisms
+      if options[:load]
+        __load__(pathname, options[:wrap])
+      else
+        __require__(pathname)
+      end
+    end
+
+    #
+    # Load file path. This is just like #require except that previously
+    # loaded files will be reloaded and standard extensions will not be
+    # automatically appended.
+    #
+    # @param pathname [String]
+    #   pathname of feature relative to library's loadpath
+    #
+    # @return [true,false] if feature was successfully loaded
+    #
+    def load(pathname, options={}) #, &block)
+      #options.merge!(block.call) if block
+
+      if !Hash === options
+        options = {}
+        options[:wrap] = options 
+      end
+
+      options[:load]   = true
+      options[:suffix] = false
+      options[:local]  = false
+
+      require(pathname, options)
+
+      #if file = $LOAD_CACHE[path]
+      #  return file.load
+      #end
+
+      #if file = Library.find(path, options)
+      #  #file.library_activate
+      #  $LOAD_CACHE[path] = file
+      #  return file.load(options) #acquire(options)
+      #end
+
+      ##if options[:load]
+      #  __load__(path, options[:wrap])
+      ##else
+      ##  __require__(path)
+      ##end
+    end
+
+    #
+    # Roll-style loading. First it looks for a specific library via `:`.
+    # If `:` is not present it then tries the current loading library.
+    # Failing that it fallsback to Ruby itself.
+    #
+    #   require('facets:string/margin')
+    #
+    # To "load" the library, rather than "require" it, set the +:load+
+    # option to true.
+    #
+    #   require('facets:string/margin', :load=>true)
+    #
+    # @param pathname [String]
+    #   pathname of feature relative to library's loadpath
+    #
+    # @return [true, false] if feature was newly required
+    #
+    def acquire(pathname, options={}) #, &block)
+      #options.merge!(block.call) if block
+      options[:local] = true
+      require(pathname, options)
+    end
+
+    #
+    # Load up the ledger with a given set of paths.
+    #
+    def prime(*paths)
+      $LEDGER.prime(*paths)
+    end
+
+    #
+    # Go thru each library and make sure bin path is in path.
+    #
+    # @todo Should this be defined on Ledger?
+    #
+    def PATH()
+      path = []
+      list.each do |name|
+        lib = Library[name]
+        path << lib.bindir if lib.bindir?
+      end
+      path.join(RbConfig.windows_platform? ? ';' : ':')
+    end
+
+  end
+
+  extend Domain
+end

data/lib/library/errors.rb

@@ -0,0 +1,49 @@
+class Library
+
+  # Library LoadError is a subclass of Ruby's standard LoadError class.
+  #
+  class LoadError < ::LoadError
+
+    #
+    # Setup new LoadError instance.
+    #
+    def initialize(failed_path, library_name=nil)
+      super()
+
+      @failed_path  = failed_path
+      @library_name = library_name
+
+      if library_name
+        @message = "#{@library_name}:#{@failed_path}"
+      else
+        @message = failed_path
+      end
+
+      clean_backtrace
+    end
+
+    #
+    # Error message string.
+    #
+    def to_s
+      "LoadError: cannot load such file -- #{@message}"
+    end
+
+    #
+    # Take an +error+ and remove any mention of 'library' from it's backtrace.
+    # Will leaving the backtrace untouched if $DEBUG is set to true.
+    #
+    def clean_backtrace
+      return if ENV['debug'] || $DEBUG
+      bt = backtrace
+      bt = bt.reject{ |e| $RUBY_IGNORE_CALLERS.any?{ |re| re =~ e } } if bt
+      set_backtrace(bt)
+    end
+  end
+
+  # Library ValidationError is raised when library metadata is not conforming.
+  #
+  class ValidationError < ::RuntimeError
+  end
+
+end

data/lib/library/feature.rb

@@ -0,0 +1,207 @@
+class Library
+
+  # The Feature class represents a single file within a library.
+  #
+  # This class had been called `Script` until it occured to me that
+  # Ruby choose the name "feature" by it's use of tem in the global
+  # variable `$LOADED_FEATURES`.
+  #
+  class Feature
+
+    #
+    # Create a new Feature instance.
+    #
+    # @param library [Library]
+    #   The Library object to which the feature belongs.
+    #
+    # @param loadpath [String]
+    #   The loadpath within the library in which the feature resides.
+    #
+    # @param filename [String]
+    #   The file path of the feature relative to the loadpath.
+    #
+    # @param extension [Boolean]
+    #   File extension to append to the feature filename.
+    #
+    def initialize(library, loadpath, filename, extension=nil)
+      @library   = library
+      @loadpath  = loadpath
+      @filename  = filename
+      @extension = extension
+    end
+
+    #
+    # The Library object to which the file belongs.
+    #
+    attr_reader :library
+
+    #
+    # The loadpath within the library in which the feature resides.
+    #
+    # @return [Array] Load path relative to library location.
+    #
+    attr_reader :loadpath
+
+    #
+    # The file path of the feature relative to the loadpath.
+    #
+    attr_reader :filename
+
+    #
+    # Extension of feature file, e.g. `.rb`.
+    #
+    attr_reader :extension
+
+    #
+    # Name of the library to which the feature belongs.
+    #
+    # @return [String] name of the feature's library
+    #
+    def library_name
+      Library === library ? library.name : nil
+    end
+
+    #
+    #
+    #
+    def library_activate
+      library.activate if Library === library
+    end
+
+    #
+    # Library location.
+    #
+    # @return [String] location of library
+    #
+    def location
+      Library===library ? library.location : library
+    end
+
+    #
+    # Full path name of of feature.
+    #
+    # @return [String] expanded file path of feature 
+    #
+    def fullname
+      @fullname ||= ::File.join(location, loadpath, filename + (extension || ''))
+    end
+
+    #
+    # The path of the feature relative to the loadpath.
+    #
+    # @return [String] file path less location and loadpath
+    #
+    def localname
+      @localname ||= ::File.join(filename + (extension || ''))
+    end
+
+    #
+    # Acquire the feature --Roll's advanced require/load method.
+    #
+    # @return [true,false] true if loaded, false if it already has been loaded.
+    #
+    def acquire(options={})
+      if options[:load] # TODO: .delete(:load) ?
+        load(options)
+      else
+        require(options)
+      end
+    end
+
+    #
+    # Require feature.
+    #
+    # @return [true,false] true if loaded, false if it already has been loaded.
+    #
+    def require(options={})
+      if library_name == 'ruby' or library_name == 'site_ruby'
+        return false if $".include?(localname)  # ruby 1.8 does not use absolutes
+        $" << localname # ruby 1.8 does not use absolutes
+      end
+
+      Library.load_stack << self #library
+      begin
+        library_activate unless options[:force]
+        success = __require__(fullname)
+      #rescue ::LoadError => load_error  # TODO: deativeate this if $DEBUG ?
+      #  raise LoadError.new(localname, library_name)
+      ensure
+        Library.load_stack.pop
+      end
+      success
+    end
+
+    #
+    # Load feature.
+    #
+    # @return [true,false] true if loaded, false if it already has been loaded.
+    #
+    def load(options={})
+      if library_name == 'ruby' or library_name == 'site_ruby'
+        $" << localname # ruby 1.8 does not use absolutes
+      end
+
+      Library.load_stack << self #library
+      begin
+        library_activate unless options[:force]
+        success = __load__(fullname, options[:wrap])
+      #rescue ::LoadError => load_error
+      #  raise LoadError.new(localname, library_name)
+      ensure
+        Library.load_stack.pop
+      end
+      success
+    end
+
+    #
+    # Compare this features full path name to another using `#==`.
+    #
+    # @param [Feature,String] another feature or file path.
+    #
+    # @return [true,false] do the features represent the the same file
+    #
+    def ==(other)
+      fullname == other.to_s
+    end
+
+    #
+    # Same as `#==`.
+    #
+    # @param [Feature, String] another feature or file path.
+    #
+    # @return [true, false] if features are the same file
+    #
+    def eql?(other)
+      fullname == other.to_s
+    end
+
+    #
+    # Same a fullname.
+    #
+    # @return [String] expanded file path
+    #
+    def to_s
+      fullname
+    end
+
+    #
+    # Same a fullname.
+    #
+    # @return [String] expanded file path
+    #
+    def to_str
+      fullname
+    end
+
+    #
+    # Use `#fullname` to calculate a hash value for the feature file.
+    #
+    # @return [Integer] hash value
+    #
+    def hash
+      fullname.hash
+    end
+
+  end
+
+end