subload 1.0.0

data/README

@@ -0,0 +1,77 @@
+subload
+
+A handy dandy autoload / require / load helper for your rubies. Similar to
+using[1], but with a few differences of opinion, and a bit shorter.
+
+Basically, expand path is fine, up until a point. Sometimes there's no point
+(i.e. when the load path already contains most of the path you're trying to
+open). When you're writing libs that users might require sub parts with
+'libname/sub_part', then expand_path combined with say, rubygems, can lead to
+double requires. Lets not do that. :-)
+
+[1] http://github.com/smtlaissezfaire/using/
+
+TODO - replace me... more...
+
+Examples:
+
+module A
+
+  # The nominal use case, A.autoload :B, 'a/b'
+  # You rarely need much else!
+  subload :B
+
+  # A custom path, A.autoload :C, 'a/c'
+  subload :C, :path => 'a/c'
+  # For example when 'a/c' defines several constants:
+  subload :Ca, :path => 'a/c'
+  subload :Cb, :path => 'a/c'
+
+  # An expanded path, A.autoload :D, File.join(Dir.pwd, 'a/d')
+  subload :D, :expand_path => true
+  # This has interesting uses in combination, although not generally 
+  # recommended:
+  subload :E, :path => '../../path/e', :expand_path => true
+
+  # Explicitly override the mode, for this call only, A.require 'a/f'
+  subload :F, :mode => :require
+
+  # Set the mode for all subsiquent calls to subload in this class/module
+  subload_with :require
+  subload :G # => require 'a/g'
+  subload :H # => require 'a/h'
+
+  # Other features intended for library and framework developers are described
+  # in the class documentation.
+
+end
+
+Some Notes:
+
+* File.expand_path: Expand path is good if you're traversing up directories.
+  It is bad if you're loading something within a library that is on the load
+  path. If the library is on the load path, and you require files with an
+  expanded path, there is the likelihood of a double require when other code
+  contains a require that is expectant of the load path modification.
+
+* Frameworks: Sometimes require explicit load order control. In these cases,
+  overriding the loader and either tracking, or performing stateful operations
+  works well.
+
+* Abusive use of override_mode: Override mode is potentially dangerous. As per
+  the other documentation, override mode should be reserved for use in
+  application code only. Libraries setting override mode could cause
+  additional failure cases for foreign libraries, although gratuitous addition
+  of loading mechanisms is not recommended.
+
+* Generated code loading: When you're doing code generation, sometimes it is
+  desirable to have tow locations from which to load a class. One will contain
+  custom class defintions, and the other will contain generated definitions.
+  Using a custom loader, one can then utilise a single subload statement to
+  correctly load both files.
+
+TODO Chaotic Overloading
+
+Consider vertical vs. horizontal delegation rules and use cases for new
+loaders in non-framework libraries that perform custom loads such that it is
+easy to say "invoke the current load mode with the following options".

data/Rakefile

@@ -0,0 +1,108 @@
+#!/usr/bin/env rake
+require 'rake/clean'
+
+task :default => :spec
+
+def spec(file = Dir['*.gemspec'].first)
+  @spec ||=
+  begin
+    require 'rubygems/specification'
+    Thread.abort_on_exception = true
+    data = File.read(file)
+    spec = nil
+    Thread.new { spec = eval("$SAFE = 3\n#{data}") }.join
+    spec.instance_variable_set(:@filename, file)
+    def spec.filename; @filename; end
+    spec
+  end
+end
+
+def manifest; @manifest ||= `git ls-files`.split("\n").reject{|s|s=~/\.gemspec$|\.gitignore$/}; end
+
+@gem_package_task_type = begin
+  require 'rubygems/package_task'
+  Gem::PackageTask
+rescue LoadError
+  require 'rake/gempackagetask'
+  Rake::GemPackageTask
+end
+def gem_task; @gem_task ||= @gem_package_task_type.new(spec); end
+gem_task.define
+Rake::Task[:clobber].enhance [:clobber_package]
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = spec.test_files
+  t.ruby_opts = ['-rubygems'] if defined? Gem
+  t.warning = true
+end unless spec.test_files.empty?
+
+rdoc_task_type = begin
+  require 'rdoc/task'
+  RDoc::Task
+rescue LoadError
+  require 'rake/rdoctask'
+  Rake::RDocTask
+end
+df = begin; require 'rdoc/generator/darkfish'; true; rescue LoadError; end
+rdtask = rdoc_task_type.new do |rd|
+  rd.title = spec.name
+  rd.main = spec.extra_rdoc_files.first
+  lib_rexp = spec.require_paths.map { |p| Regexp.escape p }.join('|')
+  rd.rdoc_files.include(*manifest.grep(/^(?:#{lib_rexp})/))
+  rd.rdoc_files.include(*spec.extra_rdoc_files)
+  rd.template = 'darkfish' if df
+end
+
+Rake::Task[:clobber].enhance [:clobber_rdoc]
+
+require 'yaml'
+require 'rake/contrib/sshpublisher'
+desc "Publish rdoc to rubyforge"
+task :publish => rdtask.name do
+  rf_cfg = File.expand_path '~/.rubyforge/user-config.yml'
+  host = "#{YAML.load_file(rf_cfg)['username']}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{spec.rubyforge_project}/#{spec.name}/"
+  Rake::SshDirPublisher.new(host, remote_dir, rdtask.rdoc_dir).upload
+end
+
+desc 'Generate and open documentation'
+task :docs => :rdoc do
+  path = rdtask.send :rdoc_target
+  case RUBY_PLATFORM
+  when /darwin/       ; sh "open #{path}"
+  when /mswin|mingw/  ; sh "start #{path}"
+  else 
+    sh "firefox #{path}"
+  end
+end
+
+desc "Regenerate gemspec"
+task :gemspec => spec.filename
+
+task spec.filename do
+  spec.files = manifest
+  spec.test_files = FileList['{test,spec}/**/{test,spec}_*.rb']
+  open(spec.filename, 'w') { |w| w.write spec.to_ruby }
+end
+
+desc "Bump version from #{spec.version} to #{spec.version.to_s.succ}"
+task :bump do
+  spec.version = spec.version.to_s.succ
+end
+
+desc "Tag version #{spec.version}"
+task :tag do
+  tagged = Dir.new('.git/refs/tags').entries.include? spec.version.to_s
+  if tagged
+    warn "Tag #{spec.version} already exists"
+  else
+    # TODO release message in tag message
+    sh "git tag #{spec.version}"
+  end
+end
+
+desc "Release #{gem_task.gem_file} to rubyforge"
+task :release => [:tag, :gem, :publish] do |t|
+  sh "rubyforge add_release #{spec.rubyforge_project} #{spec.name} #{spec.version} #{gem_task.package_dir}/#{gem_task.gem_file}"
+end

data/examples/a.rb

@@ -0,0 +1,11 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'subload'
+
+module A
+  # Normal subload, by file, looks in __DIR__/a/foo
+  subload :Foo
+  p Foo
+  p Foo::Bar
+end
+
+p A::Foo::Baz

data/examples/a/foo.rb

@@ -0,0 +1,7 @@
+module A
+  class Foo
+    subload_with(:require)
+    subload :Bar
+    subload :Baz
+  end
+end

data/examples/a/foo/bar.rb

@@ -0,0 +1,6 @@
+module A
+  class Foo
+    class Bar
+    end
+  end
+end

data/examples/a/foo/baz.rb

@@ -0,0 +1,6 @@
+module A
+  class Foo
+    class Baz
+    end
+  end
+end

data/examples/rails/loader.rb

@@ -0,0 +1,27 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../../lib')
+require 'subload'
+
+module Rails
+  def self.production?
+    # flip me, baby
+    false
+  end
+
+  module Loader
+    Subloader = lambda do |calling_object, const_name, path, options|
+      # Example is allowing override exclusively in a particular mode, but we
+      # could also be simply registering what's being loaded instead, and
+      # doing some other magic.
+      if Rails.production? && options[:eager_load]
+        require path
+      else
+        calling_object.__send__ :autoload, const_name, path
+      end
+    end
+
+    Subload::MODES[:rails_subloader] = Subloader
+    subload_with(:rails_subloader)
+    subload :SomethingWeDontCareAbout
+    subload :SomethingEssentialForThreadedBoot, :eager_load => true
+  end
+end

data/lib/subload.rb

@@ -0,0 +1,97 @@
+# TODO convert to yardoc
+module Subload
+  # To add modes to subload, simply add them to this hash. Please use the
+  # a namespace convention, starting with +:projectname_operationdescription+.
+  MODES = {
+    :autoload => lambda { |o,s,p,ops| o.__send__ :autoload, s, p },
+    :require  => lambda { |o,s,p,ops| o.__send__ :require, p },
+    :load     => lambda { |o,s,p,ops| o.__send__ :load, p }
+  }
+
+  @default_mode = :autoload
+  class <<self
+    # Subload defaults to autoload, which is appropriate and performant for
+    # single threaded applications and libraries. Setting the default mode
+    # will affect all future subloads that do not specify another mode
+    # explicitly, proided +Subload.override_mode+ has not been set.
+    attr_accessor :default_mode
+    # Subload defaults to autoload, which is appropriate and performant for
+    # single threaded applications and libraries. Sometimes users may want to
+    # switch to eager loading or some other loading mechanism forcefully.
+    # Override mode should not be set in normal library code, but should be
+    # reserved for application code only. It may be acceptable for use in
+    # appropriate locations in frameworks.
+    attr_accessor :override_mode
+  end
+
+  # Sets the subload mode locally for the current class. This is how one would
+  # use a custom loading mode
+  def subload_with(mode = nil)
+    @_subload_mode = mode unless mode.nil?
+    MODES[Subload.override_mode || @_subload_mode || Subload.default_mode]
+  end
+
+  # Load the given constant name from the path corresponding to the
+  # conventional mapping of the class name underscored. Example:
+  #  class A
+  #   subload :B # performs A.autoload(:B, 'a/b')
+  #  end
+  #
+  # You can overload various operation styles in subload using the options
+  # hash:
+  # * :path - explicitly alter the path that will be loaded, this is passed on
+  #   unmodified.
+  # * :mode - explicitly override the loading mode. N.B. Subload.override_mode
+  #   takes precidence over this.
+  # * :expand_path - when set to true, the path will be expanded before being
+  #   passed on to the loading mechanism.
+  #
+  # For custom loading mechanisms, further options are passed on, as such, you
+  # may find other behaviors if subload is being used inside a framework.
+  def subload(symbol, options = {})
+    sub_path, mode = *options.values_at(:path, :mode)
+    klass = self.instance_of?(Class) || self.instance_of?(Module)
+    klass = klass ? self.__name__ : self.class.__name__
+    path = File.join(sub_path || Subload.to_path("#{klass}::#{symbol}"))
+    path = File.expand_path(path) if options[:expand_path]
+    $stdout.puts [:subload, symbol, path, mode].inspect if $DEBUG
+    subload_with(mode)[self, symbol, path, options]
+  end
+
+  LONG_UPPER_CONSTS = [/([A-Z]+)([A-Z][a-z]+)/, '\1_\2']
+  TAIL_UPPER_CONSTS = [/([a-z])([A-Z])/, '\1_\2']
+  DOUBLE_UNDERSCORE = '__'
+  DOUBLE_COLON = '::'
+  SLASH = '/'
+
+  # Subloads snake_case method, this is very similar to that of facets, rails,
+  # and merb, but potentially has minor differences.
+  def self.to_path(s)
+    # similar to facets/string/pathize, only supports TCPServer, etc.
+    s = s.to_s.dup # We're modifying, lets be careful
+    s.gsub!(*LONG_UPPER_CONSTS)
+    s.gsub!(*TAIL_UPPER_CONSTS)
+    s.gsub!(DOUBLE_UNDERSCORE, SLASH)
+    s.gsub!(DOUBLE_COLON, SLASH)
+    s.downcase!
+    s
+  end
+end
+
+class Object
+  # Make sure we hit the top level, objects, classes, etc. We do not make this
+  # private, because source loading may want to not be, for more complex
+  # loading environments. External invocation is not recommended without clear
+  # reasoning.
+  include Subload
+end
+
+class Module
+  # If anyone can think of a better way to do this, please, I'm all ears.
+  # I'd like syntax for class_name?(object || klass) # => Symbol || String
+  if defined?(__name__)
+    warn("Subload clobber Class#__name__ from: #{method(:__name__).inspect}")
+  else
+    alias __name__ name
+  end
+end

data/test/test_subload.rb

@@ -0,0 +1,71 @@
+require "test/unit"
+
+$:.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+require "subload"
+
+class TestSubload < Test::Unit::TestCase
+  # pretend we're in a libdir!
+  $:.unshift File.expand_path(File.dirname(__FILE__))
+
+  def teardown
+    Subload.override_mode = nil
+    Subload.default_mode = :autoload
+    subload_with(false)
+  end
+
+  subload :A
+
+  def test_subload_defaults
+    assert !defined?(Al) # Not loaded already (defaults to autoload)
+    assert_equal(true, A) # Autoloaded
+    assert defined?(Al)
+  end
+
+  def test_subload_require
+    subload :B, :mode => :require
+    assert defined?(B)
+  end
+
+  def test_subload_load
+    subload :C, :path => "test_subload/c.rb", :mode => :load
+    assert defined?(C)
+  end
+
+  def test_subload_with
+    subload_with(:require)
+    subload :D
+    subload_with(false)
+
+    assert_equal subload_with(false), subload_with
+    assert_equal subload_with(:autoload), subload_with
+
+    assert defined?(Dl) # Was required before we hit D
+    assert defined?(D)
+  end
+
+  def test_default_mode
+    Subload.default_mode = :require
+    assert_equal subload_with(:require), subload_with(nil)
+  ensure
+    Subload.default_mode = :autoload
+    subload_with(false)
+  end
+
+  def test_override_mode
+    assert !defined?(F)
+    assert !defined?(F::Al)
+    assert !defined?(F::A)
+    Subload.override_mode = :require
+    subload_with(:autoload)
+    subload :F
+    assert defined?(F)
+    assert defined?(F::Al)
+    assert defined?(F::A)
+  end
+
+  def test___name__
+    assert_equal("Class", Class.__name__)
+    assert_equal("Module", Module.__name__)
+  end
+
+end

data/test/test_subload/a.rb

@@ -0,0 +1,2 @@
+TestSubload::A = true
+TestSubload::Al = true

data/test/test_subload/b.rb

@@ -0,0 +1 @@
+TestSubload::B = true

data/test/test_subload/c.rb

@@ -0,0 +1 @@
+TestSubload::C = true

data/test/test_subload/d.rb

@@ -0,0 +1,2 @@
+TestSubload::D = true
+TestSubload::Dl = true

data/test/test_subload/e.rb

@@ -0,0 +1,2 @@
+TestSubload::E = true
+TestSubload::El = true

data/test/test_subload/f.rb

@@ -0,0 +1,3 @@
+class TestSubload::F
+  subload :A
+end

data/test/test_subload/f/a.rb

@@ -0,0 +1,2 @@
+TestSubload::F::A = true
+TestSubload::F::Al = true

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: subload
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- James Tucker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-10 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.4.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.8.7
+    version: 
+description: An autoload/require/custom loader wrapper
+email: raggi@rubyforge.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+- Rakefile
+- examples/a.rb
+- examples/a/foo.rb
+- examples/a/foo/bar.rb
+- examples/a/foo/baz.rb
+- examples/rails/loader.rb
+- lib/subload.rb
+- test/test_subload.rb
+- test/test_subload/a.rb
+- test/test_subload/b.rb
+- test/test_subload/c.rb
+- test/test_subload/d.rb
+- test/test_subload/e.rb
+- test/test_subload/f.rb
+- test/test_subload/f/a.rb
+has_rdoc: true
+homepage: http://libraggi.rubyforge.org/subload
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Subload
+- --main
+- README
+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: libraggi
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: An autoload/require/custom loader wrapper
+test_files: 
+- test/test_subload.rb