impromptu 1.0.0

data/lib/impromptu/file.rb

@@ -0,0 +1,220 @@
+module Impromptu
+  class File
+    attr_reader :path, :folder, :resources, :related_resources, :related_files, :modified_time
+    RELOADABLE_EXTENSIONS = %w{rb}
+    
+    def initialize(path, folder, provides=[])
+      @path               = path
+      @folder             = folder
+      @resources          = OrderedSet.new
+      @related_resources  = Set.new
+      @related_files      = Set.new
+      @frozen             = false
+      @modified_time      = nil
+      @dirty              = true
+      @provides           = [provides].compact.flatten
+    end
+    
+    # Override eql? so two files with the same path will be
+    # considered equal by ordered set.
+    def eql?(other)
+      other.path == @path
+    end
+    
+    # Override hash so two files with the same path will result
+    # in the same hash value.
+    def hash
+      @path.hash
+    end
+    
+    # Traverse the file/resource graph to determine which total
+    # set of files and resources are related to this file. For
+    # instance, if a resource provided by this file is also
+    # defined in another, both files, and the total set of
+    # resources provided by these files, are included. If
+    # further resources are provided, those resources along
+    # with any other files defining them, are also included.
+    def freeze
+      return if @frozen
+      remaining_resources = @resources.to_a
+      remaining_files = [self]
+      
+      while remaining_resources.size > 0 || remaining_files.size > 0
+        if resource = remaining_resources.shift
+          @related_resources << resource
+          resource.files.each do |file|
+            remaining_files << file unless @related_files.include?(file)
+          end
+        end
+        
+        if file = remaining_files.shift
+          @related_files << file
+          file.add_related_file(self)
+          file.resources.each do |resource|
+            remaining_resources << resource unless @related_resources.include?(resource)
+          end
+        end
+      end
+      
+      @frozen = true
+    end
+    
+    # Unfreeze this file by clearing the related files and
+    # resources lists.
+    def unfreeze
+      @related_resources = Set.new
+      @related_files = Set.new
+      @frozen = false
+    end
+    
+    # Unfreeze and freeze a files association lists
+    def refreeze
+      unfreeze
+      freeze
+    end
+    
+    # Load (or reload) all of the resources provided by this
+    # file. If a resource is provided by multiple files, those
+    # files will also be reloaded (and the resources provided
+    # in those files reloaded). For this reason it's advisable
+    # to declare a single resource per file, otherwise the
+    # dependencies between files and resources can cause large
+    # subsections of the component graph to be reloaded together.
+    def reload
+      @related_resources.each {|resource| resource.unload}
+      @related_files.each {|file| file.load}
+    end
+    
+    # Load the file is possible, after loading any external
+    # dependencies for the component owning this file. The
+    # modified time is updated so we know if a change is made
+    # to the file at a later date. This does a simple load of
+    # the file and doesn't unload any resources beforehand.
+    # You typically want to use reload to ensure that the
+    # resources provided by this file are fully unloaded and
+    # reloaded in one go.
+    def load
+      @folder.component.load_external_dependencies
+      Kernel.load @path if reloadable?
+      @modified_time = @path.mtime
+      @dirty = false
+    end
+    
+    # Unload all of the resources provided by this file. This
+    # doesn't just unload the parts of a resource defined by
+    # this file, but the entire resource itself. i.e if there
+    # are two files defining a resource, unloading one file
+    # will unload the resource completely.
+    def unload
+      resources.each {|resource| resource.unload}
+      @modified_time = nil
+      @dirty = true
+    end
+    
+    # Returns true if the current modification time of the
+    # underlying file is greater than the modified_time of
+    # the file when we last loaded it.
+    def modified?
+      resources_loaded? && (@dirty || @modified_time.nil? || (@path.mtime > @modified_time))
+    end
+    
+    # Reloads the associated resources only if the underlying
+    # file has been modified since the last time it was loaded.
+    def reload_if_modified
+      reload if modified?
+    end
+    
+    # Indicates if this file is currently loaded
+    def loaded?
+      !@modified_time.nil?
+    end
+    
+    # True if any of the resources provided by this file have
+    # been loaded.
+    def resources_loaded?
+      @resources.each do |resource|
+        return true if resource.loaded?
+      end
+      false
+    end
+    
+    # Add a file to the list of files related to this file.
+    def add_related_file(file)
+      @related_files << file
+      @dirty = true
+    end
+    
+    # Remove a file from the list of files related to this file.
+    def remove_related_file(file)
+      @related_files.delete(file)
+      @dirty = true
+    end
+    
+    # Delete references to this file from any resources or other
+    # files. This does not unload the resource, so if loaded, the
+    # resource will be defined by a file which is no longer tracked.
+    def remove
+      @related_files.each {|file| file.remove_related_file(self)}
+      @resources.each do |resource|
+        if resource.files.size == 1
+          resource.remove
+        else
+          resource.remove_file(self)
+        end
+      end
+    end
+    
+    # Should only be called once, and only after a file has been
+    # loaded for the first time. If the file was defined with
+    # a list of resources the file implements, inform each resource
+    # that this file implements the resource. Otherwise the name
+    # of the file is used to determine the resource provided (e.g
+    # klass_one.rb would be assumed to provide KlassOne).
+    def add_resource_definition
+      # unless defined, we assume the name of the file implies
+      # the resource that is provided by the file
+      if @provides.empty?
+        @provides << module_symbol_from_path
+      end
+      
+      # add a reference of this file to every appropriate resource
+      @provides.each do |resource_name|
+        resource = Impromptu.root_resource.get_or_create_child(combine_symbol_with_namespace(resource_name))
+        resource.add_file(self)
+        @resources << resource
+      end
+    end
+    
+    # True if the file has never been loaded before, or if the
+    # file is of a type that can be reloaded (i.e ruby source
+    # as opposed to C extensions).
+    def reloadable?
+      return true if !loaded?
+      RELOADABLE_EXTENSIONS.include?(@path.extname[1..-1])
+    end
+    
+    
+    private
+      # Turn the path of this file into a module name. e.g:
+      # /root/plugin/klass_one.rb => Plugin::KlassOne
+      def module_symbol_from_path
+        # remove any directory names from the path, and the file extension
+        extension = @path.extname
+        name = @folder.relative_path_to(@path).to_s[0..-(extension.length + 1)]
+      
+        # convert any names following a slash to namespaces
+        name.gsub!(/\/(.?)/) {|character| "::#{character[1].upcase}" }
+        
+        # upcase the first character, and any characters following an underscore
+        name.gsub(/(?:^|_)(.)/) {|character| character.upcase}.to_sym
+      end
+      
+      def combine_symbol_with_namespace(symbol)
+        if @folder.component.namespace
+          "#{@folder.component.namespace}::#{symbol}".to_sym
+        else
+          symbol.to_sym
+        end
+      end
+  end
+end

data/lib/impromptu/folder.rb

@@ -0,0 +1,151 @@
+module Impromptu
+  class Folder
+    attr_accessor :folder, :files, :component, :namespace
+    DEFAULT_OPTIONS   = {nested_namespaces: true, reloadable: true}
+    SOURCE_EXTENSIONS = %w{rb so bundle}
+    
+    # Register a new folder containing source files for a
+    # component. Path is a Pathname object representing the
+    # folder, and options may be:
+    # * nested_namespaces: true by default. If true, sub-
+    #   folders indicate a new namespace for resources. For
+    #   instance, a folder with a root of 'src', containing
+    #   a folder called 'plugins' which has a file 'klass.rb'
+    #   would define the resource Plugins::Klass. When false,
+    #   the file would simply represent Klass.
+    # * reloadable: true by default. If true, this folder
+    #   will be reloaded every time Impromptu.update is
+    #   called, and any modified files will be reloaded,
+    #   removed files unloaded, and new files tracked.
+    def initialize(path, component, options={}, block)
+      @folder     = path.realpath
+      @component  = component
+      @options    = DEFAULT_OPTIONS.merge(options)
+      @block      = block
+      @files      = OrderedSet.new
+      @implicitly_load_all_files = true
+    end
+    
+    # Override eql? so two folders with the same path will be
+    # considered equal by ordered set.
+    def eql?(other)
+      other.folder == @folder
+    end
+    
+    # Override hash so two folders with the same path will result
+    # in the same hash value.
+    def hash
+      @folder.hash
+    end
+    
+    # Load a folders definition and files after the set of components
+    # has been defined. For folders provided a block, the block is
+    # run in the context of this folder (allowing 'file' to be called).
+    # Otherwise the folder is scanned to produce an initial set of files
+    # and resources provided by this folder.
+    def load
+      if @block.nil?
+        self.reload_file_set
+      else
+        instance_eval &@block
+        @block = nil # prevent the block from being run twice
+      end
+    end
+    
+    # True if the folder uses nested namespaces
+    def nested_namespaces?
+      @options[:nested_namespaces]
+    end
+    
+    # True if the folder is reloadable
+    def reloadable?
+      @options[:reloadable]
+    end
+    
+    # Return the 'base' folder for a file contained within this
+    # folder. For instance, a folder with nested namespaces would
+    # return the path to a file from the root folder. Without
+    # namespaces, the relative path to a file would be the enclosing
+    # folder of the file. i.e relative path to framework/a/b.rb (where
+    # framework is the root folder) would return 'a/b.rb' for a
+    # nested namespace folder, or just 'b.rb' for a non nested
+    # namespace folder.
+    def relative_path_to(path)
+      if nested_namespaces?
+        path.relative_path_from(@folder)
+      else
+        path.basename
+      end
+    end
+    
+    # Explicitly include a file from this folder. If you use this
+    # method, only files included by this method will be loaded.
+    # If you do not use this method, all files within this folder
+    # will be accessible. For this reason, you probably want to
+    # separate out files which need to be defined this way into a
+    # folder separate to the majority of your source files. Options
+    # may be:
+    # * provides (required): an array of symbols, or a symbol
+    #   inidicating the name of the resource(s) provided by the file
+    def file(name, options={})
+      @implicitly_load_all_files = false
+      file = Impromptu::File.new(@folder.join(*name).realpath, self, options[:provides])
+      @files.push(file).add_resource_definition
+    end
+    
+    # Reload the files provided by this folder. If the folder
+    # is tracking a specific set of files, only those files
+    # will be reloaded. Otherwise, the folder is scanned again
+    # and any previously unseen files loaded, existing files
+    # reloaded, and removed files unloaded.
+    def reload
+      reload_file_set if @implicitly_load_all_files
+      @files.each {|file| file.reload_if_modified}
+    end
+    
+    # Determine changes between the set of files this folder
+    # knows about, and the set of files existing on disk. Any
+    # files which have been removed are unloaded (and their
+    # resources reloaded if other files define the resources
+    # as well), and any new files insert their resources in to
+    # the known resources tree.
+    def reload_file_set
+      return unless @implicitly_load_all_files
+      old_file_set = @files.to_a
+      new_file_set = []
+      changes = false
+      
+      # find all current files and add them if necessary
+      @folder.find do |path|
+        next unless source_file?(path)
+        file = Impromptu::File.new(path.realpath, self)
+        new_file_set << file
+        unless @files.include?(file)
+          changes = true
+          @files.push(file).add_resource_definition
+        end
+      end
+
+      # remove any files which have been deleted
+      deleted_files = old_file_set - new_file_set
+      deleted_files.each {|file| @files.delete(file).remove}
+      changes = true if deleted_files.size > 0
+      
+      # refreeze each files association lists if the set of
+      # files has changed
+      if changes
+        @files.each do |file|
+          file.refreeze
+        end
+      end
+    end
+    
+    
+    private
+      # True if the path represents a file with an extension known to
+      # implement resources.
+      def source_file?(path)
+        path.file? && SOURCE_EXTENSIONS.include?(path.extname[1..-1])
+      end
+  end
+end

data/lib/impromptu/impromptu.rb

@@ -0,0 +1,81 @@
+module Impromptu
+  # Resources are represented in a tree, with the root_resource
+  # representing the Object object. All resources are children
+  # of this resource.
+  def self.root_resource
+    @root_resource ||= Resource.new(:Object, nil)
+  end
+  
+  # The set of components known to Impromptu
+  def self.components
+    @components ||= ComponentSet.new
+  end
+  
+  # Call update to reload any folders (and associated files) which
+  # have been marked as reloadable. Any modified files will be
+  # reloaded, any new files will have their assiciated resources
+  # inserted in the resource tree, and any removed files will be
+  # unloaded.
+  def self.update
+    components.each do |component|
+      component.folders.each do |folder|
+        folder.reload if folder.reloadable?
+      end
+    end
+  end
+  
+  # Reset Impromptu by removing all known components and resources.
+  # This should rarely be used in a running application and mainly
+  # exists to allow the test framework to run the same setup code
+  # multiple times without changing stale components.
+  def self.reset
+    # unload all resources
+    unless @root_resource.nil?
+      @root_resource.children.each_value do |resource|
+        resource.unload
+      end
+    end
+    
+    # reset lists to nil
+    @root_resource = nil
+    @components = nil
+    @base = nil
+  end
+
+  # Parse component definition files, or create components as
+  # necessary directly from the supplied block. The block is run
+  # in the context of the Impromptu module allowing you to call
+  # 'component' directly without reference to Impromptu.
+  def self.define_components(base=nil, &block)
+    # load the component definitions
+    raise "No block supplied to define_components" unless block_given?
+    @base = base || Pathname.new('.').realpath
+    instance_eval &block
+    
+    # now that we have a complete file/resource graph, freeze
+    # the associations at this point (will be unfrozen for reloads)
+    components.each do |component|
+      component.freeze
+    end
+  end
+
+  # Open and run a file defining components. The folder containing
+  # the file is used as the 'base' folder, and folder references
+  # within components are assumed to be relative to this base.
+  def self.parse_file(path)
+    @base = Pathname.new(path).realpath.dirname
+    ::File.open(path) do |file|
+      instance_eval file.read
+    end
+  end
+
+  # Define and create a new component. The name of the component
+  # must be unique (otherwise you will get a reference to the
+  # existing component), and the block supplied is run in the context
+  # of the newly created component.
+  def self.component(name, &block)
+    component = components << Component.new(@base, name)
+    component.instance_eval &block if block_given?
+    component.folders.each {|folder| folder.load}
+  end  
+end

data/lib/impromptu/ordered_set.rb

@@ -0,0 +1,49 @@
+module Impromptu
+  class OrderedSet
+    include Enumerable
+
+    def initialize
+      @items_hash = {}
+      @items_list = []
+    end
+    
+    def <<(item)
+      unless self.include?(item)
+        @items_hash[item] = item
+        @items_list << item
+      end
+      @items_hash[item]
+    end
+    alias :push :<<
+    
+    def merge(items)
+      items.each {|item| self.<< item}
+    end
+    
+    def delete(item)
+      self.include?(item) or return nil
+      @items_hash.delete(item)
+      @items_list.delete(item)
+    end
+
+    def include?(item)
+      @items_hash.has_key?(item)
+    end
+
+    def to_a
+      @items_list.dup
+    end
+    
+    def each(&block)
+      @items_list.each {|item| yield item}
+    end
+    
+    def size
+      @items_list.size
+    end
+    
+    def empty?
+      @items_list.empty?
+    end
+  end
+end

data/lib/impromptu/resource.rb

@@ -0,0 +1,195 @@
+module Impromptu
+  # Resources represent the modules or classes that are tracked by
+  # Impromptu and which can be lazy loaded. You should never create
+  # resources yourself - use component definitions to define folders
+  # of files which will implement resources.
+  class Resource
+    attr_reader :name, :base_symbol, :files, :children, :parent
+    
+    def initialize(name, parent)
+      @name         = name.to_sym
+      @parent       = parent
+      @base_symbol  = @name.base_symbol
+      @files        = OrderedSet.new
+      @children     = {}
+      @reference    = nil
+      @namespace    = false
+      @implicitly_defined = true
+    end
+    
+    # Override eql? so two resources with the same name will be
+    # considered equal by ordered set. Names are fully namespaced
+    # so will always be unique.
+    def eql?(other)
+      other.name == @name
+    end
+    
+    # Override hash so two resources with the same name will result
+    # in the same hash value. Names are fully namespaced so will
+    # always be unique.
+    def hash
+      @name.hash
+    end
+    
+    # Attempts to retrieve a reference to the object represented by
+    # this resource. If the resource is unloaded, nil is returned.
+    def reference
+      return Object if root?
+      return nil unless @parent && @parent.reference
+      @reference ||= @parent.reference.const_get(@base_symbol)
+    end
+    
+    # Reload the implementation of this resource from all files being
+    # tracked for this resource. Call this method if you are manually
+    # managing file tracking, and need to guarantee all files for this
+    # resource have been loaded. It is normally unecessary to call this
+    # if you rely on the autoloader and reloader.
+    def reload
+      @parent.reload unless @parent.loaded?
+      if @implicitly_defined
+        self.unload
+        Object.module_eval "module #{@name}; end"
+      else
+        @files.first.reload
+      end
+    end
+    
+    # Unload the resource by undefining the constant representing it.
+    # Any resources contained within this resource will also be
+    # unloaded. This allows the resource to be garbage collected.
+    def unload
+      return unless loaded?
+      @children.each_value {|child| child.unload}
+      @parent.reference.send(:remove_const, @base_symbol)
+      @reference = nil
+    end
+    
+    # Start tracking a file which implements this resource. If the
+    # file has already been added it won't be added a second time.
+    # This method does not load the added file, so the definition
+    # of the resource will be incomplete until reload is called.
+    def add_file(file)
+      @files << file
+      @implicitly_defined = false
+    end
+    
+    # Un-track a file implementing this resource. If the file was
+    # never tracked, no error is raised. This does not reload the
+    # resource, so the resource will be based on a stale definition
+    # if it was previously loaded.
+    def remove_file(file)
+      @files.delete(file)
+      @implicitly_defined = true if @files.size == 0 && namespace?
+    end
+    
+    # True if no files have been associated with this resource. In
+    # this case, loading the resource will be achieved by creating
+    # a blank module with the name of the resource. If any files
+    # have been associated, they will be loaded instead, and this
+    # method will return false.
+    def implicitly_defined?
+      @implicitly_defined
+    end
+    
+    # True if this resource represents a module acting as a
+    # namespace.
+    def namespace?
+      @namespace
+    end
+    
+    # Mark a resource as representing a module acting as a
+    # namespace.
+    def namespace!
+      @namespace = true
+    end
+    
+    # True if this resource is the parent of any resources.
+    def children?
+      !@children.empty?
+    end
+    
+    # Add a child resource to this resource. This does not load the
+    # resource. This should only be called by get_or_create_child.
+    def add_child(resource)
+      @children[resource.base_symbol] = resource
+    end
+    
+    # Remove a reference to a child resource. This does not unload
+    # the object, but is called automatically by unload on its parent
+    # resource.
+    def remove_child(resource)
+      @children.delete(resource.base_symbol)
+    end
+    
+    # In most instances, this method should only be called on the
+    # root resource to traverse the resource tree and retrieve or
+    # create the specified resource. Name must be a symbol.
+    def get_or_create_child(name)
+      return nil unless name.is_a?(Symbol)
+      current = self
+      
+      name.each_namespaced_symbol do |name|
+        # attempt to get the current resource
+        child_resource = current.child(name.base_symbol)
+        
+        # create the resource if needed
+        if child_resource.nil?
+          child_resource = Resource.new(name, current)
+          current.add_child(child_resource)
+        end
+        
+        # the next current resource is the one we just created or retrieved
+        current = child_resource
+      end
+      
+      # after iterating through the name, current will be the resulting resource
+      current
+    end
+    
+    # Walks the resource tree and returns the resource corresponding
+    # to name (which must be a symbol and can be namespaced). If the
+    # resource doesn't exist, nil is returned
+    def child(name)
+      return nil unless name.is_a?(Symbol)
+      return @children[name] if name.unnested?
+      
+      # if the name is nested, walk the resource tree to return the
+      # resource under this branch. rerturn nil if we reach a
+      # branch which doesn't exist
+      nested_symbols    = name.nested_symbols
+      top_level_symbol  = nested_symbols.first
+      further_symbols   = nested_symbols[1..-1].join('::').to_sym
+      return nil unless @children.has_key?(top_level_symbol)
+      @children[top_level_symbol].child(further_symbols)
+    end
+    
+    # Walks the resource tree to determine if the resource referred
+    # to by name (which must be a symbol, and may be namespaced) is
+    # known by Impromptu.
+    def child?(name)
+      !self.child(name).nil?
+    end
+    
+    # Unload and remove all references to this resource.
+    def remove
+      unload
+      @parent.remove_child(self) if @parent
+    end
+    
+    # True if this resource is the root resource referring to Object.
+    def root?
+      @parent.nil?
+    end
+    
+    # True if this resource exists as a constant in its parent.
+    # This does not guarantee that every file implementing this
+    # resource has been loaded, however, so an incomplete instance
+    # may exist. If you rely on the autoloader and reloader this
+    # will not occur.
+    def loaded?
+      return true if root?
+      return false unless @parent && @parent.loaded? && @parent.reference
+      parent.reference.constants.include?(@base_symbol)
+    end
+  end
+end