PageTemplate 1.1.2 → 1.2.0

data/lib/PageTemplate.rb~

@@ -0,0 +1,1004 @@
+#!/usr/local/bin/ruby -w
+
+# Use PageTemplate.rb to create output based on template pages and 
+# the code of your program.  This package is inspired by, but not 
+# quite like, Perl's HTML::Template package.  Its main intent is to 
+# separate design and code for CGI programs, but it could be useful 
+# in other contexts as well (Ex: site generation packages).
+#
+# See the README.txt file for the real documentation, such as it is.
+#
+# As a side note: if you are using PageTemplate in your projects, or 
+# add features to your copy, I'd love to hear about it.
+#
+
+############################################################
+  
+# Allows nested storage of variable names and values.
+class Namespace
+	
+  def initialize()
+    @global = {}
+    @nSpaces = []
+  end
+
+  # An alias for Namespace#set(key, value)
+  def []=(key, value)
+    self.set(key, value)
+  end
+
+  # An alias for Namespace#get(key)
+  def [](key)
+    return self.get(key)
+  end
+
+  # Saves a variable +key+ as the string +value+ in the global 
+  # namespace.
+  def set(key, value)
+    puts "Namespace setting global #{key} to #{value}" if $DEBUG
+    @global[key] = value
+  end
+
+  # Returns the first value found for +key+ in the nested namespaces.
+  # Returns nil if no value is found.
+  #
+  # Values are checked for in this order through each level of namespace:
+  # 
+  # * level.key
+  # * level.key()
+  # * level[key]
+  #
+  # If a value is not found in any of the nested namespaces, get()
+  # searches for the key in the global namespace.
+  def get(key)
+    value = nil
+    
+    @nSpaces.reverse.each do |ns|
+
+      if ns.respond_to?(":#{key}")
+        value = ns.send(":#{key}")
+      elsif ns.respond_to?("#{key}")
+        value = ns.send(key)
+      elsif ns.respond_to?("[]")
+        value = ns[key]
+      end
+      
+      break if value
+    end
+    
+    value = @global[key] unless value
+    puts "Namespace #{key}: #{value}" if $DEBUG
+    
+    return value
+  end
+
+  # A convenience method to test whether a variable has a true
+  # value. Returns nil if +flag+ is not found in the namespace, 
+  # or +flag+ has a nil value attached to it.
+  def true?(flag)
+    value = get(flag)
+    return nil unless value
+    
+    return value
+  end
+
+  # Nest namespaces by adding the object +namespace+ to the current set 
+  # of names.
+  def push(namespace)
+    @nSpaces.push(namespace)
+  end
+
+  # Un-nest namespaces by removing the most recently pushed object.
+  #
+  # Returns nil if there are no more namespaces to pop
+  def pop
+    @nSpaces.pop
+  end
+
+end
+
+############################################################
+
+# Command classes generate text output based on conditions which vary
+# between each class. Command provides an abstract base class to show
+# interface.
+class Command
+
+  # Subclasses of Command use the output method to generate their text
+  # output.  +namespace+ is a Namespace object, which may be 
+  # required by a particular subclass.
+  def output(namespace = nil)
+    raise NotImplementedError, 
+          "output() must be implemented by subclasses"
+  end
+
+  def to_s
+    return "#{self.class}"
+  end
+end
+
+# CommentCommand provides a mechanism for ignoring the contents
+# of a block.
+class CommentCommand < Command
+
+  def output(namespace = nil)
+    return nil
+  end
+
+end
+
+# BlockCommand provides a single interface to multiple Command
+# objects.
+class BlockCommand < Command
+
+  def initialize()
+    @commandBlock = []
+  end
+
+  # Return Commands held, as a string
+  def to_s
+    str = "BlockCommand: "
+    if @commandBlock 
+      @commandBlock.each { |c| str << "[" + c.to_s + "]"}
+    else
+      str << "Empty"
+    end
+    
+    return str
+  end
+  
+  # Returns the number of Commands held in this BlockCommand
+  def length
+    return @commandBlock.length
+  end
+
+  # Adds +command+ to the end of the BlockCommand's 
+  # chain of Commands.
+  #
+  # A TypeError is raised if the object being added is not a ((<Command>)).
+  def add(command)
+    if command.is_a?(Command)
+      @commandBlock << command
+    else
+      raise TypeError,
+            "BlockCommand.add: Attempt to add non-Command object"
+    end
+  end
+
+  # Applies Command#output(namespace) to each Command contained in this 
+  # object.  The output is returned as a single string.  If no output
+  # is generated, returns nil.
+  def output(namespace = nil)
+    text = ""
+    @commandBlock.each do |x| 
+      cOutput = x.output(namespace)
+      text += cOutput if cOutput
+    end
+    
+    return text unless text == ""
+  end
+end
+
+# A very simple Command which outputs a static string of text
+class TextCommand < Command
+
+  # Creates a TextCommand object, saving +text+ for future output.
+  def initialize(text)
+    @text = text
+  end
+
+  def to_s
+    return "#{self.type}: '#{@text}'"
+  end
+
+  # Returns the string provided during this object's creation.
+  def output(namespace = nil)
+    return @text
+  end
+end
+
+# A Command that is tied to a variable name.
+class ValueCommand < Command
+
+  # Creates the ValueCommand, with +value+ as the name of the variable
+  # to be inserted during output.
+  def initialize(value)
+    @value = value
+  end
+
+  # Requests the value of this object's saved value name from 
+  # +namespace+, and returns the string representation of that
+  # value to the caller.
+  def output(namespace)
+    return namespace.get(@value).to_s
+  end
+
+  def to_s
+    str = super.to_s
+    str << "(#{@value})"
+    return str
+  end
+end
+
+# The IfCommand generates output from an associated BlockCommand
+# if a flag variable is true.
+class IfCommand < ValueCommand
+  # Creates an IfCommand object, with +flag+ used as the value
+  # to check for truth, and +commandBlock+ as the BlockCommand to
+  # execute when the flag is true.
+  def initialize(flag, commandBlock)
+    super(flag)
+    @commands = commandBlock
+  end
+
+  # If +namespace+ has a true value for this Command's flag, returns
+  # the output generated by the CommandBlock. Otherwise, returns nil.
+  def output(namespace)
+    if namespace.true?(@value)
+      return @commands.output(namespace)
+    end
+  end
+
+  # Return a text representation of this command
+  def to_s
+    str = super.to_s
+    str << @commands.to_s
+    return str
+  end
+end
+
+# An UnlessCommand simplifies templates that need to use
+# a Block only if a condition is false
+class UnlessCommand < IfCommand
+  # If +namespace+ does not have a true value for this Command's flag, returns
+  # the output generated by the CommandBlock. Otherwise, returns nil.
+  def output(namespace)
+    unless namespace.true?(@value)
+      return @commands.output(namespace)
+    end
+  end
+end
+
+# An IfCommand with an alternate BlockCommand to use if the 
+# flag variable if false.
+class IfElseCommand < IfCommand
+
+  # Generates an IfElseCommand with +elseBlock+ as the 
+  # BlockCommand to execute when +flag+ is false.
+  def initialize(flag, ifBlock, elseBlock)
+    super(flag, ifBlock)
+    @elseCommands = elseBlock
+  end
+
+  # Returns the output of the if BlockCommand if +flag+ is true in
+  # +namespace+, or the output of the else BlockCommand otherwise.
+  def output(namespace)
+    result = super
+    unless result
+      result = @elseCommands.output(namespace)
+    end
+
+    return result
+  end
+
+  def to_s
+    str = super.to_s
+    str << " - ELSE " + @elseCommands.to_s
+    return str
+  end
+end
+
+# LoopCommand repeatedly steps through its CommandBlock for each item
+# in a array of hashes associated with the LoopCommand's variable.
+class LoopCommand < ValueCommand
+
+  # Creates a new LoopCommand asociated with +listName+ and using 
+  # +commandBlock+ as the command to be executed when output is 
+  # requested.
+  #
+  # *NOTE:*  The value associated with +listName+ in the caller's 
+  # Namespace must be an array of hashes.  Each hash should have 
+  # the same keys, but that is not required. (I can think of situations 
+  # where it wouldn't be an issue, so just think of 'identical keys' as a
+  # guideline)
+  def initialize(listName, commandBlock)
+    super(listName)
+    @commands = commandBlock
+  end
+
+  # Executes the object's CommandBlock for each item in the associated
+  # array of hashes.  This method nests namespaces, allowing local variables
+  # within the loop. Returns the combined output of each repetition, or
+  # nil if the loop value is false in +namespace+.
+  def output(namespace)
+    
+    return nil unless namespace.true?(@value)
+    
+    items = namespace.get(@value)
+    
+    return nil if items.empty?
+    
+    result = ""
+    
+    items.each_with_index do |item, index|
+      metavariables = Namespace.new()
+      metavariables['__FIRST__'] = true if index == 0
+      metavariables['__LAST__'] = true if index == items.length - 1
+      # Even-numbered index means an odd-numbered iteration. 
+      # Gotta love zero-based indexes.
+      metavariables['__ODD__'] = true if index % 2 == 0
+
+      namespace.push(metavariables)
+      namespace.push(item)
+      result += @commands.output(namespace)
+      namespace.pop()
+      namespace.pop()
+    end
+    
+    return result
+  end
+
+  def to_s
+    str = super.to_s
+    str << @commands.to_s
+    return str
+  end
+
+end
+
+# A LoopCommand with an alternate CommandBlock to execute 
+# if there is no loop associated with the Command variable does not exist.
+class LoopElseCommand < LoopCommand
+
+  # Generates a LoopElseCommand with a loop variable, a BlockCommand to
+  # execute if the loop exists, and a BlockCommand to execute if the
+  # loop does not exist.
+  def initialize(loopName, trueBlock, elseBlock)
+    super(loopName, trueBlock)
+    @elseCommands = elseBlock
+  end
+
+  # Returns the output of the loop BlockCommand if the loop exists, or the
+  # output of the else BlockCommand if not.
+  def output(namespace)
+    result = super
+    unless result
+      result = @elseCommands.output(namespace)
+    end
+    
+    return result
+  end
+
+  def to_s
+    str = super.to_s
+    str << " - NO " + @elseCommands.to_s
+    return str
+  end
+end
+
+# This module provides guidelines for the template parser.
+module Syntax
+
+  # Glossary holds regular expression patterns associated with markup in a
+  # PageTemplate document.  It enables the PageTemplate to tell the
+  # difference between regular document content and template markup.  It
+  # also defines the syntax for the available markup directives:
+  #
+  # === Syntax::Glossary read accessors
+  #
+  # [:directive]
+  # 	The regular expression object which describes a chunk of 
+  #	markup text.
+  # [:glossary]
+  #	A hash of regular expression objects, describing parser keys.
+  class Glossary
+    
+    attr_reader :directive, :glossary
+
+    # Creates a new Syntax::Glossary with regular expression +directive+, 
+    # and hash of regular expressions glossary, as defined above.
+    #
+    # +directive+ must have a single grouping, which holds the actual
+    # directive that is supposed to be processed (as opposed to the
+    # markers that "wrap" the directive)
+    #
+    # The following keys are required in glossary by a Syntax::Glossary
+    # object:
+    #
+    # * value 
+    # * ifopen
+    # * ifclose
+    # * ifbranch
+    # * loopopen
+    # * loopclose
+    # * loopbranch
+    #
+    # An ArgumentError is raised if glossary is missing any of these keys.
+    #
+    # You may add keys, but it is up to you to make the PageTemplate parse
+    # method understand their meaning.
+    def initialize(directive, glossary)
+      @directive = directive
+      checkGlossary(glossary)
+      @glossary = glossary
+    end
+
+    # Find out which parser directive corresponds to +text+.
+    # +text+ is the grouping found by a directive match.
+    #
+    # If no match is found, returns nil.
+    # If a match is found, returns an array of the parse command and
+    # variable associated with it (or the parse command and nil for the
+    # variable if there is no variable match).
+    def lookup(text)
+      command = nil
+      variable = nil
+      @glossary.each_key do |key|
+        if match = @glossary[key].match(text)
+          command = key
+          variable = match[1] if match[1]
+          break
+        end
+      end
+      
+      return nil if command == nil
+      return [command, variable]
+    end
+    
+    # Ensures that glossary contains all of the required keys.
+    private
+    def checkGlossary(glossary)
+      %w[ value 
+		ifopen ifclose ifbranch 
+		loopopen loopclose loopbranch
+		].each do |key|
+        unless glossary.has_key?(key)
+          raise ArgumentError,
+                "Syntax::Glossary:missing '#{key}' key"
+        end
+      end
+      
+      return true
+    end
+  end
+  
+  # This Syntax::Glossary is provided for those of us who 
+  # don't feel like defining our own syntax.
+  
+  # Here are the keys and patterns associated with Syntax::DEFAULT
+  
+  # * directive: /\[%(.+)%\]/
+  # * comment: /--.+?--/
+  # * value: /var (\w+)/
+  # * ifopen: /if (\w+)/
+  # * ifclose: /endif/
+  # * ifbranch: /else/
+  # * loopopen: /in (\w+)/
+  # * loopclose: /endin/
+  # * loopbranch: /no/
+  # * include: /include (\S+)/
+  
+  # For example +[%var title %]+ is a template directive to 
+  # insert the value of the variable 'title'.
+  
+  # Notice that I used a space before the closing braces.  This 
+  # Glossary doesn't require it, but I think it makes for a more readable 
+  # style.
+
+  DEFAULT = Syntax::Glossary.new( /\[%(.+?)%\]/,
+                                  'value'      => /^\s*var (\w+)\s*$/,
+                                  'comment'    => /^\s*--.+?--\s*$/,
+                                  'ifopen'     => /^\s*if (\w+)\s*$/,
+                                  'ifclose'    => /^\s*endif\s*$/,
+                                  'ifbranch'   => /^\s*else\s*$/,
+                                  'loopopen'   => /^\s*in (\w+)\s*$/,
+                                  'loopclose'  => /^\s*endin\s*$/,
+                                  'loopbranch' => /^\s*no\s*$/,
+                                  'include'    => /^\s*include (\S+)\s*$/
+                                  )
+
+########################################################################
+
+  # Uses a Syntax::Glossary to translate a string of text into a
+  # series of Commands.
+  class Parser
+
+    attr_reader :commands
+
+    def initialize(glossary, path=Dir.getwd)
+      @path = path
+      @syntax   = glossary
+      @commands = nil
+      @lastFile = nil
+      @mTime    = Time.at(0)
+    end
+
+    # Parse and compile a file containing PageTemplate directives.
+    def build(filename)
+      filename.untaint
+      if File.exists?(filename)
+        file = File.new(filename)
+      else
+        file = File.new(File.join(@path, filename))
+      end
+
+      # If this is a new file, or the file has been changed,
+      # parse and compile.
+      if filename != @lastFile or file.mtime < @mTime
+        reset
+        source    = file.readlines
+        parsed    = parse(source, filename)
+        @commands = compile(parsed, filename)
+        @lastFile = filename
+        @mTime    = file.mtime
+      end
+      
+      return 1 if @commands
+    end
+
+    # Returns the result of executing the Parser's internal compiled 
+    # CommandBlock, using ((|namespace||)).
+    def output(namespace = nil)
+      return @commands.output(namespace)
+    end
+
+    # Clear the Parser's CommandBlock.
+    def reset
+      @lastFile = nil
+      @mTime    = Time.at(0)
+      @commands = nil
+      return 1
+    end
+
+    # Turn an array of strings +source+ into a series of directives that
+    # can be handled by Parser#compile.
+    #
+    # If provided, +filename+ is assumed to be the name of the 
+    # file which contains the original +source+.
+    def parse(source, filename = "?")
+      puts "#{filename}: Parsing ..." if $DEBUG
+      
+      # Translate source into listing of text and directives
+      lineNo = 1
+      parsed = []
+      source.each do |line|
+        # split into plain text and directives
+        while line
+          dirMatch = @syntax.directive.match(line)
+          if dirMatch
+            matchText = dirMatch[1]
+            pre = dirMatch.pre_match
+            directive = @syntax.lookup(matchText)
+            parsed.push [lineNo, pre]
+            
+            if directive
+              parsed.push [lineNo, directive]
+            else
+              # Unrecognized directives are treated as
+              # plain text.
+              parsed.push [lineNo, dirMatch[0]]
+            end
+            
+            fragment = dirMatch.post_match
+            line = fragment
+          else
+            parsed.push [lineNo, line]
+            break
+          end
+        end
+        lineNo += 1
+      end
+      
+      puts "#{filename}: #{@parsed.length} directives" if $DEBUG
+      
+      return parsed
+    end
+
+    # Turn an array of parsed directives into a CommandBlock.
+    #
+    # If provided, +filename+ is assumed to be the name of the 
+    # file which contains the original +source+.
+    def compile(lines, filename = "?")
+      
+      puts "#{filename}: Compiling ..." if $DEBUG
+      # Translate listing of text and directives into a BlockCommand
+      commands = BlockCommand.new()
+      max = lines.length
+      i = 0
+      while i < max
+        line = lines[i]
+        type = line[1].class
+        command = nil
+        #puts "#{filename}/#{line[0]}: #{type} -- #{line}"
+        
+        if type == String
+          command = TextCommand.new(line[1])
+        elsif type == Array
+          directive = line[1][0]
+          value = line[1][1]
+          print "(#{directive} #{value}) " if $DEBUG
+          
+          if directive == "value"
+            command = ValueCommand.new(value)
+          elsif directive == "include"
+            command = IncludeCommand.new(value, @path)
+          elsif directive == "comment"
+            command = CommentCommand.new()
+          elsif directive =~ /^(\w+?)open$/
+            mainBlock = nil
+            branchBlock = nil
+            close = nil
+            branch = nil
+            
+            block = $1
+            startIndex = i + 1
+            closers = findClose(lines[startIndex..-1], 
+                                startIndex, block)
+            
+            if closers['close']
+              close = closers['close']
+              if closers['branch']
+                branch = closers['branch']
+                mainLines = lines[startIndex...branch]
+                mainBlock = compile(mainLines)
+                branchLines = lines[branch+1...close]
+                branchBlock = compile(branchLines)
+              else
+                mainLines = lines[startIndex...close]
+                mainBlock = compile(mainLines)
+              end
+            else
+              raise "#{filename}:#{line[0]} - " + 
+                      "#{block} #{value} doesn't close"
+            end
+            
+            if block == "if"
+              if mainBlock and branchBlock
+                command = IfElseCommand.new(value,
+                                            mainBlock, branchBlock)
+              elsif mainBlock
+                command = IfCommand.new(value, mainBlock)
+              end
+            elsif block == "loop"
+              if mainBlock and branchBlock
+                command = LoopElseCommand.new(value,
+                                              mainBlock, branchBlock)
+              elsif mainBlock
+                command = LoopCommand.new(value, mainBlock)
+              end
+            else
+              raise "#{filename}: #{line[0]} - " +
+                      "Unrecognized block type '#{block}'"
+            end
+            
+            # Skip to the line after the block closer.
+            i = close
+          elsif %Q[
+			ifbranch ifclose loopbranch loopclose
+			].include?(directive)
+            raise "#{filename}:#{line[0]} - #{directive}" +
+                        " without corresponding opening directive"
+          else
+            raise "#{filename}:#{line[0]} - Unknown command #{directive}"
+          end
+        else
+          raise "#{filename}: Unknown instruction in line #{line}"
+        end
+        
+        commands.add(command)
+        i += 1
+      end
+      
+      # Return compiled BlockCommand
+      return commands
+    end
+    
+    private
+    def findClose(lines, mIndex, dType)
+      branchIndex = nil
+      closeIndex = nil
+      
+      openTerm = dType + "open"
+      closeTerm = dType + "close"
+      branchTerm = dType + "branch"
+      
+      j = 0
+      nesting = 0
+      max = lines.length
+      while j < max
+        jLine = lines[j]
+        jDirective = jLine[1][0]
+        line = jLine[0]
+        
+        if jDirective == openTerm
+          nesting += 1
+        elsif jDirective == branchTerm
+          if nesting == 0
+            if branchIndex
+              raise RuntimeError, 
+                    "#{@file}:#{line} - Multiple branching statements"
+            else
+              branchIndex = j
+            end
+          end
+        elsif jDirective == closeTerm
+          if nesting > 0
+            nesting -= 1
+          else
+            closeIndex = j
+          end
+          
+        end
+        
+        j += 1
+      end
+      
+      branchIndex += mIndex if branchIndex
+      closeIndex  += mIndex if closeIndex
+      
+      return { 'branch'=> branchIndex, 'close'=> closeIndex }
+    end
+    
+  end
+  
+  
+  # A Syntax::Parser that can save its compiled CommandBlock for reuse later.
+  class CachedParser < Parser
+    def initialize(glossary, path=Dir.getwd)
+      super(glossary, path)
+      # Create the cache directory if it does not exist.
+    end
+
+    def build(filename)
+      # Determine the name of the cache file.
+      cacheFile = File.dirname(filename) + "/_" + File.basename(filename)
+      saveCache = false
+      
+      # See if cache exists and is newer than source.
+      cacheFile.untaint
+      if File.exists?(cacheFile)
+        cacheStat = File.stat(cacheFile)
+        if cacheStat.mtime > File.stat(filename).mtime
+          # See if cache is newer than internal CommandBlock.
+          if cacheStat.mtime > @mTime
+            # Load the cache into memory
+            @commands = Marshal.load(IO.readlines(cacheFile).join)
+            @mTime = cacheStat.mtime
+          elsif cacheStat.mtime < @mTime
+            saveCache = true
+          end
+        else
+          # Build the CommandBlock
+          super(filename)
+          saveCache = true
+        end
+      else
+        super(filename)
+        saveCache = true
+      end
+      
+      if saveCache
+        # Write the cache to disk.
+        data = Marshal.dump(@commands)
+        f = File.new(cacheFile, "w")
+        f.write(data)
+        f.close
+      end
+      
+      return 1 if @commands
+    end
+  end
+end
+
+############################################################
+
+# An object which parses text files littered with template directives 
+# and can produce text based on set parameters and the instructions 
+# contained within the text file. Each PageTemplate has its own
+# Namespace, so there shouldn't be any problems using it in a threaded
+# environment.
+#
+# PageTemplate is the primary user Class for this package.
+class PageTemplate
+  attr_reader :file, :syntax, :parser
+  attr_accessor :path
+
+  # Creates a new PageTemplate object, using +args+ to provide 
+  # optional initialization.
+  #
+  # ==== Possible Keys For Args
+  #
+  # [:include_path]
+  #     Additional directories that PageTemplate will look for template files in.
+  #     - May be a string or Array
+  #
+  # [:filename]
+  #	The name of a text file to use for a template.
+  #
+  # [:syntax]
+  #       A Syntax::Glossary object, provided if the user wants 
+  #	an alternate syntax for template parse directives.  If not 
+  #	provided, then Syntax::DEFAULT is used.
+  #
+  # [:use_cache]
+  #	If +true+, the PageTemplate object will use a Syntax::CachedParser
+  #	which stores compiled template data to disk in the same directory as the
+  #	template file itself.  This cached template still needs you to provide
+  #	a Namespace during output, though.
+  def initialize(args = {})
+    
+    @source   = []
+    @params   = Namespace.new()
+    
+    if args['syntax']
+      @syntax = args['syntax']
+    else
+      @syntax = Syntax::DEFAULT
+    end
+
+    @path = [ Dir.getwd() ]
+    if pathInfo = args['include_path']
+      if pathInfo.class == Array
+        @path = @path + pathInfo
+      else
+        @path.push(pathInfo)
+      end
+    end
+    
+    if args['use_cache']
+      @parser = Syntax::CachedParser.new(@syntax, @path)
+    else
+      @parser = Syntax::Parser.new(@syntax, @path)
+    end
+    
+    if args['filename']
+      @file = args['filename']
+      load(@file)
+    else
+      @file = nil
+    end
+
+  end
+
+  # Add a path to the search path for loading includes.
+  def add_path(path)
+    @path.push(path)
+  end
+  
+  # Open +file+ and parse its contents so they will be ready
+  # for template generation.
+  def load(file)
+    clearFile()
+    if File.exists?(file) then
+      @file = file
+    else
+      filepath = File.join(@path, file)
+      if File.exists?(filepath) then
+        @file = filepath
+      else
+        raise ArgumentError, "Cannot find #{file} in include path"
+      end
+    end
+    @parser.build(@file)
+  end
+  
+  # Set the namespace's +name+ to +value+.
+  #
+  # If you need to reset a flag or loop variable to a false value, the
+  # easiest way is to do just that: <tt>template.setParameter("myflag", false)</tt>
+  def setParameter(name, value)
+    @params.set(name, value)
+  end
+
+  # Get the value associated with +name+ from the namespace.  Returns 
+  # nil if the value is not set.
+  def getParameter(name)
+    return @params.get(name)
+  end
+
+  # An alias for PageTemplate.setParameter(key, value)
+  def []=(key, value)
+    setParameter(key, value)
+  end
+
+  # An alias for PageTemplate.getParameter(key)
+  def [](key)
+    return getParameter(key)
+  end
+
+  # Returns the text result of stepping through the compiled template.
+  # Returns nil if there is no compiled content (usually indicates
+  # that a file has not been loaded yet).
+  #
+  # *NOTE:* This checks the PageTemplate's namespace each time it 
+  # is called, so you can generate different custom pages without 
+  # reloading the template page.
+  def output
+    return @parser.commands.output(@params)
+  end
+
+  # Remove all template data from the PageTemplate, but leave the 
+  # Namespace intact.
+  def clearFile
+    @file = nil
+    @parser.reset()
+  end
+end
+
+# IncludeCommand allows including text from external files.
+class IncludeCommandError < RuntimeError
+  # Adding nothing, I just want the class name
+end
+
+class IncludeCommand < Command
+
+  def initialize(filename, path = nil)
+    super()
+    @filename = filename
+    @path = [ Dir.getwd() ]
+    
+    if path then
+      @path = @path + path
+    end
+
+    @parser = Syntax::Parser.new(Syntax::DEFAULT, @path)
+  end
+
+  def output(ns=nil)
+    # First check to see if the file exists in the current working directory
+    # or as an absolute filename.
+    text = ""
+    begin
+      file = determine_file(ns)
+      @parser.build(file)
+      text = @parser.output(ns)
+    rescue IncludeCommandError => error
+      text = error
+    end
+    return text
+  end
+
+  def to_s
+    return "IncludeCommand {path: '#{@path}' filename: '#{@filename}'}"
+  end
+
+  private
+  def determine_file(ns)
+    file = nil
+
+    if ns
+      base = ns.get(@filename) || @filename
+    else
+      base = @filename
+    end
+
+    @path.each do |p|
+      f = File.expand_path(File.join(p, base))
+      f.untaint
+      if File.exists?(f)
+        file = f
+        break
+      end
+    end
+
+    unless file
+      raise IncludeCommandError, "File #{base} not found."
+    end
+
+    return file
+  end
+
+end
+# = License
+#
+# ==The MIT License
+#
+# Copyright (c) 2002 Brian Wisti
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# Brian Wisti (brian@coolnamehere.com)