library 0.1.0

data/.ruby

@@ -0,0 +1,57 @@
+---
+source:
+- var
+authors:
+- name: trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2006'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: setup
+  version: 5.0+
+  groups:
+  - build
+  development: true
+- name: rubytest
+  groups:
+  - test
+  development: true
+- name: lemon
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git://github.com/rubyworks/library.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/library
+  code: http://github.com/rubyworks/library
+  mail: http://groups.google.com/groups/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2006-12-10'
+summary: Objectifying the Ruby Library
+title: Library
+version: 0.1.0
+name: library
+description: ! "The Library class encapsulates the essential nature \nof a Ruby library
+  --a location on disk from which\nscripts can be required."
+organization: rubyworks
+date: '2012-01-10'

data/.yardopts

@@ -0,0 +1,6 @@
+--title Library
+--protected
+--private
+lib/
+-
+[A-Z]*.*

data/COPYING.rdoc

@@ -0,0 +1,30 @@
+= COPYRIGHT NOTICES
+
+== Library
+
+Copyright:: (c) 2006 Rubyworks
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/library
+
+    Copyright (c) 2006 Rubyworks. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification, are
+    permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice, this list of
+          conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright notice, this list
+          of conditions and the following disclaimer in the documentation and/or other materials
+          provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+    BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+    BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/HISTORY.rdoc

@@ -0,0 +1,13 @@
+= RELEASE HISTORY
+
+== 0.1.0 / 2012-01-10
+
+The Library gem is a spin-off of the Rolls gem. The Library class
+is at the heart of Rolls, but is well defined enough to stand on its
+own as a separate supporting package. By having it as a separate
+project it becomes easier to focus on it's essential functionality.
+
+Changes:
+
+* Spin-off from Rolls and release.
+

data/README.md

@@ -0,0 +1,177 @@
+# RUBY LIBRARY
+
+<img src="" />
+
+[home](http://rubyworks.github.com/library) /
+[code](http://github.com/rubyworks/library)
+
+
+## DESCRIPTION
+
+Library is, as its name implies, the objectification of the Ruby library.
+Along with the Library Ledger, which keeps an indexed list of available
+libraries, a variety of useful features are bestowed to Ruby developers.
+
+* Work with libraries in an object-oriented manner.
+* Develop interdependent projects in real time without installing, linking or vendoring. 
+* Create isolated library environments based on project requirements.
+* Libraries can be stored anywhere. There is no special "home" path they must reside.
+* Serve gem installed libraries as easily as it serves developer's libraries.
+* Is the foundation of the Rolls gem, which provides a superset of library management functions.
+
+IMPORTANT: Presently gem installed packages can only be served if a `.ruby` file
+is part of the gem package. This should be fixed in the next release. To work
+around the `dotruby` gem can be used to generate a `.ruby` file for installed
+gems.
+
+
+## USAGE
+
+### Using the API
+
+The basics of the Library API are fairly simple. Given a location on disc
+that houses a Ruby library, e.g. `projects/hello`, a new Library instance
+can be created like any other object.
+
+    mylib = Library.new('projects/hello')
+
+With a library object in hand, we can require or load files from that library.
+
+    mylib.require 'world'
+
+Or look at information about the library.
+
+    mylib.name     #=> 'hello'
+    mylib.version  #=> '1.0.0'
+
+Crating a library object via`#new` gives us a one-off object. But to persist
+the library and make it available by name we can use `#add` instead.
+
+    Library.add('projects/hello')
+
+Or, delving down a bit deeper into the belly of system, one could simply
+feed the path to the master Ledger instance.
+
+    $LEDGER << 'projects/hello'
+
+Both have the same exact effect. Our library will then be available via 
+Library's various look-up methods. There are a few of these. One of these is
+the Kernel method `#library`.
+
+    library('hello')
+
+Another is `#[]` class method.
+
+    Library['hello']
+
+There are many other useful Library methods, see the API documentation
+for more details.
+
+### Using RUBYLIBS
+
+To use Library on a regular basis, add library paths to the `RUBYLIBS`
+environment variable. (NOTICE It is plural!!!)
+
+    export RUBYLIBS="~/workspace/ruby-projects"
+
+And add `-rubylibs` to the RUBYOPT environment variable.
+
+    export RUBYOPT="-rubylibs"
+
+You might already have `-rubygems` there, which is fine too.
+
+    export RUBYOPT="-rubylibs -rubygems"
+
+If you want access to project executables you will also need to append the
+project `bin` locations to the PATH environment variable.
+
+    export PATH="$PATH:$(ruby -e'Library::PATH()')"
+
+This will add the `bin` locations of the programs encompassed by your
+current `RUBYLIBS` setting.
+
+Of course, you will probably want to add these lines to your startup `.bashrc`
+file (or equivalent) so they are ready to go every time you bring up your
+shell console.
+
+### Preping Projects
+
+For a project to be usable via Library it must conform to common organizational
+conventions for a Ruby project and it should have a `.ruby` file.
+
+It is highly recommend that a project have a `.ruby` file although a `.gemspec`
+file can serve as a fallback if a `.ruby` file isn't found. But relying on a
+`.gemspec` is going to slow things down a fair bit. It also requires that
+the `dotruby` library be installed.
+
+To activate .gemspec support set the environment variable `RUBYLIBS_GEMSPEC=true`.
+
+See http://dotruby.github.com/dotruby for more information about `.ruby` files.
+
+
+### Autoload Caveat
+
+Ruby has a "bug" which prevents `#autoload` from using custom `#require`
+methods. So `#autoload` calls cannot make use of the Library setup. 
+This is not as significant as it might seem since `#autoload` is being
+deprecated as of Ruby 2.0. So it is best to discontinue it's use anyway.
+
+
+## LEARNING MORE
+
+The above provides a brief overview of using the Library gem. But there is
+more to it. To get a deeper understanding of the system its fullest extent,
+please visit http://rubyworks.github.org/library.
+
+
+## INSTALLATION
+
+### RubyGems Installation
+
+We strongly recommend installing Roller manually b/c Roller is a
+peer to RubyGems. However, the last we tested it, Roller could
+be install via Gems as a means of trying it out --though you won't
+get the full benefits of the system.
+
+    $ gem install library
+
+If you like Roller, then later you can uninstall the gem and
+do a proper manual install.
+
+
+### Manual Installation
+
+Manual installation is recommended for regular usage, since it
+can then be loaded without going through RubyGems.
+
+First you need a copy of the tarball (or zip) archive. You will
+find them [here](http://github.com/rubyworks/library/download).
+You will of course need to unpack the file. For example,
+
+    $ tar -xvzf library-0.1.0
+
+If you already have Ruby Setup installed on your system you can
+use it to install (See: http://rubyworks.github.com/setup). 
+
+    $ cd library-0.1.0
+    $ sudo setup.rb
+
+Otherwise, the package includes a copy of Ruby Setup that you can
+use.
+
+    $ cd library-0.1.0
+    $ sudo script/setup.
+
+On Windows, this last line will need to be 'ruby script/setup'.
+
+
+## COPYRIGHTS
+
+Ruby Library
+
+Copyright (c) 2006 Rubyworks
+
+Ruby Library is distributable in accordance with the **FreeBSD** license.
+
+See the COPYING.rdoc file details.
+

data/lib/library.rb

@@ -0,0 +1,532 @@
+require 'library/core_ext'
+require 'library/ledger'
+require 'library/errors'
+require 'library/metadata'
+require 'library/feature'
+require 'library/version'
+require 'library/domain'
+
+# Library class encapsulates a location on disc that contains a Ruby
+# project, with loadable features, of course.
+#
+class Library
+
+  #
+  # Library ledger.
+  #
+  $LEDGER = Ledger.new
+
+  #
+  # When loading files, the current library doing the loading is pushed
+  # on this stack, and then popped-off when it is finished.
+  #
+  $LOAD_STACK = []
+
+  #
+  #
+  #
+  $LOAD_CACHE = {}
+
+  # Dynamic link extension.
+  #DLEXT = '.' + ::RbConfig::CONFIG['DLEXT']
+
+  # TODO: Some extensions are platform specific --only add the ones needed
+  # for the current platform to SUFFIXES.
+
+  #
+  # Possible suffixes for feature files, that #require will try automatically.
+  #
+  SUFFIXES = ['.rb', '.rbw', '.so', '.bundle', '.dll', '.sl', '.jar'] #, '']
+
+  #
+  # Extensions glob, joins extensions with comma and wrap in curly brackets.
+  #
+  SUFFIX_PATTERN = "{#{SUFFIXES.join(',')}}"
+
+  #
+  # A shortcut for #instance.
+  #
+  # @return [Library,NilClass] The activated Library instance, or `nil` if not found.
+  #
+  def self.[](name, constraint=nil)
+    $LEDGER.activate(name, constraint) if $LEDGER.key?(name)
+  end
+
+  #
+  # Get an instance of a library by name, or name and version.
+  # Libraries are singleton, so once loaded the same object is
+  # always returned.
+  #
+  # @todo This method might be deprecated.
+  #
+  # @return [Library,NilClass] The activated Library instance, or `nil` if not found.
+  #
+  def self.instance(name, constraint=nil)
+    $LEDGER.activate(name, constraint) if $LEDGER.key?(name)
+  end
+
+  #
+  # Activate a library. Same as #instance but will raise and error if the
+  # library is not found. This can also take a block to yield on the library.
+  #
+  # @param [String] name
+  #   Name of library.
+  #
+  # @param [String] constraint
+  #   Valid version constraint.
+  #
+  # @raise [LoadError]
+  #   If library not found.
+  #
+  # @return [Library]
+  #   The activated Library object.
+  #
+  def self.activate(name, constraint=nil) #:yield:
+    library = $LEDGER.activate(name, constraint)
+    yield(library) if block_given?
+    library
+  end
+
+  #
+  # Like `#new`, but adds library to library ledger.
+  #
+  # @todo Better name for this method?
+  #
+  # @return [Library] The new library.
+  #
+  def self.add(location)
+    $LEDGER.add_location(location)
+
+    #library = new(location)
+    #$LEDGER.add_library(library)
+    #library
+  end
+
+  #
+  # New Library object.
+  #
+  # If data is given it must have `:name` and `:version`. It can
+  # also have `:loadpath`, `:date`, and `:omit`.
+  #
+  # @param location [String]
+  #   Expanded file path to library's root directory.
+  #
+  # @param metadata [Hash]
+  #   Overriding matadata (to circumvent loading it from `.ruby` file).
+  #
+  def initialize(location, metadata={})
+    raise TypeError, "not a directory - #{location}" unless File.directory?(location)
+
+    @location = location
+    @metadata = Metadata.new(location, metadata)
+
+    raise ValidationError, "Non-conforming library (missing name) -- `#{location}'" unless name
+    raise ValidationError, "Non-conforming library (missing version) -- `#{location}'" unless version
+  end
+
+  #
+  # Activate a library.
+  #
+  # @return [true,false] Has the library has been activated?
+  #
+  def activate
+    current = $LEDGER[name]
+
+    if Library === current
+      raise VersionConflict.new(self, current) if current != self
+    else
+      ## NOTE: we are only doing this for the sake of autoload
+      ## which does not honor a customized require method.
+      #if Library.autoload_hack?
+      #  absolute_loadpath.each do |path|
+      #    $LOAD_PATH.unshift(path)
+      #  end
+      #end
+      $LEDGER[name] = self
+    end
+
+    # TODO: activate runtime requirements?
+    #verify
+  end
+
+  #
+  # Is this library active in global ledger?
+  #
+  def active?
+    $LEDGER[name] == self
+  end
+
+  #
+  # Location of library files on disc.
+  #
+  def location
+    @location
+  end
+
+  #
+  # Access to library metadata. Metadata is gathered from
+  # the `.ruby` file or a `.gemspec` file.
+  #
+  # @return [Metadata] metadata object
+  #
+  def metadata
+    @metadata
+  end
+
+  #
+  # Library's "unixname".
+  #
+  # @return [String] name of library
+  #
+  def name
+    @name ||= metadata.name
+  end
+
+  #
+  # Library's version number.
+  #
+  # @return [VersionNumber] version number
+  #
+  def version
+    @version ||= metadata.version
+  end
+
+  #
+  # Library's internal load path(s). This will default to `['lib']`
+  # if not otherwise given.
+  #
+  # @return [Array] list of load paths
+  #
+  def load_path
+    metadata.load_path
+  end
+
+  alias_method :loadpath, :load_path
+
+  #
+  # Release date.
+  #
+  # @return [Time] library's release date
+  #
+  def date
+    metadata.date
+  end
+
+  #
+  # Alias for +#date+.
+  #
+  alias_method :released, :date
+
+  #
+  # Library's requirements. Note that in gemspec terminology these are
+  # called *dependencies*.
+  #
+  # @return [Array] list of requirements
+  #
+  def requirements
+    metadata.requirements
+  end
+
+  #
+  # Runtime requirements.
+  #
+  # @return [Array] list of runtime requirements
+  #
+  def runtime_requirements
+    requirements.select{ |req| !req['development'] }
+  end
+
+  #
+  # Omit library form ledger?
+  #
+  # @return [Boolean] if true, omit library from ledger
+  #
+  def omit
+    @metadata.omit
+  end
+
+  #
+  # Same as `#omit`.
+  #
+  alias_method :omit?, :omit
+
+  #
+  # Returns a list of load paths expand to full path names.
+  #
+  # @return [Array<String>] list of expanded load paths
+  #
+  def absolute_loadpath
+    loadpath.map{ |lp| ::File.join(location, lp) }
+  end
+
+  #
+  # Take requirements and open them. This will reveal any
+  # version conflicts or missing dependencies.
+  #
+  # @param [Boolean] development
+  #   Include development dependencies?
+  #
+  def verify(development=false)
+    reqs = development ? requirements : runtime_requirements
+    reqs.each do |req|
+      name, constraint = req['name'], req['version']
+      Library.open(name, constraint)
+    end
+  end
+
+  #
+  # Does a library contain a relative +file+ within it's loadpath.
+  # If so return the libary file object for it, otherwise +false+.
+  #
+  # Note that this method was designed to maximize speed.
+  #
+  # @param [#to_s] file
+  #   The relative pathname of the file to find.
+  #
+  # @param [Hash] options
+  #   The Hash of optional settings to adjust search behavior.
+  #
+  # @option options [Boolean] :suffix
+  #   Automatically try standard extensions if pathname has none.
+  #
+  # @option options [Boolean] :legacy
+  #   (deprecated) Do not match within library's +name+ directory, eg. `lib/foo/*`.
+  #
+  # @return [Feature,nil] The feature, if found.
+  #
+  def find(pathname, options={})
+    main   = options[:main]
+    #legacy = options[:legacy]
+    suffix = options[:suffix] || options[:suffix].nil?
+    #suffix = false if options[:load]
+    suffix = false if SUFFIXES.include?(::File.extname(pathname))
+    if suffix
+      loadpath.each do |lpath|
+        SUFFIXES.each do |ext|
+          f = ::File.join(location, lpath, pathname + ext)
+          return feature(lpath, pathname, ext) if ::File.file?(f)
+        end
+      end #unless legacy
+      legacy_loadpath.each do |lpath|
+        SUFFIXES.each do |ext|
+          f = ::File.join(location, lpath, pathname + ext)
+          return feature(lpath, pathname, ext) if ::File.file?(f)
+        end
+      end unless main
+    else
+      loadpath.each do |lpath|
+        f = ::File.join(location, lpath, pathname)
+        return feature(lpath, pathname) if ::File.file?(f)
+      end #unless legacy
+      legacy_loadpath.each do |lpath|
+        f = ::File.join(location, lpath, pathname)        
+        return feature(lpath, pathname) if ::File.file?(f)
+      end unless main
+    end
+    nil
+  end
+
+  #
+  # Alias for #find.
+  #
+  alias_method :include?, :find
+
+  #
+  #
+  #
+  def legacy?
+    !legacy_loadpath.empty?
+  end
+
+  #
+  # What is `legacy_loadpath`? Well, library doesn't require you to put your
+  # library's scripts in a named lib path, e.g. `lib/foo/`. Instead one can
+  # just put them in `lib/` b/c Library keeps things indexed by honest to
+  # goodness library names. The `legacy_path` then is used to handle these
+  # old style paths along with the new.
+  #
+  def legacy_loadpath
+    @legacy_loadpath ||= (
+      path = []
+      loadpath.each do |lp|
+        llp = File.join(lp, name)
+        dir = File.join(location, llp)
+        path << llp if File.directory?(dir)
+      end
+      path
+    )
+  end
+
+  #
+  # Create a new Feature object from +lpath+, +pathname+ and +ext+.
+  #
+  def feature(lpath, pathname, ext=nil)
+    Feature.new(self, lpath, pathname, ext)
+  end
+
+  #
+  # Requre feature from library.
+  #
+  def require(pathname, options={})
+    if feature = find(pathname, options)
+      feature.require(options)
+    else
+      raise LoadError.new(path, name)  # TODO: silently?
+    end
+  end
+
+  #
+  # Load feature form library.
+  #
+  def load(pathname, options={})
+    #options[:load] = true
+    if feature = find(pathname, options)
+      feature.load(options)
+    else
+      raise LoadError.new(pathname, self.name)
+    end
+  end
+
+  #
+  # Inspect library instance.
+  #
+  def inspect
+    if version
+      %[#<Library #{name}/#{version} @location="#{location}">]
+    else
+      %[#<Library #{name} @location="#{location}">]
+    end
+  end
+
+  #
+  # Same as #inspect.
+  #
+  def to_s
+    inspect
+  end
+
+  #
+  # Compare by version.
+  #
+  def <=>(other)
+    version <=> other.version
+  end
+
+  #
+  # Return default feature. This is the feature that has same name as
+  # the library itself.
+  #
+  def default
+    @default ||= find(name, :main=>true)
+  end
+
+  #--
+  #    # List of subdirectories that are searched when loading.
+  #    #--
+  #    # This defualts to ['lib/{name}', 'lib']. The first entry is
+  #    # usually proper location; the latter is added for default
+  #    # compatability with the traditional require system.
+  #    #++
+  #    def libdir
+  #      loadpath.map{ |path| ::File.join(location, path) }
+  #    end
+  #
+  #    # Does the library have any lib directories?
+  #    def libdir?
+  #      lib.any?{ |d| ::File.directory?(d) }
+  #    end
+  #++
+
+  #
+  # Location of executable. This is alwasy bin/. This is a fixed
+  # convention, unlike lib/ which needs to be more flexable.
+  #
+  def bindir
+    ::File.join(location, 'bin')
+  end
+
+  #
+  # Is there a `bin/` location?
+  #
+  def bindir? 
+    ::File.exist?(bindir)
+  end
+
+  #
+  # Location of library system configuration files.
+  # This is alwasy the `etc/` directory.
+  #
+  def confdir
+    ::File.join(location, 'etc')
+  end
+
+  #
+  # Is there a `etc/` location?
+  #
+  def confdir?
+    ::File.exist?(confdir)
+  end
+
+  # Location of library shared data directory.
+  # This is always the `data/` directory.
+  def datadir
+    ::File.join(location, 'data')
+  end
+
+  # Is there a `data/` location?
+  def datadir?
+    ::File.exist?(datadir)
+  end
+
+  #
+  #def to_rb
+  #  to_h.inspect
+  #end
+
+  #
+  # Convert to hash.
+  #
+  # @return [Hash] The library metadata in a hash.
+  #
+  def to_h
+    {
+      :location     => location,
+      :name         => name,
+      :version      => version.to_s,
+      :loadpath     => loadpath,
+      :date         => date.to_s,
+      :requirements => requirements
+    }
+  end
+
+  module ::Kernel
+    #
+    # In which library is the current file participating?
+    #
+    # @return [Library] The library currently loading features.
+    #
+    def __LIBRARY__
+      $LOAD_STACK.last.library
+    end
+
+    #
+    # Activate a library, same as `Library.instance` but will raise and error
+    # if the library is not found. This can also take a block to yield on the
+    # library.
+    #
+    # @param name [String]
+    #   The library's name.
+    #
+    # @param constraint [String]
+    #   A valid version constraint.
+    #
+    # @return [Library] The Library instance.
+    #
+    def library(name, constraint=nil, &block) #:yield:
+      Library.activate(name, constraint, &block)
+    end
+
+    module_function :library
+  end
+
+end