kodekopelli 0.8.0

data/examples/treemenu/generated/README.txt

@@ -0,0 +1 @@
+This folder contains all content generated by Kodekopelli processing.

data/examples/treemenu/templates/authorized.txt

@@ -0,0 +1 @@
+<authz:authorize ifAnyGranted="<%= att('roles') %>"><%= child_output %></authz:authorize>

data/examples/treemenu/templates/menu_category.txt

@@ -0,0 +1,4 @@
+<li><% unless att('url',nil).nil? %><a href="<%= att('url') %>"
+target="<%= att('target') %>"
+><% end %><%= h att('text') %><% unless att('url',nil).nil? %></a><% end %><br />
+<%= child_output %></li>

data/examples/treemenu/templates/menu_item.txt

@@ -0,0 +1,3 @@
+<li><% unless att('url',nil).nil? %><a href="<%= att('url') %>"
+target="<%= att('target') %>"
+><% end %><%= h att('text') %><% unless att('url',nil).nil? %></a><% end %></li>

data/examples/treemenu/templates/simple_menu.txt

@@ -0,0 +1,3 @@
+<ul><% child_iterator { |current_child, text| %>
+  <%= text %><% } %>
+</ul>

data/lib/kodekopelli.rb

@@ -0,0 +1,56 @@
+begin
+  require 'erb'
+  require 'rexml/document'
+
+rescue LoadError
+  #  require 'rubygems'
+  #  require_gem 'somethin', '>=1.1.1'
+end
+
+require File.dirname(__FILE__) + '/kodekopelli/expandable_properties'
+require File.dirname(__FILE__) + '/kodekopelli/file_generator'
+require File.dirname(__FILE__) + '/kodekopelli/frozen_key_hash'
+require File.dirname(__FILE__) + '/kodekopelli/minimal_logger'
+require File.dirname(__FILE__) + '/kodekopelli/properties_file'
+require File.dirname(__FILE__) + '/kodekopelli/util'
+
+module Kodekopelli
+  def Kodekopelli.logo # :nodoc:
+    buf = "\n"
+    buf += "                            K                      \n"
+    buf += "                            ODE   KO               \n"
+    buf += "                             PEL  LI   K           \n"
+    buf += "                     ODEKOP   EL  LI   KO          \n"
+    buf += "                         DEK   O  PE   LL          \n"
+    buf += "                           IK  OD EK   OP          \n"
+    buf += "                 ELLIKODE   KO PELL   IK           \n"
+    buf += "                 O     DEK  OPELLIK ODE            \n"
+    buf += "                         KOPELLIKODEK              \n"
+    buf += "                          OPELLIKODEK              \n"
+    buf += "                  OPELLIKODEKOPELLIKOD             \n"
+    buf += "               EKOPELLIKODEKOPELLIKOD              \n"
+    buf += "             EKOPELLIKODE  KOPELLIKOD              \n"
+    buf += "           EKOPELLIKODEK     OPELLI                \n"
+    buf += "          KODEKOPELLIKOD       EK                  \n"
+    buf += "         OPELLIKODEKOPELL      IKO                 \n"
+    buf += "        DEKOPELLIKODEKOPE     LLI                  \n"
+    buf += "        KODEPELLIKODE  KOPELLIKODE                 \n"
+    buf += "        KOPELLIKODEKOPEL        LI                 \n"
+    buf += "        KODEKOPE    LLIKODEKOPELLIK                \n"
+    buf += "        ODEKOPELL                IK                \n"
+    buf += "         ODEKOPELL               IK                \n"
+    buf += "         ODEKOPELLI              KOD               \n"
+    buf += "          EKOPELLIKODE            KO               \n"
+    buf += "           PELLIKODEKOPELLIK      OD               \n"
+    buf += "            EKOPELLIKODEKOPEL                      \n"
+    buf += "             LIKODEKOPEL  LI                       \n"
+    buf += "              KODEKOP     ELLIKOD                  \n"
+    buf += "                EKOPE     LLIKO                    \n"
+    buf += "                   DEK                             \n"
+    buf += "                 OPELL            TM               \n"
+    buf += "                IKODEKOP                           \n"
+    buf += "                 ELLIKOD                           \n"
+    buf += "\n"
+    buf
+  end
+end

data/lib/kodekopelli/expandable_properties.rb

@@ -0,0 +1,63 @@
+module Kodekopelli # :nodoc:
+  # This module encapsulates functionality related to
+  # manipulating expandable properties.  In this context,
+  # <em>expandable properties</em> refer to those properties
+  # that may contain as substrings other properties
+  # to be substituted from an arbitrary property
+  # store, like a _Hash_.
+  #
+  # === Example Properties
+  #   property.not.expandable=world
+  #
+  #   property.expandable=Hello, ${property.not.expandable}!  # => Hello, world!
+  #
+  #   property.nested.expandables=Not another ${property.expandable}.
+  #   # => Not another Hello, world!
+  #
+  # Please note that the order of the properties above is very important.
+  # For example, if the property keyed by <em>property.expandable</em>
+  # had been listed before property <em>property.not.expandable</em>,
+  # its value would have remained 
+  # <code>Hello, ${property.not.expandable}!</code> with no
+  # <em>expansions</em> being performed.
+  module ExpandableProperties #
+    
+  # Given a property value that may or may not contain expansion directives of the form ${property key}
+  # and a hash containing pre-existing properties, this function returns a string with property
+  # values substituted for the expansion directives.
+  #
+  # :call-seq:
+  #  ExpandableProperties.replace_expandables(string, hash) -> string
+  #
+  def ExpandableProperties.replace_expandables(property_value, property_hash)
+    if(property_value.nil? || property_hash.nil?)
+      raise "Both a property value and property hash must be provided."
+    end
+        
+    modified_value = String.new(property_value)
+    
+    expandables_in_property_value(modified_value).each {|current_expandable|
+      expand_if_present!(current_expandable, modified_value, property_hash[current_expandable])
+    }
+    
+    modified_value
+  end
+    
+  private
+  
+  # Given a string, returns an array of those keys that should
+  # be used for expansion,
+  def ExpandableProperties.expandables_in_property_value(anystring)
+    anystring.scan(/\$\{[^\}]*\}/).each {|current| current.chop!.slice!("${")}
+  end
+
+  # Given the name of an expandable name, a property value containing the expandable, and a replacement value,
+  # modifies the property value by substituting the replacement valuable for the expandable.
+  def ExpandableProperties.expand_if_present!(expandable_name,  property_value, replacement_value)
+    unless replacement_value.nil? || replacement_value.empty?
+      property_value.gsub!("${#{expandable_name}}", replacement_value)
+    end
+  end
+
+  end
+end

data/lib/kodekopelli/file_generator.rb

@@ -0,0 +1,726 @@
+module Kodekopelli # :nodoc:
+  # The _FileGenerator_ class coordinates the necessary
+  # actions to generate output files from one or more definitions
+  # files.
+  class FileGenerator #
+    require 'optparse'
+    require 'webrick'
+    include WEBrick
+    require 'erb'
+    include ERB::Util
+  
+    attr_accessor :logger
+    
+    # Returns a new _FileGenerator_.
+    #
+    # :call-seq:
+    #   FileGenerator.new( properties_hash=nil ) -> file generator
+    #
+    def initialize(properties_hash = nil)
+      # Stores properties for property and attribute value expansions
+      # and system configuration
+      @property_hash = Kodekopelli::FrozenKeyHash.new
+      
+      unless(properties_hash.nil?)
+        properties_hash.each_pair { |key,value|
+          @property_hash[key] = value
+        }
+      end
+      
+      # Tracks attributes defined in the definitions
+      # file(s); also provides for nested contexts.
+      @context_stack = []
+    
+      # Allows for node-specific context creation
+      @node_stack = []
+
+      # Context containing those attributes that
+      # are relevant to the node currently being
+      # processed.
+      @current_context = {}
+      
+      @logger = MinimalLogger.new
+    end
+
+    # Element names
+    $ELEMENT_COMPOSITE = 'composite'
+    $ELEMENT_FILE = 'file'
+    $ELEMENT_FILE_GROUP = 'filegroup'
+    $ELEMENT_ATTRIBUTE = 'attribute'
+    $ELEMENT_INCLUDE = 'include'
+    $ELEMENT_TEMPLATE = 'template'
+    $ELEMENT_PROPERTY = 'property'
+    $ELEMENT_ROOT = 'kodekopelli'
+    
+    # Attribute names
+    $ATTRIBUTE_ENVIRONMENT = 'environment'
+    $ATTRIBUTE_FILE = 'file'
+    $ATTRIBUTE_LOCATION = 'location'
+    $ATTRIBUTE_NAME = 'name'
+    $ATTRIBUTE_TEMPLATE = 'template'
+    $ATTRIBUTE_VALUE = 'value'
+    
+    # Property names
+    $KODEKOPELLI_VERSION = "0.8.0"
+    $KODEKOPELLI_VERSION_PROPERTY = 'kodekopelli.version'
+    $KODEKOPELLI_START_TIME_PROPERTY = 'kodekopelli.start.time'
+        
+    def run(runtime_args) # :nodoc:
+      properties_file = nil
+      
+      opts = OptionParser.new
+      
+      opts.banner = "Usage: kodekopelli [options] [configfile [configfile2 [configfile3] ...]]"
+      opts.separator ""
+      opts.separator "Core Options:"
+        
+      opts.on("-h", "--help", "print this message") { 
+        puts opts.to_s
+        return
+      }
+      
+      opts.on("--version", "print the version information and exit") {
+	puts "Kodekopelli version #{$KODEKOPELLI_VERSION}"
+	return
+      }
+      
+      opts.on("-q", "--quiet", "be extra quiet in log messages") {
+        @logger.silent = true 
+      }
+      
+      opts.on("-v", "--verbose", "be extra verbose in log messages") {
+        @logger.verbose = true 
+      }
+      
+      opts.on("-l", "--logo", "print the Kodekopelli logo and exit") {
+        puts Kodekopelli.logo
+        return
+      }
+      
+      opts.on("--props k1=v1,k2=v2,...", Array,
+        "use the property key/value pair(s)", "specified") do |properties|
+        properties.each { |current_property|
+          first_delim_index = current_property.index('=')
+          if(first_delim_index > 0)
+            # Don't bother processing properties that don't have
+            # delimiters or in which no property name was
+            # specified.
+            current_property_key = current_property[0,first_delim_index]
+            current_property_value = current_property[first_delim_index + 1, current_property.length-1]
+            
+           @property_hash[current_property_key]= current_property_value
+            
+          end
+         }
+      end
+      
+      opts.on("--propsfile file", "load all properties from file with --props", "taking precedence") do |propsfile|
+        properties_file = propsfile
+      end
+      
+      opts.separator ""
+      opts.separator "Other Options:"
+      
+      opts.on("--server [port]", Integer, "launch an HTTP server with the current",
+                 "folder as the context root using,", "optionally, the port specified",
+                 "(defaults to port 80)") do |port|
+        port_number = port || 80
+        
+        s = HTTPServer.new(
+          :Port         => port_number,
+          :DocumentRoot => Dir::pwd
+        )
+
+        trap("INT") {
+        @logger.info("Shutting down HTTP server listening on port [#{port_number}]...")
+        s.shutdown 
+        }
+        
+        @logger.info("Starting HTTP server listening on port [#{port_number}]...")
+        @logger.info("Context root location:  [#{Dir::pwd}]")
+        s.start
+
+        return
+      end
+      
+      opts.on("--system", "display all system properties available to", "Kodekopelli and exit") {
+        puts "*** SYSTEM PROPERTIES (#{Time.now.to_s}) ***"
+        puts sprintf("%-30s     %s", "<KEY>", "<VALUE>")
+        ENV.to_hash.each_pair {|key,value|
+          puts sprintf("%-30s => %s", key, value)
+        }
+        return
+      }
+      
+      # Perform a destructive parse, leaving only the
+      # configuration files, if any were specified.
+      begin
+        opts.parse!(runtime_args)
+      rescue => cl_err
+        puts "Unable to process command line options:  #{cl_err.to_s}"
+        puts opts.to_s
+        exit(1)
+      end
+      
+      unless(properties_file.nil?)
+        digest_properties_file(properties_file)
+      end
+      
+      if(runtime_args.size > 0)
+        begin
+          process(runtime_args)
+        rescue => err
+          @logger.always("Root cause:  #{err.to_s}")
+          @logger.always("Build failed.")
+          exit(1)
+        end
+      else
+        puts "No Kodekopelli configuration files specified."
+        puts opts.to_s
+      end
+    end
+    # Processes one or more Kodekopelli definitions files,
+    # given an array of file locations.
+    #
+    # :call-seq:
+    #   process(array)
+    #
+    def process(files)
+      @logger.raw(Kodekopelli.logo)
+      files.each { |current_file|
+        process_definitions(current_file)
+      }
+    end
+    
+    protected
+    
+    def att(key, default = '')
+      @current_context[key] || default
+    end
+    
+    def prop(key, default = '')
+      @property_hash[key] || default
+    end
+    
+    def prop_att(key, default = '')
+      prop(key, nil) || att(key, nil) || default
+    end
+    
+    def att_prop(key, default = '')
+      att(key, nil) || prop(key, nil) || default
+    end
+    
+    def j(javascript)
+      Kodekopelli::Util.escape_javascript(javascript)
+    end
+    
+    def include_file(filename, process=true, ignore_if_missing=false)
+      # The location of the properties file may contain expandable property directives.  Replace any
+	  # that exist prior to attempting its retrieval.
+	  location = Kodekopelli::ExpandableProperties.replace_expandables(filename, @property_hash)
+      
+      contents = Kodekopelli::Util.file_contents(location, ignore_if_missing)
+      
+      if(process)
+        contents = process_erb(contents)
+      end
+      
+      contents
+    end
+    
+    def node_att(node, name, default = '')
+      value = node.attributes[name] || default
+      # The child attribute may contain expandable property directives.  Replace
+      # any that exist prior to returning.
+      Kodekopelli::ExpandableProperties.replace_expandables(value, @property_hash)
+    end
+    
+    def child_iterator
+      current = current_node
+      @logger.debug("Processing node [" + current.name + "]...")
+      result = ''
+      
+      current.elements.each { |node|
+        text = ''
+	    if(node.name == $ELEMENT_INCLUDE)
+	      text = process_include(node)
+	      result += yield(node, text)
+	    else
+	      if(node.name == $ELEMENT_COMPOSITE)
+	        text = process_composite(node)
+	      else
+	        text = process_template(node)
+	      end
+	      result += yield(node, text)
+	    end
+	  }
+	result
+    end
+    
+    def child_output
+      result = ''
+      child_iterator { |node, text|
+        result += text
+      }
+      result
+    end
+    
+    private
+    
+    # Given a reference to an XML representation of the
+    # definitions file, initializes the properties to be used during
+    # its processing.
+    def initialize_properties(doc)
+      @logger.debug("Initializing properties...")
+      
+      #  Iterate over the <property ... /> elements in the document, performing fine-grained
+      #  processing (via a call to process_property_element) for each.
+      doc.elements.each("#{$ELEMENT_ROOT}/#{$ELEMENT_PROPERTY}") { |current_element|
+        process_property_element(current_element)
+      }
+
+      # Always add the system (environment) properties to the property
+      # hash
+      expose_system_properties
+      
+      @logger.debug("Finished initializing properties.")
+    end
+    
+    def expose_system_properties(prefix='')
+      ENV.to_hash.each_pair { |key, value|
+	    @property_hash[prefix + key] = Kodekopelli::ExpandableProperties.replace_expandables(value, @property_hash)
+	  }
+	end
+    
+    # Performs fine-grained processing on a <property ... /> element, updating the
+    # property hash based upon the attributes provided.
+    def process_property_element(property_element)
+
+      # Retrieve the value of the "environment" attribute, if it was specified
+      environment_attribute_value = property_element.attributes[$ATTRIBUTE_ENVIRONMENT]
+      
+      # If the "environment" attribute was specified...  #
+      unless(environment_attribute_value.nil?)
+        # The attribute value may or may not end with a period ('.').  If it does, remove the period;
+	    # then, regardless, concatenate another period to serve as a separator between the user-specified
+	    # prefix and the environment attribute name suffix.
+        prefix = environment_attribute_value.chomp(".") + "."
+	    
+	    
+	    expose_system_properties(prefix)
+	    
+	    # No additional work is required for the current element.
+	    return
+      end
+      
+      # Retrieve the value of the "file" attribute, if it was specified
+      file_attribute_value = property_element.attributes[$ATTRIBUTE_FILE]
+      
+      # If the "file" attribute was specified...
+      unless(file_attribute_value.nil?)
+        digest_properties_file(file_attribute_value)
+            
+	    # No additional work is required for the current element.
+        return        
+      end
+      
+      # The "name" attribute is required when either of the "value" or "location" attributes is
+      # provided
+      name_attribute_value = property_element.attributes[$ATTRIBUTE_NAME]
+      
+      # Retrieve the value of the "location" attribute, if it was specified.
+      location_attribute_value = property_element.attributes[$ATTRIBUTE_LOCATION]
+      
+      # If the "location" attribute was specified...
+      unless(location_attribute_value.nil?)
+        if(name_attribute_value.nil?)
+          raise "A #{$ATTRIBUTE_NAME} attribute must be specified for property element [<#{$ELEMENT_PROPERTY} ... />] when the #{$ATTRIBUTE_LOCATION} attribute is specified."
+         end
+	 
+	    # The location may contain expandable property directives.  Replace any that exist prior to checking its
+	    # validity as a file or directory
+	    location = Kodekopelli::ExpandableProperties.replace_expandables(location_attribute_value, @property_hash)
+
+	    unless File.exists?(location)
+	      raise "Unable to locate file or folder for location [#{location}] with name [#{name_attribute_value}].  Current working directory is [#{File.expand_path('.')}].  Properies: [#{@property_hash.to_s}]."
+	    end
+	    
+	    @property_hash[name_attribute_value] = location
+	
+	    # No additional work is required for the current element.
+        return
+      end
+
+      # Retrieve the value of the "value" attribute, if it was specified
+      value_attribute_value = property_element.attributes[$ATTRIBUTE_VALUE]
+      
+      if(name_attribute_value.nil?)
+        raise "A #{$ATTRIBUTE_NAME} attribute must be specified for property element [<#{$ELEMENT_PROPERTY} ... />]"
+      end
+
+      if(value_attribute_value.nil?)
+        raise "A #{$ATTRIBUTE_VALUE} attribute must be specified for property element [<#{$ELEMENT_PROPERTY} ... />]"
+      end
+      
+      # Add the property value to the property hash, keyed by the property name
+      @property_hash[name_attribute_value] = Kodekopelli::ExpandableProperties.replace_expandables(value_attribute_value, @property_hash)
+      
+    end
+    
+    def digest_properties_file(filename)
+      # The location of the properties file may contain expandable property directives.  Replace any
+	  # that exist prior to attempting its retrieval.
+	  location = Kodekopelli::ExpandableProperties.replace_expandables(filename, @property_hash)
+      @logger.debug("Loading properties from file [#{location}]...")
+	
+	  # Create a hash containing those simple properties defined in the properties file
+	  properties_file_hash = Kodekopelli::PropertiesFile.to_hash(location)
+	
+	  # For each property defined in the properties file, add it to the
+	  # properties hash.
+	  properties_file_hash.each_pair { |key, value|
+	    @property_hash[key] = Kodekopelli::ExpandableProperties.replace_expandables(value, @property_hash)
+      }
+      @logger.debug("Finished loading properties from file [#{location}].")
+    end
+    
+    # Adds any global attributes specified in the definitions file as top-level
+    # context attributes.
+    def initialize_global_attributes(doc)
+      @logger.debug("Initializing global attributes...")
+      
+      # Hash to hold global attributes
+      values = Kodekopelli::FrozenKeyHash.new
+      
+      #  Iterate over the <attribute ... /> elements in the document, performing fine-grained
+      #  processing for each.
+      doc.elements.each("#{$ELEMENT_ROOT}/#{$ELEMENT_ATTRIBUTE}") { |attribute_element|
+        # Retrieve the value of the "name" attribute
+        name_attribute_value = attribute_element.attributes[$ATTRIBUTE_NAME]
+        
+        # Retrieve the value of the "attribute" attribute
+        value_attribute_value = attribute_element.attributes[$ATTRIBUTE_VALUE]
+
+        if(name_attribute_value.nil?)
+          raise "A #{$ATTRIBUTE_NAME} attribute must be specified for property element [<#{$ELEMENT_ATTRIBUTE} ... />]"
+        end
+
+        if(value_attribute_value.nil?)
+          raise "A #{$ATTRIBUTE_VALUE} attribute must be specified for property element [<#{$ELEMENT_ATTRIBUTE} ... />]"
+        end
+        
+      	# The attribute value may contain expandable property directives.  Replace any
+	    # that exist prior to storing it in the context
+        values[name_attribute_value] = Kodekopelli::ExpandableProperties.replace_expandables(value_attribute_value, @property_hash)
+      }
+      
+      push_hash_context(values)
+      @logger.debug("Finished initializing global attributes.")
+    end
+
+    def process_composite(composite_node)
+      @logger.debug("Attempting to process composite element...")
+      composite_results = ''
+      
+      unless(composite_node.elements.size > 0)
+        raise "No child elements were specified for composite element [#{composite_node.to_s}]"
+      end
+      
+      push_context(composite_node)
+      
+      if(composite_node.attributes[$ATTRIBUTE_TEMPLATE].nil?)
+      #   raise "No template attribute was specified for composite element [#{composite_node.to_s}]"
+        composite_results = process_children(composite_node)
+      else
+        # Retrieve the value of the "template" attribute
+        template_attribute_value = composite_node.attributes[$ATTRIBUTE_TEMPLATE]
+      
+        # The location may contain expandable property directives.  Replace any that exist prior
+        # to retrieving its contents.  
+        location = Kodekopelli::ExpandableProperties.replace_expandables(template_attribute_value, @property_hash)
+      
+        @logger.debug("Attempting to process composite element with template [#{location}]...")
+        erb_script = Kodekopelli::Util.file_contents(location)
+      
+        # Compile the ERB script and run it
+        composite_results = process_erb(erb_script)
+      end
+      
+      @logger.debug("Finished processing composite element.")
+      
+      pop_context
+      composite_results
+    end
+    
+    # Process the contents of the erb_script provided,
+    # returning the results.
+    def process_erb(erb_script)
+      script = erb_script || ''
+      begin 
+        erb = ERB.new(script)
+        erb_results = erb.result(binding)
+      rescue => err
+        raise err #, "There was a problem interpreting the ERB script."
+      end
+      erb_results
+    end
+    
+    # Given a template node, process its content using the template specified or, optionally,
+    # processes its content directly.
+    def process_template(node)
+      # By default, the erb script is equal to the element data
+      template_element_content = node.text
+      
+      # Retrieve any inline template element content that
+      # may exist, defaulting to the empty string
+      erb_script = template_element_content || ''
+      
+      # If no template element content was found, retrieve the template
+      # attribute value specified in the current template element.
+      if(erb_script == '')
+        # Retrieve the value of the "template" attribute, if it was specified.
+        template_attribute_value = node.attributes[$ATTRIBUTE_TEMPLATE]
+         
+        # If no template attribute was found for the current template element,
+        # see if it exists in the contexgt...
+        if(template_attribute_value.nil?)
+          template_attribute_value = att($ATTRIBUTE_TEMPLATE, nil)
+          if(template_attribute_value.nil?)
+            raise "No template location specified for element [#{node.to_s}]"
+          end
+        end
+        
+        # The location may contain expandable property directives.  Replace any that exist prior
+        # to retrieving its contents.  
+        location = Kodekopelli::ExpandableProperties.replace_expandables(template_attribute_value, @property_hash)
+      
+        @logger.debug("Attempting to process template [#{location}]...")
+        erb_script = Kodekopelli::Util.file_contents(location)
+        @logger.debug("Finished processing template [#{location}].")
+      end
+     
+      context = push_context(node)
+      
+      # Compile the ERB script and run it
+      erb_results = process_erb(erb_script)
+      
+      pop_context
+      erb_results
+    end
+ 
+    # Given an include node, retrieves the contents of the file as
+    # specified by its file attribute
+    #
+    # :call-seq:
+    #   process_include(node) -> file contents
+    #
+    def process_include(node, process=false)
+      filename = node.attributes[$ATTRIBUTE_FILE]
+      
+      # The location may contain expandable property directives.  Replace any that exist prior
+      # to retrieving its contents.  
+      location = Kodekopelli::ExpandableProperties.replace_expandables(filename, @property_hash)
+      
+      contents = Kodekopelli::Util.file_contents(location)
+      
+      if(process)
+        contents = process_erb(contents)
+      end
+      contents
+    end
+    
+    # Resets all contexts and other runtime artifacts to
+    # allow for processing a fresh definitions file
+    def reset_state
+      @logger.debug('Resetting state...')
+      
+      @property_hash.clear
+      @context_stack.clear
+      @node_stack.clear
+
+      @logger.debug('Reset complete.')
+    end
+    
+    # Returns a hash of the current context.
+    #
+    # :call-seq:
+    #   build_current_context -> hash
+    #
+    def build_current_context
+      # The context_stack instance attribute is an array of hashes
+      # containing 1 or more contexts, from oldest to newest.  Flatten
+      # it so that the more recent values take precedence over the
+      # older values.
+      @current_context = {}
+      @context_stack.each {|current_hash|
+        current_hash.each { |key, value|
+	  @current_context[ key ] = value
+        }
+      }
+      @current_context
+    end
+    
+    # Returns the topmost node on the node stack
+    # :call-seq:
+    #   current_node -> node
+    #
+    def current_node
+      @node_stack.last
+    end
+    
+    def process_children(node)
+      result = ''
+      # Iterate through the elements and process them
+	  node.elements.each { |current_node|
+	    if(current_node.name == $ELEMENT_TEMPLATE)
+	      result += process_template(current_node)
+	    end
+	    
+	    if(current_node.name == $ELEMENT_COMPOSITE)
+	      result += process_composite(current_node)
+	    end
+	    
+	    if(current_node.name == $ELEMENT_INCLUDE)
+	      result += process_include(current_node)
+	    end
+	  }
+	  result
+	end
+	  
+    # Given an XML node, adds a context to the stack
+    def push_context(node)
+      @node_stack.push(node)
+      # Create a hash of the attributes for this XML node
+      values = {}
+      
+      node.attributes.each { | key, value |
+      	  # The attribute value may contain expandable property directives.  Replace any
+	  # that exist prior to storing it in the context
+	  values[key] = Kodekopelli::ExpandableProperties.replace_expandables(value, @property_hash)
+      }
+      
+      push_hash_context(values)
+    end
+    
+    # Given a hash, adds a context to the stack
+    def push_hash_context(values)
+      # Add the has to the contet stack
+      @context_stack.push( values )
+      build_current_context
+    end
+    
+    # Pops the topmost context for a particular
+    # node, indicating that processing has completed
+    def pop_context
+      @node_stack.pop
+      @context_stack.pop
+    end
+    
+    def process_definitions(definitions_file)
+      @logger.info("Processing Kodekopelli file [#{definitions_file}]...")
+      unless File.exists?(definitions_file)
+        raise "Could not locate definitions file [#{definitions_file}]."
+      end
+      begin
+        doc = REXML::Document.new(File.open(definitions_file))
+      rescue
+        raise "Could not parse definition file [#{definitions_file}]."
+      end
+      generated_file_count = 0
+      # Process properties, if specified...
+      # Set Kodekopelli-specific properties
+      @property_hash[$KODEKOPELLI_VERSION_PROPERTY] = $KODEKOPELLI_VERSION
+      @property_hash[$KODEKOPELLI_START_TIME_PROPERTY] = Time.now
+      
+      property_elements = doc.root.elements[$ELEMENT_PROPERTY]
+      if(property_elements.nil?)
+        @logger.debug("No property [<#{$ELEMENT_PROPERTY} ... />] elements found.")
+      else
+        initialize_properties(doc)
+	    doc.root.elements.delete_all $ELEMENT_PROPERTY
+      end
+      @logger.debug("Kodekopelli Properties:\n#{@property_hash.to_s}")
+      
+      # Process globals, if specified...
+      global_attributes = doc.root.elements[$ELEMENT_ATTRIBUTE]
+      if(global_attributes.nil?)
+        @logger.debug("No global attribute [<#{$ELEMENT_ATTRIBUTE} ... />] elements found.");
+      else
+        initialize_global_attributes(doc)
+        doc.root.elements.delete_all $ELEMENT_ATTRIBUTE
+      end    
+      
+      # Start the context stack
+      push_context(doc.root)
+      
+      # Get the <filegroup>...</filegroup> nodes
+      filegroup_nodes = doc.root.elements
+      
+      filegroup_nodes.each { |current_filegroup_node| 
+        
+        file_nodes = current_filegroup_node.elements
+	    
+	    push_context(current_filegroup_node)
+	    
+	    file_nodes.each { |current_file_node|
+	      file_name = current_file_node.attributes[$ATTRIBUTE_NAME]
+	      
+	      # The location of the output file name may contain expandable property directives.  Replace any
+	      # that exist prior to attempting its retrieval.
+	      target = Kodekopelli::ExpandableProperties.replace_expandables(file_name, @property_hash)
+	  
+	      @logger.info("Generating file [#{target}]...")
+	      begin
+	        outfile = File.open(target, "w")
+	      rescue 
+	        raise "Unable to create output file #{target}"
+	      end
+
+          push_context(current_file_node)
+	      
+	      template_attribute_value = current_file_node.attributes[$ATTRIBUTE_TEMPLATE] || att($ATTRIBUTE_TEMPLATE, nil)
+	      
+          if(template_attribute_value.nil?)
+            if(current_file_node.elements.size == 0)
+              erb_script = current_file_node.text || ''
+              outfile.write(process_erb(erb_script))
+            else
+              # Iterate through the elements and process them
+	          outfile.write(process_children(current_file_node))
+	        end
+          else
+            # The location may contain expandable property directives.  Replace any that exist prior
+            # to retrieving its contents.  
+            location = Kodekopelli::ExpandableProperties.replace_expandables(template_attribute_value, @property_hash)
+      
+            @logger.debug("Attempting to process file element with template [#{location}]...")
+            erb_script = Kodekopelli::Util.file_contents(location)
+      
+            # Compile the ERB script and run it
+            outfile.write(process_erb(erb_script))
+            @logger.debug("Finished processing file element.")
+          end
+	      
+	      # Remove individual output file context
+	      pop_context
+	      outfile.close
+	      @logger.info("Finished generating file [#{target}].")
+	  
+	      generated_file_count += 1
+	    } # End individual output file iteration
+      
+      # Remove filegroup context
+      pop_context 
+      
+      } # End filegroup iteration
+	  
+      # Remove the root element context
+      pop_context
+      
+      @logger.info("#{generated_file_count} total files were generated.")
+      @logger.info("Finished processing Kodekopelli file [#{definitions_file}].")
+      
+      reset_state
+    end
+  end
+end