masterview 0.2.5 → 0.3.0

data/lib/masterview/parser.rb

@@ -1,5 +1,9 @@
 module MasterView
 
+  # The TemplateProcessing module contains the internal mechanisms
+  # for the MasterView template document Parser
+  module TemplateProcessing
+
   class RenderLevel #contains render modes, each gen level
     attr_accessor :render_modes
 
@@ -81,6 +85,11 @@ module MasterView
     end
   end
 
+  # List of directives.
+  #
+  # Constructed with the directives for a template document element,
+  # sorted into processing order by directive priority level
+  #
   class DirectiveSet
     attr_accessor :directives
     def initialize
@@ -90,7 +99,7 @@ module MasterView
     def <<(directive)
       @directives << directive
       @directives.flatten!
-      self  
+      self
     end
 
     def determine_dcs(method_name)
@@ -110,10 +119,15 @@ module MasterView
         directive.send(method_name_sym, dcs)
       end
     end
-    
-  end
 
+  end
 
+  # Default renderer for document elements, invoked after any other directives
+  # on a document element have been processed.
+  #
+  # Unless preempted by a previously invoked directive, the default rendering
+  # is to copy the element content to the output.
+  #
   class SimpleRenderHandler
     def description
       'SimpleRenderHandler is the default renderer for nodes, it should be invoked as the last directive and will output node normally'
@@ -122,9 +136,20 @@ module MasterView
     def stag(dcs)
       context = dcs.context
       ret = []
+      # NOTE: although strictly speaking attribute order is not significant
+      # in XML, in practice some template authors may have a preferred style
+      # for the order in which they write attribute markup in their templates.
+      # In such cases, it would be nice to be able to support a config option
+      # to preserve original attribute order, rather than the forced sort-by-name
+      # as done here.  However, would need to get into the parser
+      # and have it use a facets Dictionary rather than standard {} Hash
+      # when collecting element attributes so we have order available at this point.
+      # Hook: rexml/parsers/baseparser.rb - pull method, :start_element event
+      # http://facets.rubyforge.org/api/more/classes/Dictionary.html
+      # [DJL 18-Jul-2006]
       ret << "<#{context[:tag].tag_name.to_s}" # allow for symbol tag_name
       sorted_attributes = context[:tag].attributes.sort { |a,b| a[0].to_s <=> b[0].to_s } #allow for symbols using to_s
-      sorted_attributes.each do |name, value| 
+      sorted_attributes.each do |name, value|
         ret << " #{name.to_s}=\"#{value}\"" # allow for key to by symbol
       end
       ret << '>' #must output as separate string so simplify_empty_elements can find it
@@ -139,7 +164,7 @@ module MasterView
       context = dcs.context
       [] << '<!-- ' << context[:content_part] << ' -->'
     end
-    
+
     def cdata(dcs)
       context = dcs.context
       [] << '<![CDATA[' << context[:content_part] << ']]>'
@@ -149,26 +174,49 @@ module MasterView
       context = dcs.context
       [] << '</' << "#{context[:tag].tag_name.to_s}>" #must output </ as separate string so simplify_empty_elements can find it
     end
-    
+
   end
 
-  class Tag 
+  # Records information about an element in the document.
+  #
+  # A Tag is constructed when the start tag of an element is encountered.
+  # It tracks the name of the tag along with any attributes and
+  # MasterView directives attached to this element which are invoked
+  # during the rendering processing.
+  #
+  #--
+  # ISSUE: better name for this class would be Element or TemplateElement.
+  # Tag is something the element *has* (in addition to its attributes and content),
+  # it's not what it *is*.  [Deb 22-Sep-2006]
+  #++
+  #
+  class Tag
     attr_accessor :directives, :tag_name, :attributes, :mode_type, :stag, :content, :etag, :parent
-    def initialize(directives, tag_name, attributes, mode_type, parent)
+    attr_accessor :prolog, :renderer
+    def initialize(directives, tag_name, attributes, mode_type, parent, prolog, renderer)
       @tag_name = tag_name
-      @attributes = attributes
+
+      unless attributes.nil? or attributes.is_a?( CaseInsensitiveHash ) # not a CaseInsensitiveHash so make it one
+        @attributes = CaseInsensitiveHash.new
+        @attributes.replace(attributes) # copy values in
+      else
+        @attributes = attributes
+      end
+
       @mode_type = mode_type
       @directives = directives
       @stag = []
       @content = []
       @etag = []
       @parent = parent
+      @prolog = prolog
+      @renderer = renderer
     end
 
-    # creates a tag context using tag itself and mode type, also merge in any additional 
+    # creates a tag context using tag itself and mode type, also merge in any additional
     # values passed in via values hash
     def create_context( values = {} )
-      { 
+      {
         :tag => self,
         :mode_type => @mode_type
       }.merge!(values)
@@ -179,8 +227,6 @@ module MasterView
     end
   end
 
-
-
   class MIOSerializer
     def initialize(options)
       raise RequiredArgumentMissingError.new("Required argument is missing, specify the MasterViewIO object in options[:output_mio_tree]") unless options[:output_mio_tree]
@@ -190,6 +236,7 @@ module MasterView
 
     def serialize(render_mode, tag)
       data_to_write = tag.data.join
+      data_to_write = tag.prolog + "\n" + data_to_write unless tag.prolog.nil? #prepend prolog if exists
       @mio_tree.path(render_mode.output).write(data_to_write, @options)
     end
   end
@@ -205,9 +252,9 @@ module MasterView
     end
   end
 
-  # Serializer which simply outputs each fragment to a hash with the key representing 
+  # Serializer which simply outputs each fragment to a hash with the key representing
   # the path and the value the string contents.
-  # You may specify this serializer as an option to the parser (:serializer => HashSerializer.new(output_hash)). 
+  # You may specify this serializer as an option to the parser (:serializer => HashSerializer.new(output_hash)).
   # It takes an empty hash as the single constructor parameter to which the contents will be output.
   class HashSerializer
     def initialize( output_hash )
@@ -222,25 +269,42 @@ module MasterView
   end
 =end
 
+  # A Renderer is configured for a template parser to control the output
+  # generated from the template source document.  The renderer is responsible
+  # for managing directive processing and output generation in response
+  # to document event notifications from the SAX source document parser.
+  #
   class Renderer
     include DirectiveHelpers
 
     # Set of element names that can be simplified. Used in simplify_empty_elements.
     # Only simplify elements that are specified in the DTD as being empty, collapsing others can cause parsing
-    # or rendering problems in browsers. 
+    # or rendering problems in browsers.
     # http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict
-    # base, meta, link, hr, br, param, img, area, input, col 
+    # base, meta, link, hr, br, param, img, area, input, col
     XHTMLEmptyElementNameSet = %w{ base meta link hr br param img area input col }.to_set
 
-    attr_reader :directive_load_paths, :mv_ns, :keyword_expander, :default_extension, :options
-    attr_accessor :render_levels, :default_render_handler, :serializer, :template_pathname, :template_full_pathname
+    attr_reader :options
+    attr_reader :template_pathname, :template_full_pathname
+
+    attr_reader :keyword_expander, :default_extension
+    attr_accessor :render_levels, :default_render_handler, :serializer
+
+    attr_reader :directive_load_path  #:nodoc:
     attr_reader :directives_registry  #:nodoc:
 
-    def self.last_renderer; @@last_renderer; end
+    attr_reader :mv_generate_attr, :mv_gen_partial_attr, :mv_gen_replace_attr
+    attr_reader :mv_insert_generated_comment_attr
+
+    # array of strings containing the xml prolog for a doc, on the root
+    # this might contain xml declaration and doctype, etc.
+    attr_accessor :prolog
 
     def initialize( options = {} )
-      @@last_renderer = self; #save last renderer for convenient access
       @options = options
+      @template_pathname = options[:template_pathname]
+      @template_full_pathname = IOMgr.template.path(self.template_pathname).full_pathname if self.template_pathname
+
       @default_render_handler = SimpleRenderHandler.new
       @render_levels = [
         RenderLevel.new( [RenderMode.new] )
@@ -248,59 +312,64 @@ module MasterView
 
       serializer = options[:serializer] || DefaultSerializer
       self.serializer = serializer.is_a?(Class) ? serializer.new(options) : serializer #one can pass in Serializer class or an instance
-      self.mv_ns = options[:namespace] || NamespacePrefix
-      self.template_pathname = options[:template_pathname] 
-      self.template_full_pathname = IOMgr.template.path(self.template_pathname).full_pathname if self.template_pathname
+
       @default_extension = (options[:output_mio_tree]) ? options[:output_mio_tree].default_extension : IOMgr.erb.default_extension
       @keyword_expander = KeywordExpander.new
       @keyword_expander.set_template_pathname(self.template_pathname, @default_extension)
-      #ISSUE: if :additional_directive_paths then do cleaning and validity checks here and now
-      # (then we don't need to keep re-checking in DirectiveRegistry or other processing)
-      # [DJL 04-Jul-2006]
-      self.directive_load_paths = ( DefaultDirectiveLoadPaths << options[:additional_directive_paths] ).flatten
+      self.initialize_directives( options[:directive_load_path] )
     end
 
-    def mv_ns=(namespace_prefix)
-      @mv_ns = namespace_prefix
-      Log.debug { 'namespace_prefix set to '+namespace_prefix }
-    end
+    # Process the directive load_path, re-requiring any new entries
+    # and preparing processing context for the current template.
+    #
+    # Note that any directives that were already required (and loaded)
+    # will still be in memory because these are not reset.
+    # (i.e., there is not currently a cache vs. reload config option for
+    # directive implementations in the way that rails provides for class loading).
+    #
+    def initialize_directives( load_path ) #:nodoc:
 
-    # Sets directive_load_paths, re-requiring all the new load paths, however any directives that were
-    # already required (and loaded) will still be in memory because these are not reset.
-    def directive_load_paths=( directive_paths ) 
+      using_current_load_path = (load_path == MasterView::DirectiveLoadPath.current)
 
-      @directives_registry = MasterView::DirectivesRegistry
-      #ISSUE: can we optimize this if there aren't :additional_directive_paths?
-      # Do we even need/want the notion of per-invocation :additional_directive_paths
-      # given that the directives load path is configurable for the client app?
-      # [DJL 04-Jul-2006]
-      directives_registry.load_directives( directive_paths ) #?? if directive_load_paths != DefaultDirectiveLoadPaths ??
+      # ordinary configuration sets up std load path and directives registry for the app session
+      # ??provide hook here for testing alt load paths and config overrides? is this right??
+      @directives_registry = using_current_load_path ? MasterView::DirectiveRegistry.current : MasterView::DirectiveRegistry.new
 
-      # is this a good idea? no clear that we need/want to modify mv_ns after app initialization
-      # If so, this could be simplifed.  Discuss with jeffb.
-      # [DJL 04-Jul-2006]
-      if @mv_ns != NamespacePrefix
-        @directives_registry = directives_registry.clone
-      end
+      #ISSUE: do we really need/want to run this o n *every* parse?
+      # Probably ought to have some cache config option like dev/production class loading
+      # [DJL 02-Oct-2006]
+      @directives_registry.process_directives_load_path( load_path ) #?? unless using_current_load_path??
+
+      # bind the names of the standard mv template-manipulation directives
+      mv_ns = @directives_registry.mv_namespace_prefix
+      @mv_generate_attr = mv_ns+'generate'
+      @mv_gen_partial_attr = mv_ns+'gen_partial'
+      @mv_gen_replace_attr = mv_ns+'gen_replace'
+      @mv_insert_generated_comment_attr  = mv_ns+'insert_generated_comment'
+      #??@mv_import_attr = mv_ns+'import'
+      #??@mv_import_render_attr = mv_ns+'import_render'
 
-      # only need to do the following if :additional_directive_paths or nonstd @mv_ns???
-      directives_registry.build_directive_maps( @mv_ns )
-      
     end
 
     def modes
       @render_levels.last.render_modes
     end
+
     def push_level(render_level)
       @render_levels.push render_level
     end
 
     def push_tag(tag_name, attributes)
+      tag_prolog = nil
+      unless prolog.nil?
+        tag_prolog = prolog.join("\n")
+        self.prolog = nil # clear now that we have used it, only needs to be applied to this tag
+      end
       modes.each do |mode|
         attributes_copy = attributes.clone #these get changed in select_active_directives
         directives = select_active_directives(tag_name, attributes_copy, mode)
         parent = (mode.tags.empty?) ? nil : mode.tag
-        mode.tags.push Tag.new(directives, tag_name, attributes_copy, mode.mode_type, parent)
+        mode.tags.push Tag.new(directives, tag_name, attributes_copy, mode.mode_type, parent, tag_prolog, self)
         mode.tag.stag << mode.render_directives(:stag)
       end
     end
@@ -314,7 +383,7 @@ module MasterView
     end
 
     #does not call any directives, direct output
-    def append_raw(raw_output) 
+    def append_raw(raw_output)
       modes.each do |mode|
         if mode.tag
           mode.tag.content << raw_output
@@ -350,10 +419,10 @@ module MasterView
     # Simplify (collapse) empty elements so that <foo></foo> from rexml parsing ends up being <foo/> .
     # Only simplify elements that are specified in the DTD as being empty, collapsing others can cause parsing
     # or rendering problems in browsers. Uses constant XHTMLEmptyElementNameSet to find elements that should be
-    # collapsed. 
+    # collapsed.
     # http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict
     # xhtml-1.0-Strict empty elements are:
-    # base, meta, link, hr, br, param, img, area, input, col 
+    # base, meta, link, hr, br, param, img, area, input, col
     def simplify_empty_elements(content) #relies on the fact that > and </ are individual strings and are back to back with nothing in between
       ret = []
       current_element_name = nil
@@ -361,7 +430,7 @@ module MasterView
       last = nil
       content.flatten!
       content.each do |item|
-        if next_to_last == '>' && last == '</' && XHTMLEmptyElementNameSet.include?(current_element_name) 
+        if next_to_last == '>' && last == '</' && XHTMLEmptyElementNameSet.include?(current_element_name)
           ret.pop #remove '>'
           ret.pop #remove '</'
           ret << ' />' # adding in a space to make xhtml more compatible with html editors and older browsers
@@ -387,43 +456,116 @@ module MasterView
 
     def select_active_directives(tag_name, attributes, mode)
       selected = DirectiveSet.new
-      directive_processors = directives_registry.construct_directive_processors( attributes )
-      sorted_directives = directive_processors.sort do |x,y| 
-        xval = (x.respond_to?(:priority)) ? x.priority : DirectivePriorities::Medium
-        yval = (y.respond_to?(:priority)) ? y.priority : DirectivePriorities::Medium
-        xval <=> yval
+      directive_processors = directives_registry.construct_directive_processors( tag_name, attributes )
+      sorted_directives = directive_processors.sort do |dp1,dp2|
+        dp1.priority <=> dp2.priority
       end
       sorted_directives << @default_render_handler #insure this is last
       selected << sorted_directives
     end
 
-  end
+    # initialize (if necessary) and append string to xml_prolog array
+    def append_to_prolog(str)
+      self.prolog ||= []
+      self.prolog << str
+    end
 
+  end
 
-  class MasterViewListener
+  # SAX parser event handler.  Handles the low-level events
+  # from the SAX parser processing an XML document and
+  # passes the element tag and content data off to a
+  # MasterViewer::TemplateProcessing::Renderer for template processing.
+  #
+  class SAXParserListener
     include REXML::SAX2Listener
     include DirectiveHelpers
+    include ParserHelpers
 
     def initialize( options = {} )
       @renderer = Renderer.new(options)
     end
 
     def xmldecl(version, encoding, standalone)
-      #todo
+      xmldecl = []
+      xmldecl << '<?xml'
+      xmldecl << %Q[version="#{version}"] unless version.nil?
+      xmldecl << %Q[encoding="#{encoding}"] unless encoding.nil?
+      xmldecl << %Q[standalone="#{standalone}"] unless standalone.nil?
+      xmldecl << '?>'
+      @renderer.append_to_prolog( xmldecl.join(' ') )
     end
 
     def start_document
       #todo
     end
 
-    def doctype(name, pub, sys, long_name, uri)
+    # Handles a doctype declaration. Any attributes of the doctype which are
+    # not supplied will be nil.  # EG, <!DOCTYPE me PUBLIC "foo" "bar">
+    # @p name the name of the doctype; EG, "me"
+    # @p pub_sys "PUBLIC", "SYSTEM", or nil.  EG, "PUBLIC"
+    # @p long_name the supplied long name, or nil.  EG, "foo"
+    # @p uri the uri of the doctype, or nil.  EG, "bar"
+    def doctype(name, pub_sys, long_name, uri)
+      xml_doctype = []
+      xml_doctype << '<!DOCTYPE'
+      xml_doctype << name
+      xml_doctype << pub_sys unless pub_sys.nil?
+      xml_doctype << %Q["#{long_name}"] unless long_name.nil?
+      xml_doctype << %Q["#{uri}"] unless uri.nil?
+      doctype_str = xml_doctype.join(' ')+'>'
+      @renderer.append_to_prolog( doctype_str )
+    end
+
+    def processing_instruction target, data
+      #todo
+    end
+
+    # If a doctype includes an ATTLIST declaration, it will cause this
+    # method to be called.  The content is the declaration itself, unparsed.
+    # EG, <!ATTLIST el attr CDATA #REQUIRED> will come to this method as "el
+    # attr CDATA #REQUIRED".  This is the same for all of the .*decl
+    # methods.
+    def attlistdecl(element, pairs, contents)
       #todo
     end
 
+    # <!ELEMENT ...>
+    def elementdecl content
+      #todo
+    end
+
+    # <!ENTITY ...>
+    # The argument passed to this method is an array of the entity
+    # declaration.  It can be in a number of formats, but in general it
+    # returns (example, result):
+    #  <!ENTITY % YN '"Yes"'>
+    #  ["%", "YN", "'\"Yes\"'", "\""]
+    #  <!ENTITY % YN 'Yes'>
+    #  ["%", "YN", "'Yes'", "s"]
+    #  <!ENTITY WhatHeSaid "He said %YN;">
+    #  ["WhatHeSaid", "\"He said %YN;\"", "YN"]
+    #  <!ENTITY open-hatch SYSTEM "http://www.textuality.com/boilerplate/OpenHatch.xml">
+    #  ["open-hatch", "SYSTEM", "\"http://www.textuality.com/boilerplate/OpenHatch.xml\""]
+    #  <!ENTITY open-hatch PUBLIC "-//Textuality//TEXT Standard open-hatch boilerplate//EN" "http://www.textuality.com/boilerplate/OpenHatch.xml">
+    #  ["open-hatch", "PUBLIC", "\"-//Textuality//TEXT Standard open-hatch boilerplate//EN\"", "\"http://www.textuality.com/boilerplate/OpenHatch.xml\""]
+    #  <!ENTITY hatch-pic SYSTEM "../grafix/OpenHatch.gif" NDATA gif>
+    #  ["hatch-pic", "SYSTEM", "\"../grafix/OpenHatch.gif\"", "\n\t\t\t\t\t\t\tNDATA gif", "gif"]
+    def entitydecl content
+      #todo
+    end
+
+    # <!NOTATION ...>
+    def notationdecl content
+      puts 'in notationdecl'
+    end
+
     def start_element(uri, localname, qname, attributes)
       unescape_attributes!(attributes)
-      push_levels(attributes)
-      @renderer.push_tag(qname, attributes)
+      ci_attributes = CaseInsensitiveHash.new
+      ci_attributes.replace(attributes) #populate from original hash
+      push_levels(ci_attributes)
+      @renderer.push_tag(qname, ci_attributes)
     end
 
     def characters(text)
@@ -454,41 +596,41 @@ module MasterView
     end
 
     def generate_replace(value)
-      @renderer.append_raw ERB_EVAL+value+ERB_END
+      @renderer.append_raw ERB_EVAL_START+value+ERB_EVAL_END
     end
 
     # handle a mv:gen_partial attribute, which calls generate and outputs a token
     # it takes an optional :dir => 'foo/bar' which is prepended to partial path,
-    # otherwise it just uses what is in partial. 
+    # otherwise it just uses what is in partial.
     # This creates a generate attribute value which will be used later.
     # Parameters
     # value = attribute value for gen_partial
     # attributes = all remaining attributes hash
     def handle_gen_partial(attributes)
-      value = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_ns+'gen_partial')
-      if value 
+      value = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_gen_partial_attr)
+      if value
         prepend_dir = find_string_val_in_string_hash(value, :dir) #only used for masterview
-        partial = find_string_val_in_string_hash(value, :partial) 
+        partial = find_string_val_in_string_hash(value, :partial)
         return if partial.nil?
         path = render_partial_name_to_file_name(partial, @renderer.default_extension)
         path = File.join(prepend_dir, path) if prepend_dir
-        generate_attribute = attributes[@renderer.mv_ns+'generate'] || '' # check if we need to add to existing generate
+        generate_attribute = attributes[@renderer.mv_generate_attr] || '' # check if we need to add to existing generate
         generate_attribute = path + (generate_attribute.blank? ? '' : ', '+generate_attribute)
-        attributes[@renderer.mv_ns+'generate'] = generate_attribute 
-        @renderer.append_raw( ERB_EVAL+'render( '+value+' )'+ERB_END ) 
+        attributes[@renderer.mv_generate_attr] = generate_attribute
+        @renderer.append_raw( ERB_CONTENT_START+'render( '+value+' )'+ERB_CONTENT_END )
       end
     end
 
     def push_levels(attributes)
       handle_gen_partial(attributes)
-      
-      gen_replace = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_ns+'gen_replace') #get and delete from map
+
+      gen_replace = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_gen_replace_attr) #get and delete from map
       generate_replace( gen_replace ) unless gen_replace.nil?
 
-      gen = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_ns+'generate') #get and delete from map
+      gen = @renderer.keyword_expander.resolveAttrAndDelete(attributes, @renderer.mv_generate_attr) #get and delete from map
       if gen
         omit_comment = @renderer.options[:omit_comment] || OmitGeneratedComments || File.extname(gen) != MasterView::IOMgr.erb.default_extension
-        attributes[@renderer.mv_ns+'insert_generated_comment'] =  @renderer.template_full_pathname.to_s unless omit_comment #add the comment directive, so it will be written to each gen'd file
+        attributes[@renderer.mv_insert_generated_comment_attr] = @renderer.template_full_pathname.to_s unless omit_comment #add the comment directive, so it will be written to each gen'd file
         render_level = nil
         gen_values = parse_eval_into_hash(gen, :normal)
 
@@ -499,7 +641,7 @@ module MasterView
           arr_values = (value.is_a?(Enumerable)) ? value : [value] #if not enumerable add it to array
           value.each do |path|
             path.strip!
-            #Log.debug { ('pushing mode='+mode_type.to_s+' path='+path).indent(2*@renderer.render_levels.size) } 
+            #Log.debug { ('pushing mode='+mode_type.to_s+' path='+path).indent(2*@renderer.render_levels.size) }
             render_level ||= RenderLevel.new
             render_level.push RenderMode.new(path, mode_type)
           end
@@ -508,51 +650,79 @@ module MasterView
       end
 
     end
-    
+
   end
 
+  end
+
+  # The Parser processes a template document containing MasterView directives markup.
+  #
+  # Processing options can be specified to control pre-processing of the template
+  # (e.g., <code>:tidy</code> to run HTML Tidy) as well as the operation of
+  # the parse operation.
+  #
   class Parser
-    def self.parse_mio( template_mio, output_mio_tree, options = {})
-      options[:template_pathname]= template_mio.pathname
+
+    # Parse a template document contained in an IO source.
+    def self.parse_mio( template_mio, output_mio_tree, options={} )
+      options = options.clone()  # don't munge the client's copy of this
+      options[:template_pathname] = template_mio.pathname
       options[:output_mio_tree] = output_mio_tree
       template = template_mio.read
       self.parse( template, options )
     end
 
-
-    # parse a MasterView template and render output. 
+    # Parse a MasterView template and render output.
+    #
     # template param is actual template source passed in as string or array.
-    # options are the optional parameters which control the output (:output_mio_tree, :namespace, :serializer)
-    def self.parse( template, options = DefaultParserOptions.clone)
-      options[:listeners] ||= [MasterViewListener]
-      options[:rescue_exceptions] = RescueExceptions unless options.include?(:rescue_exceptions)
+    # options are the optional parameters which control the template parsing (:tidy)
+    # and rendering output (:output_mio_tree, :namespace, :serializer)
+    #
+    def self.parse( template, options={} )
+      mv_parser = self.new
+      mv_parser.process(template, options)
+    end
+
+    # process the template
+    def process(template, options)
+
+      options = options.clone()  # don't munge the client's copy of this
+      ensure_standard_options_configured(options)
 
       begin
-      if options[:tidy]
-        template = TidyHelper.tidy(template)
-      elsif options[:escape_erb]
-        template = EscapeErbHelper.escape_erb(template)
-      end
-      
-      parser = REXML::Parsers::SAX2Parser.new( template )
-      options[:listeners].each do |listener|
-        if listener.is_a? Class
-          parser.listen( listener.new(options) )
-        else
-          parser.listen(listener)
+        sax_parser = REXML::Parsers::SAX2ParserWithDoctypeFix.new( template )
+        options[:listeners].each do |listener|
+          if listener.is_a? Class
+            sax_parser.listen( listener.new(options) )
+          else
+            sax_parser.listen(listener)
+          end
         end
-      end
-      parser.parse
-      rescue Exception => e
+        sax_parser.parse
+      rescue Exception => ex
         if options[:rescue_exceptions]
-          Log.error { "Failure to parse template. Exception="+e }
-          Log.debug { e.backtrace.join("\n") }
+          Log.error { "Failure to parse template. Exception="+ex }
+          Log.debug { ex.backtrace.join("\n") }
         else
           raise
         end
       end
     end
 
+    # ensure that default policies are configured
+    def ensure_standard_options_configured(options)  #:nodoc:
+
+      # install the standard processing mechanisms unless overridden by client
+      options[:directive_load_path] = DirectiveLoadPath.current unless options.include?(:directive_load_path)
+      options[:listeners] ||= [ TemplateProcessing::SAXParserListener ]
+      options[:rescue_exceptions] = RescueExceptions unless options.include?(:rescue_exceptions)
+
+      DefaultParserOptions.each_pair {|key, value|
+        options[key] = value unless options.include?(key)
+      }
+
+    end
+
   end
 
 end