relative 1.0.0

data/History.txt

@@ -0,0 +1,8 @@
+=== 1.0.0 / 2008-06-25
+Initial release of relative.  This release includes support for:
+* constructing pathnames relative to the caller
+  (File.expand_path_relative_to_caller and
+  Pathname#expand_path_relative_to_caller)
+* Passing pathnames relative to the caller into standard I/O methods
+  (PathRelativeToCaller)
+* requiring files relative to the caller (Kernel#require_relative)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Designing Patterns
+
+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/Manifest.txt

@@ -0,0 +1,14 @@
+Manifest.txt
+LICENSE
+History.txt
+README.txt
+Rakefile
+lib/relative.rb
+lib/relative/file.rb
+lib/relative/kernel.rb
+lib/relative/pathname.rb
+lib/relative/pathrelativetocaller.rb
+test/test_file.rb
+test/test_kernel.rb
+test/test_pathname.rb
+test/test_pathrelativetocaller.rb

data/README.txt

@@ -0,0 +1,117 @@
+= relative
+* Project Page: http://rubyforge.org/projects/relative/
+* Documentation: http://relative.rubyforge.org/
+
+== DESCRIPTION:
+The relative library enhances Ruby's core and standard libraries to support
+naming, opening, and reading files relative to the Ruby file currently being
+interpreted (the contents of the __ FILE __ identifier). This functionality is
+especially useful in embedded Ruby (eruby, erb, erubis, etc.) where absolute
+paths or paths relative to the interpreter's current working directory are
+problematic (due to file system structures and working directories
+varying across platforms and web servers).
+
+== FEATURES
+* The File.expand_path_relative_to_caller class method that
+  expands paths relative to the calling file (analogous to File.expand_path,
+  which expands paths relative to the interpreter's current working directory)
+* The Kernel#require_relative instance method that allows Ruby
+  modules to be imported with paths relative to the calling file
+* The Pathname#expand_path_relative_to_caller instance method that
+  returns a new Pathname object created by expanding the receiver Pathname
+  relative to the calling file (analogous to Pathname.expand_path, which
+  expands a Pathname relative to the interpreter's current working directory)
+* The PathRelativeToCaller class, instances of which are constructed with a
+  path relative to the calling file and can be passed into all of the
+  core and standard Ruby I/O methods (IO.read, File.open, etc).
+  A PathRelativeToCaller instance expands the relative path with which it is
+  initialized and evaluates to the absolute path in I/O methods;
+  it makes the relative path accessible through an attribute accessor,
+  however.
+
+== PROBLEMS:
+None (known).
+
+== SYNOPSIS:
+======+examples/example.rb+:
+ #!/usr/bin/env ruby
+ require 'rubygems'
+ require 'relative'
+ 
+ relative_path = "../Rakefile"
+ 
+ print("====================================================================\n")
+ print("The absolute path of #{relative_path} (relative to #{__FILE__}):\n")
+ print("#{File.expand_path_relative_to_caller(relative_path)}\n")
+ print("====================================================================\n")
+ print("The Pathname of #{relative_path} (relative to #{__FILE__}):\n")
+ print("#{Pathname.new(relative_path).expand_path_relative_to_caller()}\n")
+ print("====================================================================\n")
+ print("The contents of #{relative_path} (relative to #{__FILE__}):\n")
+ print("#{IO.read(PathRelativeToCaller.new(relative_path))}")
+ print("====================================================================\n")
+
+
+This example shows the use of File.expand_path_relative_to_caller to expand
++../Rakefile+ relative to the path of the example script,
++examples/example.rb+.  It also illustrates how
+Pathname#expand_path_relative_to_caller can return an expansion of
+the receiver Pathname (+../Rakefile+) relative to +examples/example.rb+.
+Finally, it demonstrates that a PathRelativeToCaller object can be passed
+into ordinary File and IO methods, within which it will evaluate to an
+absolute expansion of +../Rakefile+ (the path with which it was initialized)
+relative to +examples/example.rb+ (the source file that constructed the
+PathRelativeToCaller instance).
+
+== REQUIREMENTS:
+Hoe is required but only for running the tests.
+
+== INSTALL:
+ sudo gem install relative
+
+== AUTHORS:
+=== Designing Patterns
+* Homepage: http://www.designingpatterns.com
+* Blogs: http://blogs.designingpatterns.com
+
+== SUPPORT
+Please post questions, concerns, or requests for enhancement to the forums on
+the project page.  Alternatively, direct contact information for
+Designing Patterns can be found on the project page for this gem.
+
+== ENHANCEMENTS
+Please feel free to contact us with any ideas; we will try our best to
+enhance the software and respond to user requests.  Of course, we are more
+likely to work on a particular enhancement if we know that there are users
+who want it.  Designing Patterns provides contracting and consulting services,
+so if there is an enhancement that *must* get done (and in a specified time
+frame), please inquire about retaining our services!
+
+== LICENSE:
+The license text can be found in the +LICENSE+ file at the root of the
+distribution.
+
+This  package is licensed with an MIT license:
+
+Copyright (c) 2008 Designing Patterns
+
+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.
+
+== SHARE AND ENJOY!

data/Rakefile

@@ -0,0 +1,15 @@
+# -*- ruby -*-
+
+$LOAD_PATH.unshift("lib")
+
+require 'rubygems'
+require 'hoe'
+
+$stderr = STDERR
+
+Hoe.new('relative', "1.0.0") do |p|
+  p.remote_rdoc_dir = ''
+  p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
+end
+
+# vim: syntax=Ruby

data/lib/relative.rb

@@ -0,0 +1,25 @@
+#
+# Require the 'relative' components corresponding to Ruby core
+# libraries.
+#
+require 'relative/file'
+require 'relative/kernel'
+require 'relative/pathrelativetocaller'
+
+#
+# Only require the 'relative' components corresponding to Ruby
+# standard libraries if the associated standard library module is
+# loaded.  This trick allows
+#  require 'relative'
+# to extend the core and standard libraries but not to include any
+# ununsed standard libraries.
+#
+# autoload does not work as one might expect...  if the module already is
+# defined, autoload will *not* load the files.  So, directly load the files if
+# the module already is defined.
+#
+if(!Object.const_defined?(:Pathname))
+  autoload :Pathname, 'relative/pathname'
+else
+  require 'relative/pathname'
+end

data/lib/relative/file.rb

@@ -0,0 +1,49 @@
+class File
+  #
+  # Compute this information (the directory containing the relative gem's
+  # source code) when this file is loaded; this information is used within
+  # File#expand_path_relative_to_caller.
+  #
+  RELATIVE_GEM_SOURCE_DIR = File.expand_path(File.dirname(__FILE__)) #:nodoc:
+
+  # 
+  # ====Description:
+  # This method returns an absolute expansion of file_name, relative to
+  # the caller's source file.  Note that this method is a no-op if
+  # file_name is absolute.
+  #
+  # ====Examples:
+  # If the caller's source file is:
+  #  /usr/bin/scripts/print_file.rb
+  # then
+  #  File.expand_path_relative_to_caller("config/print_file.cfg")
+  # will return
+  #  "/usr/bin/scripts/config/print_file.cfg"
+  # 
+  # ====Parameters:
+  # [file_name]
+  #      A file system path relative to the calling file
+  # 
+  # ====Returns:
+  # An absolute expansion of file_name, relative to the caller's source file.
+  # 
+  def self.expand_path_relative_to_caller(file_name)
+    caller_stack = caller(1) # Start the call stack at the caller
+    external_caller_file_dir = caller_stack.each do |caller_stack_frame|
+      caller_file_name = caller_stack_frame.split(":")[0]
+      caller_file_dir = File.expand_path(File.dirname(caller_file_name))
+      
+      #
+      # Treat callers inside the relative gem differently from those
+      # outside the relative gem.  In particular, assume that
+      # callers within the relative gem want paths expanded relative
+      # to *their* callers.
+      #
+      if(caller_file_dir != RELATIVE_GEM_SOURCE_DIR)
+        break caller_file_dir
+      end
+    end
+    
+    return File.expand_path(file_name, external_caller_file_dir)
+  end
+end

data/lib/relative/kernel.rb

@@ -0,0 +1,30 @@
+require 'relative/file'
+
+module Kernel
+  #
+  # Only implement require_relative if it is not implemented
+  # already.
+  #
+  if(!Kernel.method_defined?(:require_relative))
+    # 
+    # ====Description:
+    # This method loads the Ruby code contained in file_name, where
+    # file_name is expanded relative to the calling source file.
+    # Basically, this method is exactly the same as the require method
+    # except that it interprets its argument relative to the calling
+    # source file rather than to the interpreter's current working
+    # directory.  An equivalent require_relative method will be
+    # provided as part of the core Ruby 1.9 distribution (see
+    # http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/16356;
+    # if a require_relative already is defined, this method will not
+    # override the existing implementation).
+    # 
+    # ====Parameters:
+    # [file_name]
+    #      The file system path of the Ruby source file to load
+    # 
+    def require_relative(file_name)
+      require(File.expand_path_relative_to_caller(file_name))
+    end
+  end
+end

data/lib/relative/pathname.rb

@@ -0,0 +1,31 @@
+require 'relative/file'
+
+require 'pathname'
+
+class Pathname
+  # 
+  # ====Description:
+  # This method returns an absolute expansion of self, relative to
+  # the caller's source file.  Note that this method is a no-op if
+  # self is an absolute Pathname.
+  #
+  # ====Examples:
+  # If the caller's source file is:
+  #  /usr/bin/scripts/print_file.rb
+  # then
+  #  relative_path = Pathname.new("config/print_file.cfg")
+  #  absolute_path = relative_path.expand_path_relative_to_caller()
+  # will make absolute_path equal to:
+  #  Pathname.new("/usr/bin/scripts/config/print_file.cfg")
+  # 
+  # ====Parameters:
+  # [file_name]
+  #      A file system path relative to the calling file
+  # 
+  # ====Returns:
+  # An absolute expansion of self, relative to the caller's source file.
+  # 
+  def expand_path_relative_to_caller
+    return Pathname.new(File.expand_path_relative_to_caller(to_s()))
+  end
+end

data/lib/relative/pathrelativetocaller.rb

@@ -0,0 +1,77 @@
+require 'relative/file'
+
+#
+# An instance of this class represents a file path relative to the
+# source file that created the instance.
+#
+# For example, if the caller's source file is:
+#  /usr/bin/scripts/print_file.rb
+# then
+#  path = PathRelativeToCaller.new("config/print_file.cfg")
+#  puts path.relative
+#  puts path.absolute
+# will output:
+#  config/print_file.cfg
+#  /usr/bin/scripts/config/print_file.cfg
+#
+# PathRelativeToCaller instances evaluate to their absolute path expansions
+# in core and standard I/O methods like File.open and IO.read, allowing
+# code like this:
+#  IO.read(PathRelativeToCaller.new("config/print_file.cfg"))
+#
+class PathRelativeToCaller
+  #
+  # The path relative to the code that created the PathNameRelativeToCaller
+  # instance (the argument to new).
+  #
+  attr_reader :relative
+
+  #
+  # The absolute expansion of the relative_path attribute.
+  #
+  attr_reader :absolute
+
+  # 
+  # ====Description:
+  # This initializes a new PathRelativeToCaller instance with
+  # path, a file system path relative to the calling file.
+  # 
+  # ====Parameters:
+  # [path]
+  #      A file system path relative to the calling file
+  # 
+  def initialize(path)
+    if(path.respond_to?(TO_PATH))
+      @relative = path.__send__(TO_PATH)
+    else
+      @relative = path
+    end
+
+    @relative = @relative.dup()
+    @absolute = File.expand_path_relative_to_caller(@relative)
+  end
+
+  # 
+  # ====Returns:
+  # A String containing the absolute expansion of the
+  # relative path contained in self.
+  # 
+  def to_s
+    return @absolute
+  end
+  
+  #:stopdoc:
+  # This block was ripped from pathname.rb in the Ruby Standard library.
+  # Basically, PathNameRelativeToCaller will define a to_path method if
+  # being interpreted by Ruby 1.9 and a to_str method otherwise.  to_path
+  # (or to_str) must be defined in order for PathNameRelativeToCaller instances
+  # to be interchangeable with strings as arguments to Ruby I/O methods.
+  if RUBY_VERSION < "1.9"
+    TO_PATH = :to_str
+  else
+    # to_path is implemented so Pathname objects are usable with File.open,etc.
+    TO_PATH = :to_path
+  end
+  alias_method(TO_PATH, :to_s)
+  #:startdoc:
+end

data/test/test_file.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'relative/file'
+require 'relative/pathrelativetocaller'
+
+require 'test/unit'
+
+class RelativeFileTest < Test::Unit::TestCase
+  def expand_path_relative_to_caller_trial(relative_path)
+    absolute_path = File.expand_path_relative_to_caller(relative_path)
+
+    expected_absolute_path = File.expand_path(File.join(File.dirname(__FILE__), relative_path))
+
+    assert_equal(expected_absolute_path, absolute_path)
+
+    #
+    # Expanding an absolute path relative to the caller should be
+    # a no-op.
+    #
+    absolute_path = File.expand_path_relative_to_caller(expected_absolute_path)
+    assert_equal(expected_absolute_path, absolute_path)
+  end
+
+  def test_expand_path_relative_to_caller
+    expand_path_relative_to_caller_trial(".")
+    expand_path_relative_to_caller_trial("..")
+    expand_path_relative_to_caller_trial("../lib")
+    expand_path_relative_to_caller_trial(File.basename(__FILE__))
+  end
+end

data/test/test_kernel.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'relative/kernel'
+
+require 'test/unit'
+
+class RelativeKernelTest < Test::Unit::TestCase
+  def require_relative_trial(relative_path)
+    require_relative(relative_path)
+
+    #
+    # require_relative also should handle absolute paths
+    # correctly.
+    #
+    absolute_path = File.expand_path(File.join(File.dirname(__FILE__), relative_path))
+    require_relative(absolute_path)
+  end
+
+  def test_require_relative
+    require_relative_trial('../lib/relative/kernel')
+  end
+end

data/test/test_pathname.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'relative/pathname'
+require 'relative/pathrelativetocaller'
+
+require 'test/unit'
+
+class RelativePathnameTest < Test::Unit::TestCase
+  def expand_path_relative_to_caller_trial(relative_path)
+    absolute_path = relative_path.expand_path_relative_to_caller()
+
+    expected_absolute_path = (Pathname(__FILE__).dirname() + relative_path).expand_path()
+
+    assert_equal(expected_absolute_path, absolute_path)
+
+    #
+    # Expanding an absolute path relative to the caller should be
+    # a no-op.
+    #
+    absolute_path = expected_absolute_path.expand_path_relative_to_caller()
+    assert_equal(expected_absolute_path, absolute_path)
+  end
+
+  def test_expand_path_relative_to_caller
+    expand_path_relative_to_caller_trial(Pathname("."))
+    expand_path_relative_to_caller_trial(Pathname(".."))
+    expand_path_relative_to_caller_trial(Pathname(PathRelativeToCaller.new("../lib")))
+    expand_path_relative_to_caller_trial(Pathname(File.basename(__FILE__)))
+  end
+end

data/test/test_pathrelativetocaller.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+require 'relative/pathrelativetocaller'
+
+class PathRelativeToCallerTest < Test::Unit::TestCase
+  def path_trial(relative_path, expected_absolute_path)
+    path = PathRelativeToCaller.new(relative_path)
+    assert_equal(relative_path, path.relative)
+    assert_equal(expected_absolute_path, path.absolute)
+  end
+
+  def test_path_expansion
+    path_trial(File.basename(__FILE__), File.expand_path(__FILE__))
+    path_trial("../Rakefile",
+               File.expand_path(File.join(File.dirname(__FILE__), "../Rakefile")))
+    path_trial(File.expand_path(__FILE__), File.expand_path(__FILE__))
+  end
+
+  def test_io_operations
+    #
+    # Verify that PathRelativeToCaller correctly can be passed into
+    # the core I/O methods.
+    #
+    assert_equal(IO.read(File.expand_path(File.join(File.dirname(__FILE__), "../Rakefile"))),
+                 IO.read(PathRelativeToCaller.new("../Rakefile")))
+
+    File.open(PathRelativeToCaller.new(File.basename(__FILE__))) do |rel_file|
+      File.open(__FILE__) do |abs_file|
+        assert_equal(abs_file.read(), rel_file.read())
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: relative
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- DesigningPatterns
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-06-26 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.6.0
+    version: 
+description: The relative library enhances Ruby's core and standard libraries to support naming, opening, and reading files relative to the Ruby file currently being interpreted (the contents of the __ FILE __ identifier). This functionality is especially useful in embedded Ruby (eruby, erb, erubis, etc.) where absolute paths or paths relative to the interpreter's current working directory are problematic (due to file system structures and working directories varying across platforms and web servers).
+email: 
+- technical.inquiries@designingpatterns.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- History.txt
+- README.txt
+files: 
+- Manifest.txt
+- LICENSE
+- History.txt
+- README.txt
+- Rakefile
+- lib/relative.rb
+- lib/relative/file.rb
+- lib/relative/kernel.rb
+- lib/relative/pathname.rb
+- lib/relative/pathrelativetocaller.rb
+- test/test_file.rb
+- test/test_kernel.rb
+- test/test_pathname.rb
+- test/test_pathrelativetocaller.rb
+has_rdoc: true
+homepage: "Project Page: http://rubyforge.org/projects/relative/"
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: relative
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: The relative library enhances Ruby's core and standard libraries to support naming, opening, and reading files relative to the Ruby file currently being interpreted (the contents of the __ FILE __ identifier)
+test_files: 
+- test/test_pathrelativetocaller.rb
+- test/test_pathname.rb
+- test/test_file.rb
+- test/test_kernel.rb