impromptu 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,34 @@
+Public Domain, so feel free to do whatever you like. If you prefer a long legal definition, the Creative Commons public domain description is below. In this, I (William Cannings) am the Owner, and Impromptu is the Work.
+
+== Creative Commons Legal Code ==
+
+CC0 1.0 Universal
+
+CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER.
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following:
+
+the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work;
+moral rights retained by the original author(s) and/or performer(s);
+publicity and privacy rights pertaining to a person's image or likeness depicted in a Work;
+rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below;
+rights protecting the extraction, dissemination, use and reuse of data in a Work;
+database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and
+other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof.
+2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document.
+Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law.
+Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work.
+Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work.

data/README.rdoc

@@ -0,0 +1,76 @@
+= Impromptu
+A lazy/auto-loading component manager for Ruby.
+
+== Motivation
+Large libraries such as web frameworks define a lot of code that may never be used in a production running app. It would be nice if you could pick and choose which parts of a library are actually loaded and used within an application, and automatically reload files when they are changed. It would be even nicer if you didn't have to manually configure which components to include at all.
+
+== Overview
+Impromptu allows you to define components of a system, the gem/external requirements of a component, and the files and folders which implement the resources provided. +const_missing+ is used to load modules and classes the first time they are used, along with any gems/requirements the component as a whole has. By doing this, there's no need to define which components of a library are actually used; the fewest components possible are loaded simply as a result of the code you write.
+
+A simple component DSL is used to define components:
+
+  component 'framework' do
+    namespace :Framework
+    requires  'rack'
+    folder    'lib', nested_namespaces: false
+  end
+
+  component 'private' do
+    namespace :Framework
+    folder 'private'
+  end
+
+  component 'other' do
+    folder 'other' do
+      file 'load.rb'
+      file 'mods.rb', :provides => [:ModOne, :ModTwo]
+    end
+  end
+
+
+Components may have a namespace, may have requirements, and must have at least one folder containing source files that implement the resources provided by the component.  Imagine the 'lib' folder used by the 'framework' component contained the files:
+
+  [lib]
+    \ klass.rb
+    \ [group]
+        \ klass2.rb
+
+These files would provide the resources Framework::Klass, and Framework::Klass2. If the 'nested_namespaces' flag was true, klass2.rb would instead provide Framework::Group::Klass2. When either of these resources are requested anywhere, Impromptu first loads the requirements of the component (in this case rack) before loading any files implementing the requested resource. Sometimes, a resource is defined by more than one file. Imagine the 'private' folder contained:
+
+  [private]
+    \ klass.rb
+    \ klass2.rb
+
+Because the 'private' component shares the same namespace as the 'framework' component, these two files would also provide Framework::Klass and Framework::Klass2. Referencing Klass or Klass2 would load the file from 'lib' first before the file from 'private' (since the 'private' component appears after the 'framework' component).
+
+In both these components no file provides the Framework module. In this case, Impromptu will automatically create a blank module. If after an update a file appears which implements the namespace, the blank module will be removed, and the new implementation loaded. Removing this file will cause the blank module to be created again.
+
+Just as a resource may be implemented by multiple files, a file may implement multiple resources. Because Impromptu doesn't scan files before loading them you must manually tell Impromptu which resources a file provides if it provides more than one, or if the name of the resource cannot be inferred from the name of the file. Folder definitions may take a block (as with the 'other' folder from the 'other' component). Calling file within the block informs Impromptu of a file to load, and specifying the :provides option allows you to tell Impromptu the names of the resources implemented in the file.
+
+== Defining Components
+Before any resources from a component can be loaded, you must define the components of your system in a block provided to define_components. There are two options: you can either define components directly in this block, or you can call the 'parse_file' method to load a file which defines the components instead.
+
+  Impromptu.define_components do
+    # direct
+    component do
+      ...
+    end
+    
+    # from a file
+    parse_file 'framework/framework.components'
+  end
+
+The present working directory, or the directory containing a file being parsed, is used as the current 'base' directory. Folder references are assumed to be relative to this directory, unless they are an absolute path. Once the set of components is defined it cannot be changed. The list of folders implementing a component also cannot be changed, although the files within a folder may be changed and reloaded. These restrictions may be lifted in a later release.
+
+== Reloading Components
+Impromptu supports the reloading of resource implementation files, including adding new files to a folder and removing existing files. By default folders are assumed to be reloadable, though setting the reloadable option to false prevents folders being scanned during an update:
+
+  folder 'lib', :reloadable => false
+
+To force a reload of already loaded resources, and an update of the resource tree, call Impromptu.update. Only resources which have their files changed and have previously been loaded will be reloaded. Any new files will either insert their resources in to the resource tree or add themselves to the list of files implementing an existing resource. Removing a file may simply remove it from the list of files implementing a resource, or it may unload and remove the resource entirely (if it was the only or last file implementing a resource). Any folders which were defined using a block and subsequent calls to 'file' will not be scanned for new or missing files since their file list is explicitly defined. Only files with a reloadable extension (currently 'rb') will be reloaded if they are changed - object files such as bundles and shared objects can only be loaded once.
+
+== Known Issues
+Reloading resources is currently not guarded so if you have one thread reloading a resource, and another accessing it, the second thread may get a stale reference.
+
+== Thanks
+To Matt (http://twitter.com/mattrobs) for the name

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "impromptu"
+    gem.summary = "Component and dependency manager for Ruby"
+    gem.description = "Component and dependency manager for Ruby"
+    gem.email = "me@willcannings.com"
+    gem.homepage = "http://github.com/willcannings/impromptu"
+    gem.authors = ["Will Cannings"]
+    gem.add_development_dependency "shoulda"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Impromptu #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/impromptu.gemspec

@@ -0,0 +1,106 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{impromptu}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Will Cannings"]
+  s.date = %q{2010-09-30}
+  s.description = %q{Component and dependency manager for Ruby}
+  s.email = %q{me@willcannings.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "impromptu.gemspec",
+     "lib/impromptu.rb",
+     "lib/impromptu/autoload.rb",
+     "lib/impromptu/component.rb",
+     "lib/impromptu/component_set.rb",
+     "lib/impromptu/file.rb",
+     "lib/impromptu/folder.rb",
+     "lib/impromptu/impromptu.rb",
+     "lib/impromptu/ordered_set.rb",
+     "lib/impromptu/resource.rb",
+     "lib/impromptu/symbol.rb",
+     "test/framework/copies/extra_klass2.rb",
+     "test/framework/copies/new_klass.rb",
+     "test/framework/copies/new_unseen.rb",
+     "test/framework/copies/original_klass.rb",
+     "test/framework/ext/extensions.rb",
+     "test/framework/ext/extensions/blog.rb",
+     "test/framework/lib/group/klass2.rb",
+     "test/framework/lib/klass.rb",
+     "test/framework/other/also.rb",
+     "test/framework/other/ignore.rb",
+     "test/framework/other/load.rb",
+     "test/framework/other/two.rb",
+     "test/framework/private/klass.rb",
+     "test/framework/test.components",
+     "test/helper.rb",
+     "test/test_autoload.rb",
+     "test/test_component.rb",
+     "test/test_component_set.rb",
+     "test/test_folder.rb",
+     "test/test_impromptu.rb",
+     "test/test_integration.rb",
+     "test/test_ordered_set.rb",
+     "test/test_resource.rb",
+     "test/test_symbol.rb"
+  ]
+  s.homepage = %q{http://github.com/willcannings/impromptu}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Component and dependency manager for Ruby}
+  s.test_files = [
+    "test/framework/copies/extra_klass2.rb",
+     "test/framework/copies/new_klass.rb",
+     "test/framework/copies/new_unseen.rb",
+     "test/framework/copies/original_klass.rb",
+     "test/framework/ext/extensions/blog.rb",
+     "test/framework/ext/extensions.rb",
+     "test/framework/lib/group/klass2.rb",
+     "test/framework/lib/klass.rb",
+     "test/framework/other/also.rb",
+     "test/framework/other/ignore.rb",
+     "test/framework/other/load.rb",
+     "test/framework/other/two.rb",
+     "test/framework/private/klass.rb",
+     "test/helper.rb",
+     "test/test_autoload.rb",
+     "test/test_component.rb",
+     "test/test_component_set.rb",
+     "test/test_folder.rb",
+     "test/test_impromptu.rb",
+     "test/test_integration.rb",
+     "test/test_ordered_set.rb",
+     "test/test_resource.rb",
+     "test/test_symbol.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 0"])
+  end
+end
+

data/lib/impromptu/autoload.rb

@@ -0,0 +1,33 @@
+module Impromptu
+  module Autoload
+    # Impromptu implements the autoloading behaviour using this module
+    # and this method. Object is extended with this module so we can
+    # catch references to objects which don't exist. It first tries
+    # to determine if we know about the resource corresponding to name
+    # and if so loads and returns a reference to it. Otherwise, the usual
+    # NameError exception will be raised by Object. We also test to make
+    # sure a resource isn't already loaded before returning a reference
+    # to it. If it is, then something very screwy has gone on and Ruby
+    # cannot locate an already loaded resource.
+    def const_missing(symbol)
+      # walk the resource tree and get a reference to the
+      # resource or nil if we're not tracking it
+      resource = Impromptu.root_resource.child(symbol)
+      
+      # if we don't know about the symbol, send the method to
+      # Object which will raise an exception
+      super(symbol) if resource.nil?
+      
+      # ensure the resource hasn't already been loaded
+      raise "Illegal condition: const_missing called after a resource has been loaded" if resource.loaded?
+      
+      # load the resource and return a reference to it. this
+      # assumes that the source files will correctly define
+      # the resource. otherwise nil will be returned.
+      resource.reload
+      resource.reference
+    end
+  end
+end
+
+Object.extend(Impromptu::Autoload)

data/lib/impromptu/component.rb

@@ -0,0 +1,124 @@
+module Impromptu
+  class Component
+    attr_accessor :base_path, :name, :requirements, :folders, :frozen
+    attr_writer   :namespace
+    
+    # Create a new component. base_path is the 'current working
+    # directory' of the component, and all folder paths will be
+    # joined with this path to create an absolute path. Name is
+    # the name of the component and is currently only used as a
+    # reference. Names must be unique amongst all components, so
+    # to avoid clashes a namespacing scheme should be used.
+    def initialize(base_path, name)
+      @base_path    = base_path || Pathname.new('.').realpath
+      @name         = name
+      @requirements = OrderedSet.new
+      @folders      = OrderedSet.new
+      @namespace    = nil
+      @frozen       = false
+      @dependencies_loaded = false
+    end
+    
+    # Override eql? so two components with the same name will be
+    # considered equal by ordered set.
+    def eql?(other)
+      other.name == @name
+    end
+    
+    # Override hash so two components with the same name will result
+    # in the same hash value.
+    def hash
+      @name.hash
+    end
+    
+    # Add external dependencies (such as gems) to this component. e.g:
+    # requires 'gem_name', 'other_file'. May be called multiple times.
+    def requires(*resources)
+      protect_from_modification
+      @requirements.merge(resources)
+    end
+    
+    # Declare a folder implementing this component. All source files
+    # within this folder are assumed to define the resources of this
+    # component. Sub-folders by default provide nested namespaces,
+    # and when used in combination with the namespace method can
+    # produce multi-level namespaces. For example, a root folder 'src'
+    # which contains a sub-folder 'plugins', and a file 'testing.rb'
+    # would provide the resource Plugins::Testing. If namespace was
+    # used to define a root namespace for the component, that namespace
+    # would precede the Plugins namespace. To turn off this behaviour
+    # set the nested_namespaces option to false. e.g:
+    # folder 'src', nested_namespaces: false
+    def folder(path, options={}, &block)
+      protect_from_modification
+      folder = @folders << Folder.new(@base_path.join(*path), self, options, block)
+    end
+    
+    # Define a namespace used for all resources provided by this
+    # component. This becomes the root namespace for all top level
+    # folders. e.g if you declare a namespace ':Root', and a single
+    # folder 'src' which contains a file 'klass.rb', klass.rb will
+    # declare the resource Root::Klass. By default, nested folders
+    # will extend the namespace with the name of the folder. For
+    # instance, if the src folder contained another called 'plugins'
+    # which contained a file 'testing.rb', the resource
+    # Root::Plugins::Testing would be defined. Folder declarations
+    # can override this behaviour.
+    def namespace(name=nil)
+      unless name.nil?
+        protect_from_modification
+        @namespace = name.to_sym
+      end
+      @namespace
+    end
+    
+    # Load the external dependencies required by this component. If
+    # the require fails, ruby gems is loaded and the require attempted
+    # again. Any failures after this point will cause a LoadError
+    # exception to bubble through your application.
+    def load_external_dependencies
+      return false if @dependencies_loaded
+      @requirements.each do |requirement|
+        begin
+          require requirement
+        rescue LoadError => unavailable
+          begin
+            require 'rubygems'
+          rescue LoadError
+            raise unavailable
+          end
+          require requirement
+        end
+      end
+      @dependencies_loaded = true
+    end
+    
+    # Mark a component as 'frozen'. Modification of the component
+    # requirements or list of folders is not allowed after this.
+    def freeze
+      # freeze files
+      @folders.each do |folder|
+        folder.files.each do |file|
+          file.freeze
+        end
+      end
+      
+      # create a blank namespace module if required
+      unless namespace.nil?
+        Impromptu.root_resource.get_or_create_child(namespace).namespace!
+      end
+      
+      @frozen = true
+    end
+    
+    # True if the component definition has been frozen.
+    def frozen?
+      @frozen
+    end
+    
+    private
+      def protect_from_modification
+        raise "Modification of component after component has been loaded" if @frozen
+      end
+  end
+end

data/lib/impromptu/component_set.rb

@@ -0,0 +1,10 @@
+module Impromptu
+  class ComponentSet < OrderedSet
+    # Retrieve a component by name. This is used very
+    # rarely (only in component definitions and the
+    # test suite) so a linear search is acceptable.
+    def [](name)
+      @items_list.select {|component| component.name == name}.first
+    end
+  end
+end