root 0.0.1

data/History

@@ -0,0 +1,3 @@
+== 0.0.1 / 2009-04-03
+
+Initial release, a port of Tap::Root.

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009, Regents of the University of Colorado.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,14 @@
+= Root[http://tap.rubyforge.org/root]
+
+== Installation
+
+Root is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+
+  % gem install root
+
+== Info 
+
+Copyright (c) 2009, Regents of the University of Colorado.
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
+Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+License:: {MIT-Style}[link:files/MIT-LICENSE.html]

data/lib/root.rb

@@ -0,0 +1,268 @@
+require 'configurable'
+require 'root/utils'
+
+# Root allows you to define a root directory and alias relative paths, so
+# that you can conceptualize what filepaths you need without predefining the
+# full filepaths.  Root also simplifies operations on filepaths.
+#
+#   # define a root directory with aliased relative paths
+#   r = Root.new '/root_dir', :input => 'in', :output => 'out'
+#  
+#   # work with aliases
+#   r[:input]                                   # => '/root_dir/in'
+#   r[:output]                                  # => '/root_dir/out'
+#   r['implicit']                               # => '/root_dir/implicit'
+#
+#   # expanded paths are returned unchanged
+#   r[File.expand_path('expanded')]             # => File.expand_path('expanded')
+#
+#   # work with filepaths
+#   fp = r.filepath(:input, 'path/to/file.txt') # => '/root_dir/in/path/to/file.txt'
+#   r.relative_filepath(:input, fp)             # => 'path/to/file.txt'
+#   r.translate(fp, :input, :output)            # => '/root_dir/out/path/to/file.txt'
+#  
+#   # version filepaths
+#   r.version('path/to/config.yml', 1.0)        # => 'path/to/config-1.0.yml'
+#   r.increment('path/to/config-1.0.yml', 0.1)  # => 'path/to/config-1.1.yml'
+#   r.deversion('path/to/config-1.1.yml')       # => ['path/to/config.yml', "1.1"]
+#
+#   # absolute paths can also be aliased 
+#   r[:abs, true] = "/absolute/path"      
+#   r.filepath(:abs, "to", "file.txt")          # => '/absolute/path/to/file.txt'
+#
+# By default, Roots are initialized to the present working directory
+# (Dir.pwd).
+#
+#--
+# === Implementation Notes
+#
+# Internally Root expands and stores all aliased paths in the 'paths' hash.
+# Expanding paths ensures they remain constant even when the present working
+# directory (Dir.pwd) changes.
+#
+# Root keeps a separate 'relative_paths' hash mapping aliases to their
+# relative paths. This hash allow reassignment if and when the root directory
+# changes.  By contrast, there is no separate data structure storing the
+# absolute paths. An absolute path thus has an alias in 'paths' but not
+# 'relative_paths', whereas relative paths have aliases in both.
+#
+# These features may be important to note when subclassing Root:
+# - root and all filepaths in 'paths' are expanded
+# - relative paths are stored in 'relative_paths'
+# - absolute paths are present in 'paths' but not in 'relative_paths'
+#
+class Root
+  include Configurable
+  include Utils
+  
+  # The root directory.
+  config_attr(:root, '.', :writer => false)
+  
+  # A hash of (alias, relative path) pairs for aliased paths relative
+  # to root.
+  config_attr(:relative_paths, {}, :writer => false)
+  
+  # A hash of (alias, relative path) pairs for aliased absolute paths.
+  config_attr(:absolute_paths, {}, :reader => false, :writer => false)
+  
+  # A hash of (alias, expanded path) pairs for expanded relative and
+  # absolute paths.
+  attr_reader :paths
+  
+  # The filesystem root, inferred from self.root
+  # (ex '/' on *nix or something like 'C:/' on Windows).
+  attr_reader :path_root
+  
+  # Creates a new Root with the given root directory, aliased relative paths
+  # and absolute paths.  By default root is the present working directory 
+  # and no aliased relative or absolute paths are specified.  
+  def initialize(root=Dir.pwd, relative_paths={}, absolute_paths={})
+    assign_paths(root, relative_paths, absolute_paths)
+    @config = DelegateHash.new(self.class.configurations, {}, self)
+  end
+  
+  # Sets the root directory. All paths are reassigned accordingly.
+  def root=(path)
+    assign_paths(path, relative_paths, absolute_paths)
+  end
+
+  # Sets the relative_paths to those provided. 'root' and :root are reserved
+  # aliases and cannot be set using this method (use root= instead).
+  #
+  #   r = Root.new
+  #   r['alt']                            # => File.join(r.root, 'alt')
+  #   r.relative_paths = {'alt' => 'dir'}
+  #   r['alt']                            # => File.join(r.root, 'dir')
+  #
+  def relative_paths=(paths)
+    paths = Validation::HASH[paths]
+    assign_paths(root, paths, absolute_paths)
+  end
+  
+  # Sets the absolute paths to those provided. 'root' and :root are reserved
+  # aliases and cannot be set using this method (use root= instead).
+  #
+  #   r = Root.new
+  #   r['abs']                            # => File.join(r.root, 'abs')
+  #   r.absolute_paths = {'abs' => '/path/to/dir'}
+  #   r['abs']                            # => '/path/to/dir'
+  #
+  def absolute_paths=(paths)
+    paths = Validation::HASH[paths]
+    assign_paths(root, relative_paths, paths)
+  end
+  
+  # Returns the absolute paths registered with self.
+  def absolute_paths
+    abs_paths = {}
+    paths.each do |als, path|
+      unless relative_paths.include?(als) || als.to_s == 'root'
+        abs_paths[als] = path
+      end
+    end
+    abs_paths
+  end
+
+  # Sets an alias for the path relative to the root directory.  The aliases
+  # 'root' and :root cannot be set with this method (use root= instead).
+  # Absolute filepaths can be set using the second syntax.  
+  #
+  #   r = Root.new '/root_dir'
+  #   r[:dir] = 'path/to/dir'
+  #   r[:dir]                             # => '/root_dir/path/to/dir'
+  #
+  #   r[:abs, true] = '/abs/path/to/dir'  
+  #   r[:abs]                             # => '/abs/path/to/dir'
+  # 
+  #--
+  # Implementation Note:
+  #
+  # The syntax for setting an absolute filepath requires an odd use []=.  
+  # In fact the method recieves the arguments (:dir, true, '/abs/path/to/dir') 
+  # rather than (:dir, '/abs/path/to/dir', true), meaning that internally path 
+  # and absolute are switched when setting an absolute filepath.
+  #
+  def []=(als, path, absolute=false)
+    raise ArgumentError, "the alias #{als.inspect} is reserved" if als.to_s == 'root'
+
+    # switch the paths if absolute was provided
+    unless absolute == false
+      switch = path
+      path = absolute
+      absolute = switch
+    end
+    
+    case
+    when path.nil? 
+      @relative_paths.delete(als)
+      @paths.delete(als)
+    when absolute
+      @relative_paths.delete(als)
+      @paths[als] = File.expand_path(path)
+    else
+      @relative_paths[als] = path
+      @paths[als] = File.expand_path(File.join(root, path))
+    end 
+  end
+
+  # Returns the expanded path for the specified alias.  If the alias has not
+  # been set, then the path is inferred to be 'root/als'.  Expanded paths
+  # are returned directly.
+  #
+  #   r = Root.new '/root_dir', :dir => 'path/to/dir'
+  #   r[:dir]                             # => '/root_dir/path/to/dir'
+  #
+  #   r.path_root                         # => '/'
+  #   r['relative/path']                  # => '/root_dir/relative/path'
+  #   r['/expanded/path']                 # => '/expanded/path'
+  #
+  def [](als)
+    path = self.paths[als] 
+    return path unless path == nil
+    
+    als = als.to_s 
+    expanded?(als) ? als : File.expand_path(File.join(root, als))
+  end
+  
+  # Resolves the specified alias, joins the paths together, and expands the
+  # resulting filepath.
+  def filepath(als, *paths)
+    File.expand_path(File.join(self[als], *paths))
+  end
+
+  # Retrieves the filepath relative to the path of the specified alias.  
+  def relative_filepath(als, path)
+    super(self[als], path)
+  end
+  
+  # Same as filepath but raises an error if the result is not a subpath of
+  # the aliased directory.
+  def subpath(als, *paths)
+    dir = self[als]
+    path = filepath(als, *paths)
+    
+    if path.rindex(dir, 0) != 0
+      raise "not a subpath: #{path} (#{dir})"
+    end
+    
+    path
+  end
+
+  # Generates a filepath translated from the aliased source dir to the
+  # aliased target dir. Raises an error if the filepath is not relative
+  # to the source dir.
+  # 
+  #   r = Root.new '/root_dir'
+  #   path = r.filepath(:in, 'path/to/file.txt')    # => '/root_dir/in/path/to/file.txt'
+  #   r.translate(path, :in, :out)                  # => '/root_dir/out/path/to/file.txt'
+  #
+  def translate(path, source_als, target_als)
+    super(path, self[source_als], self[target_als])
+  end
+
+  # Lists all files along the aliased path matching the input patterns.
+  # Patterns should join with the aliased path make valid globs for 
+  # Dir.glob.  If no patterns are specified, glob returns all paths
+  # matching 'als/**/*'.
+  def glob(als, *patterns)
+    patterns << "**/*" if patterns.empty?
+    patterns.collect! {|pattern| filepath(als, pattern)}
+    super(*patterns)
+  end
+
+  # Lists all versions of path in the aliased dir matching the version
+  # patterns. If no patterns are specified, then all versions of path
+  # will be returned.
+  def vglob(als, path, *vpatterns)
+    super(filepath(als, path), *vpatterns)
+  end
+  
+  # Changes pwd to the specified directory using Root.chdir.
+  def chdir(als, mkdir=false, &block)
+    super(self[als], mkdir, &block)
+  end
+  
+  # Constructs a path from the inputs (using filepath) and prepares it using
+  # Root.prepare.  Returns the path.
+  def prepare(als, *paths, &block)
+    super(filepath(als, *paths), &block)
+  end
+  
+  private
+
+  # reassigns all paths with the input root, relative_paths, and absolute_paths
+  def assign_paths(root, relative_paths, absolute_paths)
+    @root = File.expand_path(root)
+    @relative_paths = {}
+    @paths = {'root' => @root, :root => @root}
+
+    @path_root = File.dirname(@root)
+    while @path_root != (parent = File.dirname(@path_root))
+      @path_root = parent 
+    end
+  
+    relative_paths.each_pair {|dir, path| self[dir] = path }
+    absolute_paths.each_pair {|dir, path| self[dir, true] = path }
+  end  
+
+end

data/lib/root/constant.rb

@@ -0,0 +1,140 @@
+require 'root/string_ext'
+
+class Root
+  
+  # A Constant serves as a placeholder for an actual constant, sort of like 
+  # autoload.  Use the constantize method to retrieve the actual constant; if
+  # it doesn't exist, constantize requires require_path and tries again.
+  #
+  #   Object.const_defined?(:Net)                      # => false
+  #   $".include?('net/http')                          # => false
+  #
+  #   http = Constant.new('Net::HTTP', 'net/http')
+  #   http.constantize                                 # => Net::HTTP
+  #   $".include?('net/http')                          # => true
+  #
+  class Constant
+    class << self
+      
+      # Tries to find a declared constant under base with the specified
+      # const_name.  When a constant is missing, constantize yields the
+      # current base and any non-existant constant names the block, if given,
+      # or raises a NameError.  The block is expected to return the desired
+      # constant; in the example 'Non::Existant' is effectively mapping to
+      # ConstName.
+      #
+      #   module ConstName; end
+      #
+      #   Constant.constantize('ConstName')                     # => ConstName
+      #   Constant.constantize('Non::Existant') { ConstName }   # => ConstName
+      #
+      def constantize(const_name, base=Object) # :yields: base, missing_const_names
+        unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ const_name
+          raise NameError, "#{const_name.inspect} is not a valid constant name!"
+        end
+        
+        constants = $1.split(/::/)
+        while !constants.empty?
+          unless const_is_defined?(base, constants[0])
+            if block_given? 
+              return yield(base, constants)
+            else
+              raise NameError.new("uninitialized constant #{const_name}", constants[0]) 
+            end
+          end
+          base = base.const_get(constants.shift)
+        end
+        base
+      end
+      
+      private
+      
+      # helper method.  Determines if a constant named name is defined in
+      # const.  The implementation (annoyingly) has to be different for ruby
+      # 1.9 due to changes in the API.
+      case RUBY_VERSION
+      when /^1.9/
+        def const_is_defined?(const, name) # :nodoc:
+          const.const_defined?(name, false)
+        end
+      else
+        def const_is_defined?(const, name) # :nodoc:
+          const.const_defined?(name)
+        end
+      end
+    end
+    
+    # The constant name
+    attr_reader :name
+    
+    # The path to load to initialize a missing constant
+    attr_reader :require_path
+    
+    # Initializes a new Constant with the specified constant name and
+    # require_path.  The name should be a valid constant name.
+    def initialize(name, require_path=nil)
+      @name = name
+      @require_path = require_path
+    end
+    
+    # Returns the underscored name.
+    def path
+      @path ||= name.underscore
+    end
+    
+    # Returns the basename of path.
+    def basename
+      @basename ||= File.basename(path)
+    end
+    
+    # Returns the path, minus the basename of path. 
+    def dirname
+      @dirname ||= (dirname = File.dirname(path)) == "." ? "" : dirname
+    end
+    
+    # Returns the name of the constant, minus nesting.
+    def const_name
+      @const_name ||= (name =~ /.*::(.*)$/ ? $1 : name)
+    end
+    
+    # Returns the nesting constants of name.
+    def nesting
+      @nesting ||= (name =~ /(.*)::.*$/ ? $1 : '')
+    end
+    
+    # Returns the number of constants in nesting.
+    def nesting_depth
+      @nesting_depth ||= nesting.split(/::/).length
+    end
+
+    # Returns the Lazydoc document for require_path.
+    def document
+      require_path ? Lazydoc[require_path] : nil 
+    end
+    
+    # True if another is a Constant with the same name
+    # and require_path as self.
+    def ==(another)
+      another.kind_of?(Constant) && 
+      another.name == self.name &&
+      another.require_path == self.require_path
+    end
+    
+    # Looks up and returns the constant indicated by name. If the constant
+    # cannot be found, constantize requires require_path and tries again.  
+    #
+    # Raises a NameError if the constant cannot be found.
+    def constantize
+      Constant.constantize(name) do
+        require require_path if require_path
+        Constant.constantize(name)
+      end
+    end
+    
+    # Returns a string like:
+    #   "#<Root::Constant:object_id Const::Name (require_path)>"
+    def inspect
+      "#<#{self.class}:#{object_id} #{name}#{@require_path == nil ? "" : " (#{@require_path})"}>"
+    end
+  end
+end