PageTemplate 1.2.0 → 2.0.0

data/lib/PageTemplate/parser.rb

@@ -0,0 +1,373 @@
+# parser.rb
+#
+# This contains the guts of the engines that make PageTemplate work.
+#
+
+############################################################
+
+class PageTemplate
+
+  # A Namespace object consists of three things:
+  #
+  # parent: A parent object to get a value from if the namespace
+  # does not 'know' a value.
+  #
+  # object: An object is a hash or list that contains the values that
+  # this namespace will refer to. It may also be an object, in which
+  # case, its methods are treated as a hash, with respond_to? and
+  # send()
+  #
+  # Cache: A cache ensures that a method on an object will only be
+  # called once.
+  class Namespace
+    attr_accessor :parent, :object
+    def initialize(parent=nil,object=nil)
+      @values = Hash.new
+      @parent = parent
+      @object = object
+    end
+
+    # Clears the cache
+    def clear_cache
+      @values = Hash.new
+    end
+
+    # Saves a variable +key+ as the string +value+ in the global 
+    # namespace.
+    def set(key, value)
+      @values[key] = value
+    end
+    alias_method :[]=, :set
+
+    # 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.
+    #
+    # If +val+ is a dot-separated list of words, then 'key' is the
+    # first part of it.  The remainder of the words are sent to key
+    # (and further results) to premit accessing attributes of objects.
+    def get(val)
+      # Is it ours, or is it cached?
+      key, rest = val.split(/\./,2)
+      value = case
+      when @values.has_key?(key)
+        @values[key]
+      when @object.respond_to?(:has_key?) && @object.has_key?(key)
+        @values[key] = @object[key]
+      when @object && @object.respond_to?(key.to_sym)
+        # This sets the cache and returns the value, too!
+        @values[key] = @object.send(key)
+      when @object && key == '__ITEM__'
+        @object
+      when @parent
+        @parent.get(key)
+      else
+        # We're the global namespace
+        nil
+      end
+
+      if rest
+        rest.split(/\./).each do |i|
+          begin
+            value = value.send(i)
+          rescue NoMethodError => er
+            return nil
+          end
+        end
+      end
+      value
+    end
+    alias_method :[], :get
+
+    # 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)
+      get(flag) ? true : false
+    end
+  end
+
+  # A Source is a source from which templates are drawn.
+  #
+  # Source#get(name) must return the body of the template that is to
+  # be parsed, or nil if it doesn't exist.
+  class Source
+    def initialize(args = {})
+      @args  = args
+    end
+    def get(name)
+      name
+    end
+  end
+
+  # FileSource provides access to files within the 'include_paths'
+  # argument.
+  #
+  # It attempts to be secure by not allowing any access outside of
+  # The directories detailed within include_paths
+  class FileSource < Source
+    attr_reader :paths
+
+    def initialize(args = {})
+      @args  = args
+      @paths = @args['include_paths']
+      @paths ||= [@args['include_path']].compact
+      @paths = [Dir.getwd] if @paths.empty?
+    end
+
+    # Return the contents of the file +name+, which must be within the
+    # include_paths.
+    def get(name)
+      begin
+        fn = get_filename(name)
+        if fn
+          return IO.read(fn)
+        else
+          return nil
+        end
+      rescue Exception => er
+        return "[ Unable to open file #{fn} ]"
+      end
+    end
+    def get_filename(file)
+      file = file.gsub(/\.\.\//,'') 
+      file.untaint
+      @paths.each do |path|
+        fn = File.join(path,file)
+        return fn if File.exists?(fn)
+      end
+      return nil
+    end
+  end
+
+  # This is the dictionary of commands and the directive that Parser
+  # uses to compile a template into a tree of commands.
+  #
+  # directive is the general format of a PageTemplate command.
+  # Default: /\[%(.+?)%\]/m
+  #
+  # @glossary is a hash table of regexp->Command objects. These
+  # regexps should not contain PageTemplate command text. i.e:
+  # /var \w+/i should be used instead of /[% var %]/
+  class SyntaxGlossary
+    attr_accessor :directive
+
+    def initialize(directive, glossary)
+      @directive = directive
+      @glossary = glossary
+    end
+
+    # Look up +text+ to see if it matches a command within the lookup
+    # table, returning the command for it, or UnknownCommand if none
+    # match.
+    def lookup(text)
+      @glossary.each do |key,val|
+        if m = key.match(text)
+          return val
+        end
+      end
+
+      return UnknownCommand
+    end
+  
+    # Define a regexp -> Command mapping.
+    # +rx+ is inserted in the lookup table as a key for +command+
+    def define(rx,command)
+      raise ArgumentError, 'First argument to define must be a Regexp' unless rx.is_a?(Regexp)
+      @glossary[rx] = command
+    end
+    # This is shorthand for define(+key+,Valuecommand), and also
+    # allows +key+ to be a string, converting it to a regexp before
+    # adding it to the dictionary.
+    def define_global_var(key)
+      rx = key
+      rx = /^#{key.to_s}(?:\.\w+\??)*(?:\s:(\w+))?$/ unless key.is_a?(Regexp)
+      @glossary[rx] = ValueCommand
+    end
+  end
+
+  # This is the regexp we tried using for grabbing an entire line
+  # Good for everything but ValueCommand :-/.
+  # /(?:^\s*\[%([^\]]+?)%\]\s*$\r?\n?|\[%(.+?)%\])/m,
+  DEFAULTGLOSSARY = SyntaxGlossary.new(
+          /\[%(.+?)%\]/m,
+
+          /^var ((\w+)(\.\w+\??)*)(\s+:\w+)?$/i       => ValueCommand,
+          /^--/i                                   => CommentCommand,
+          /^(if|unless) ((\w+)(\.\w+\??)*)$/i         => IfCommand,
+          /^(in|loop) ((\w+)(\.\w+\??)*)(:\s+\w+)?$/i => LoopCommand,
+          /^(include) ((\w+)(\.\w+\??)*)$/i           => IncludeCommand
+      )
+
+  # Preprocessor is a parent class for preprocessors.
+  # A preprocessor is used to process or otherwise prepare output for
+  # printing by Valuecommand
+  #
+  # Preprocessors must be singletons, and take a string to convert in
+  # some form.
+  class Preprocessor
+  end
+
+  # DefaultPreprocessor is a preprocessor with simple processors.
+  class DefaultPreprocessor < Preprocessor
+    # Just the string itself.
+    def DefaultPreprocessor.process(str)
+      str
+    end
+    # Reverse the string. (Just to demonstrate preprocessor)
+    def DefaultPreprocessor.reverse(str)
+      str.reverse
+    end
+    # HTML's escapeURI
+    def DefaultPreprocessor.escapeURI(string)
+      string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
+        '%' + $1.unpack('H2' * $1.size).join('%').upcase
+      end.tr(' ','+')
+    end
+    # escape HTML.
+    def DefaultPreprocessor.escapeHTML(string)
+      str = string.gsub(/&/n, '&amp;')
+      str.gsub!(/\"/n, '&quot;')
+      str.gsub!(/>/n, '&gt;')
+      str.gsub!(/</n, '&lt;')
+      str
+    end
+  end
+
+  # The big ass parser that does all the dirty work of turning
+  # templates into compiled commands.
+  #
+  # Parser.new() accepts a hash as an argument, and looks for these
+  # keys: (with defaults)
+  #
+  #  'namespace' => A namespace object. (A new namespace)
+  #  'glossary'  => A SyntaxGlossary object. (a dup of DEFAULTGLOSSARY)
+  #  'preprocessor' => The preprocessor. (DefaultPreprocessor)
+  #  'default_processor' => The processor. (:process)
+  #  'source' => The Source for templates. (FileSource)
+  #
+  # Once the parser is created, it can compile and parse any number of
+  # templates. 
+  #
+  # It can be treated as a one-template item by using
+  # Parser#load(template), and calling Parser.output
+  #
+  # To create separate generated templates from the same engine, use
+  # Parser#parse, or Parser#load. (It will still keep the most recent
+  # one it's #load'd, but that will not affect previously parsed or
+  # loaded)
+  class Parser
+    attr_reader :preprocessor, :default_processor
+    attr_reader :glossary, :namespace, :source
+    attr_reader :args, :commands
+    # Parser.new() accepts a hash as an argument, and looks for these
+    # keys: (with defaults)
+    #
+    #  'namespace' => A namespace object. (A new namespace)
+    #  'glossary'  => A SyntaxGlossary object. (a dup of DEFAULTGLOSSARY)
+    #  'preprocessor' => The preprocessor. (DefaultPreprocessor)
+    #  'default_processor' => The processor. (:process)
+    #  'source' => The Source for templates. (FileSource)
+    def initialize(args = {})
+      @args         = args # For sub-commands
+      @namespace    = args['namespace'] || Namespace.new
+      @glossary     = args['glossary'] || DEFAULTGLOSSARY.dup
+      @preprocessor = args['preprocessor'] || DefaultPreprocessor
+      @default_processor = args['default_processor'] || :process
+      @source       = (args['source'] || FileSource).new(@args)
+      @commands     = nil
+    end
+    # Load +name+ from a template, and save it to allow this parser to
+    # use it for output.
+    def load(name)
+      @commands = compile(name)
+    end
+    # Load +name+ from a template, but do not save it.
+    def compile(name)
+      body = @source.get(name)
+      if body
+        parse(body)
+      else
+        TextCommand.new("[ Template '#{name}' not found ]")
+      end
+    end
+    # Compile a Template (BlockCommand) from a string. Does not save
+    # the commands.
+    def parse(body)
+      rx = @glossary.directive
+      stack = [Template.new(self)]
+      while (m = rx.match(body))
+        pre = m.pre_match
+        command = m[1].strip.gsub(/\s+/,' ')
+        body = m.post_match
+        
+        # Convert all pre-text to a TextCommand
+        if (pre && pre.length > 0)
+          stack.last.add TextCommand.new(pre)
+        end
+
+        # If the command at the top of the stack is a 'Stacker',
+        # Does this command modify it? If so, just skip back.
+        next if stack.last.modifies?(command)
+
+        # If it closes, we're done changing this. Pop it off the
+        # Stack and add it to the one above it.
+        if stack.last.closes?(command)
+          cmd = stack.pop
+          stack.last.add(cmd)
+          next
+        end
+
+        # Find what command it is.
+        cmd = @glossary.lookup(command)
+        
+        # If the command takes it, pass the parser.
+        block = if (cmd.instance_method(:initialize).arity == 2)
+          cmd.new(command,self)
+        else
+          cmd.new(command)
+        end
+
+        # If it's a stacking command, push it on the stack
+        if block.is_a?(StackableCommand)
+          stack.push block
+        else
+          stack.last.add block
+        end
+      end
+      stack.last.add TextCommand.new(body) if body && body.length > 0
+      if (stack.length > 1)
+        raise ArgumentError, 'Mismatched command closures in template'
+      end
+      stack[0]
+    end
+    # Not really of any point, but clears the saved commands.
+    def clearCommands
+      @commands = nil
+    end
+    # Sets this parser's namespace values.
+    def []=(key,val)
+      @namespace[key] = val
+    end
+    # Gets this parser's namespace values.
+    def [](key)
+      @namespace[key]
+    end
+    # If any commands are loaded and saved, return a string of it.
+    def output(namespace=nil)
+      return '' unless @commands
+      @namespace.parent = namespace if namespace
+      str = @commands.output(@namespace)
+      @namespace.parent = nil
+      str
+    end
+  end
+end