porthole 0.99.4

data/lib/porthole/generator.rb

@@ -0,0 +1,195 @@
+class Porthole
+  # The Generator is in charge of taking an array of Porthole tokens,
+  # usually assembled by the Parser, and generating an interpolatable
+  # Ruby string. This string is considered the "compiled" template
+  # because at that point we're relying on Ruby to do the parsing and
+  # run our code.
+  #
+  # For example, let's take this template:
+  #
+  #   Hi {{thing}}!
+  #
+  # If we run this through the Parser we'll get these tokens:
+  #
+  #   [:multi,
+  #     [:static, "Hi "],
+  #     [:porthole, :etag, "thing"],
+  #     [:static, "!\n"]]
+  #
+  # Now let's hand that to the Generator:
+  #
+  # >> puts Porthole::Generator.new.compile(tokens)
+  # "Hi #{CGI.escapeHTML(ctx[:thing].to_s)}!\n"
+  #
+  # You can see the generated Ruby string for any template with the
+  # porthole(1) command line tool:
+  #
+  #   $ porthole --compile test.porthole
+  #   "Hi #{CGI.escapeHTML(ctx[:thing].to_s)}!\n"
+  class Generator
+    # Options are unused for now but may become useful in the future.
+    def initialize(options = {})
+      @options = options
+    end
+
+    # Given an array of tokens, returns an interpolatable Ruby string.
+    def compile(exp)
+      "\"#{compile!(exp)}\""
+    end
+
+    # Given an array of tokens, converts them into Ruby code. In
+    # particular there are three types of expressions we are concerned
+    # with:
+    #
+    #   :multi
+    #     Mixed bag of :static, :porthole, and whatever.
+    #
+    #   :static
+    #     Normal HTML, the stuff outside of {{portholes}}.
+    #
+    #   :porthole
+    #     Any Porthole tag, from sections to partials.
+    #
+    # To give you an idea of what you'll be dealing with take this
+    # template:
+    #
+    #   Hello {{name}}
+    #   You have just won ${{value}}!
+    #   {{#in_ca}}
+    #   Well, ${{taxed_value}}, after taxes.
+    #   {{/in_ca}}
+    #
+    # If we run this through the Parser, we'll get back this array of
+    # tokens:
+    #
+    #   [:multi,
+    #    [:static, "Hello "],
+    #    [:porthole, :etag, "name"],
+    #    [:static, "\nYou have just won $"],
+    #    [:porthole, :etag, "value"],
+    #    [:static, "!\n"],
+    #    [:porthole,
+    #     :section,
+    #     "in_ca",
+    #     [:multi,
+    #      [:static, "Well, $"],
+    #      [:porthole, :etag, "taxed_value"],
+    #      [:static, ", after taxes.\n"]]]]
+    def compile!(exp)
+      case exp.first
+      when :multi
+        exp[1..-1].map { |e| compile!(e) }.join
+      when :static
+        str(exp[1])
+      when :porthole
+        send("on_#{exp[1]}", *exp[2..-1])
+      else
+        raise "Unhandled exp: #{exp.first}"
+      end
+    end
+
+    # Callback fired when the compiler finds a section token. We're
+    # passed the section name and the array of tokens.
+    def on_section(name, content, raw, delims)
+      # Convert the tokenized content of this section into a Ruby
+      # string we can use.
+      code = compile(content)
+
+      # Compile the Ruby for this section now that we know what's
+      # inside the section.
+      ev(<<-compiled)
+      if v = #{compile!(name)}
+        if v == true
+          #{code}
+        elsif v.is_a?(Proc)
+          t = Porthole::Template.new(v.call(#{raw.inspect}).to_s)
+          def t.tokens(src=@source)
+            p = Parser.new
+            p.otag, p.ctag = #{delims.inspect}
+            p.compile(src)
+          end
+          t.render(ctx.dup)
+        else
+          # Shortcut when passed non-array
+          v = [v] unless v.is_a?(Array) || defined?(Enumerator) && v.is_a?(Enumerator)
+
+          v.map { |h| ctx.push(h); r = #{code}; ctx.pop; r }.join
+        end
+      end
+      compiled
+    end
+
+    # Fired when we find an inverted section. Just like `on_section`,
+    # we're passed the inverted section name and the array of tokens.
+    def on_inverted_section(name, content, raw, _)
+      # Convert the tokenized content of this section into a Ruby
+      # string we can use.
+      code = compile(content)
+
+      # Compile the Ruby for this inverted section now that we know
+      # what's inside.
+      ev(<<-compiled)
+      v = #{compile!(name)}
+      if v.nil? || v == false || v.respond_to?(:empty?) && v.empty?
+        #{code}
+      end
+      compiled
+    end
+
+    # Fired when the compiler finds a partial. We want to return code
+    # which calls a partial at runtime instead of expanding and
+    # including the partial's body to allow for recursive partials.
+    def on_partial(name, indentation)
+      ev("ctx.partial(#{name.to_sym.inspect}, #{indentation.inspect})")
+    end
+
+    # An unescaped tag.
+    def on_utag(name)
+      ev(<<-compiled)
+        v = #{compile!(name)}
+        if v.is_a?(Proc)
+          v = Porthole::Template.new(v.call.to_s).render(ctx.dup)
+        end
+        v.to_s
+      compiled
+    end
+
+    # An escaped tag.
+    def on_etag(name)
+      ev(<<-compiled)
+        v = #{compile!(name)}
+        if v.is_a?(Proc)
+          v = Porthole::Template.new(v.call.to_s).render(ctx.dup)
+        end
+        ctx.escapeHTML(v.to_s)
+      compiled
+    end
+
+    def on_fetch(names)
+      names = names.map { |n| n.to_sym }
+
+      if names.length == 0
+        "ctx[:to_s]"
+      elsif names.length == 1
+        "ctx[#{names.first.to_sym.inspect}]"
+      else
+        initial, *rest = names
+        <<-compiled
+          #{rest.inspect}.inject(ctx[#{initial.inspect}]) { |value, key|
+            value && ctx.find(value, key)
+          }
+        compiled
+      end
+    end
+
+    # An interpolation-friendly version of a string, for use within a
+    # Ruby string.
+    def ev(s)
+      "#\{#{s}}"
+    end
+
+    def str(s)
+      s.inspect[1..-2]
+    end
+  end
+end

data/lib/porthole/parser.rb

@@ -0,0 +1,263 @@
+require 'strscan'
+
+class Porthole
+  # The Parser is responsible for taking a string template and
+  # converting it into an array of tokens and, really, expressions. It
+  # raises SyntaxError if there is anything it doesn't understand and
+  # knows which sigil corresponds to which tag type.
+  #
+  # For example, given this template:
+  #
+  #   Hi {{thing}}!
+  #
+  # Run through the Parser we'll get these tokens:
+  #
+  #   [:multi,
+  #     [:static, "Hi "],
+  #     [:porthole, :etag, "thing"],
+  #     [:static, "!\n"]]
+  #
+  # You can see the array of tokens for any template with the
+  # porthole(1) command line tool:
+  #
+  #   $ porthole --tokens test.porthole
+  #   [:multi, [:static, "Hi "], [:porthole, :etag, "thing"], [:static, "!\n"]]
+  class Parser
+    # A SyntaxError is raised when the Parser comes across unclosed
+    # tags, sections, illegal content in tags, or anything of that
+    # sort.
+    class SyntaxError < StandardError
+      def initialize(message, position)
+        @message = message
+        @lineno, @column, @line, _ = position
+        @stripped_line = @line.strip
+        @stripped_column = @column - (@line.size - @line.lstrip.size)
+      end
+
+      def to_s
+        <<-EOF
+#{@message}
+  Line #{@lineno}
+    #{@stripped_line}
+    #{' ' * @stripped_column}^
+EOF
+      end
+    end
+
+    # After these types of tags, all whitespace until the end of the line will
+    # be skipped if they are the first (and only) non-whitespace content on
+    # the line.
+    SKIP_WHITESPACE = [ '#', '^', '/', '<', '>', '=', '!' ]
+
+    # The content allowed in a tag name.
+    ALLOWED_CONTENT = /(\w|[?!\/.-])*/
+
+    # These types of tags allow any content,
+    # the rest only allow ALLOWED_CONTENT.
+    ANY_CONTENT = [ '!', '=' ]
+
+    attr_reader :scanner, :result
+    attr_writer :otag, :ctag
+
+    # Accepts an options hash which does nothing but may be used in
+    # the future.
+    def initialize(options = {})
+      @options = {}
+    end
+
+    # The opening tag delimiter. This may be changed at runtime.
+    def otag
+      @otag ||= '%%'
+    end
+
+    # The closing tag delimiter. This too may be changed at runtime.
+    def ctag
+      @ctag ||= '%%'
+    end
+
+    # Given a string template, returns an array of tokens.
+    def compile(template)
+      if template.respond_to?(:encoding)
+        @encoding = template.encoding
+        template = template.dup.force_encoding("BINARY")
+      else
+        @encoding = nil
+      end
+
+      # Keeps information about opened sections.
+      @sections = []
+      @result = [:multi]
+      @scanner = StringScanner.new(template)
+
+      # Scan until the end of the template.
+      until @scanner.eos?
+        scan_tags || scan_text
+      end
+
+      if !@sections.empty?
+        # We have parsed the whole file, but there's still opened sections.
+        type, pos, result = @sections.pop
+        error "Unclosed section #{type.inspect}", pos
+      end
+
+      @result
+    end
+
+    # Find {{portholes}} and add them to the @result array.
+    def scan_tags
+      # Scan until we hit an opening delimiter.
+      start_of_line = @scanner.beginning_of_line?
+      pre_match_position = @scanner.pos
+      last_index = @result.length
+
+      return unless x = @scanner.scan(/([ \t]*)?#{Regexp.escape(otag)}/)
+      padding = @scanner[1] || ''
+
+      # Don't touch the preceding whitespace unless we're matching the start
+      # of a new line.
+      unless start_of_line
+        @result << [:static, padding] unless padding.empty?
+        pre_match_position += padding.length
+        padding = ''
+      end
+
+      # Since {{= rewrites ctag, we store the ctag which should be used
+      # when parsing this specific tag.
+      current_ctag = self.ctag
+      type = @scanner.scan(/#|\^|\/|=|!|<|>|&|\{/)
+      @scanner.skip(/\s*/)
+
+      # ANY_CONTENT tags allow any character inside of them, while
+      # other tags (such as variables) are more strict.
+      if ANY_CONTENT.include?(type)
+        r = /\s*#{regexp(type)}?#{regexp(current_ctag)}/
+        content = scan_until_exclusive(r)
+      else
+        content = @scanner.scan(ALLOWED_CONTENT)
+      end
+
+      # We found {{ but we can't figure out what's going on inside.
+      error "Illegal content in tag" if content.empty?
+
+      fetch = [:porthole, :fetch, content.split('.')]
+      prev = @result
+
+      # Based on the sigil, do what needs to be done.
+      case type
+      when '#'
+        block = [:multi]
+        @result << [:porthole, :section, fetch, block]
+        @sections << [content, position, @result]
+        @result = block
+      when '^'
+        block = [:multi]
+        @result << [:porthole, :inverted_section, fetch, block]
+        @sections << [content, position, @result]
+        @result = block
+      when '/'
+        section, pos, result = @sections.pop
+        raw = @scanner.pre_match[pos[3]...pre_match_position] + padding
+        (@result = result).last << raw << [self.otag, self.ctag]
+
+        if section.nil?
+          error "Closing unopened #{content.inspect}"
+        elsif section != content
+          error "Unclosed section #{section.inspect}", pos
+        end
+      when '!'
+        # ignore comments
+      when '='
+        self.otag, self.ctag = content.split(' ', 2)
+      when '>', '<'
+        @result << [:porthole, :partial, content, padding]
+      when '{', '&'
+        # The closing } in unescaped tags is just a hack for
+        # aesthetics.
+        type = "}" if type == "{"
+        @result << [:porthole, :utag, fetch]
+      else
+        @result << [:porthole, :etag, fetch]
+      end
+
+      # Skip whitespace and any balancing sigils after the content
+      # inside this tag.
+      @scanner.skip(/\s+/)
+      @scanner.skip(regexp(type)) if type
+
+      # Try to find the closing tag.
+      unless close = @scanner.scan(regexp(current_ctag))
+        error "Unclosed tag"
+      end
+
+      # If this tag was the only non-whitespace content on this line, strip
+      # the remaining whitespace.  If not, but we've been hanging on to padding
+      # from the beginning of the line, re-insert the padding as static text.
+      if start_of_line && !@scanner.eos?
+        if @scanner.peek(2) =~ /\r?\n/ && SKIP_WHITESPACE.include?(type)
+          @scanner.skip(/\r?\n/)
+        else
+          prev.insert(last_index, [:static, padding]) unless padding.empty?
+        end
+      end
+
+      # Store off the current scanner position now that we've closed the tag
+      # and consumed any irrelevant whitespace.
+      @sections.last[1] << @scanner.pos unless @sections.empty?
+
+      return unless @result == [:multi]
+    end
+
+    # Try to find static text, e.g. raw HTML with no {{portholes}}.
+    def scan_text
+      text = scan_until_exclusive(/(^[ \t]*)?#{Regexp.escape(otag)}/)
+
+      if text.nil?
+        # Couldn't find any otag, which means the rest is just static text.
+        text = @scanner.rest
+        # Mark as done.
+        @scanner.terminate
+      end
+
+      text.force_encoding(@encoding) if @encoding
+
+      @result << [:static, text] unless text.empty?
+    end
+
+    # Scans the string until the pattern is matched. Returns the substring
+    # *excluding* the end of the match, advancing the scan pointer to that
+    # location. If there is no match, nil is returned.
+    def scan_until_exclusive(regexp)
+      pos = @scanner.pos
+      if @scanner.scan_until(regexp)
+        @scanner.pos -= @scanner.matched.size
+        @scanner.pre_match[pos..-1]
+      end
+    end
+
+    # Returns [lineno, column, line]
+    def position
+      # The rest of the current line
+      rest = @scanner.check_until(/\n|\Z/).to_s.chomp
+
+      # What we have parsed so far
+      parsed = @scanner.string[0...@scanner.pos]
+
+      lines = parsed.split("\n")
+
+      [ lines.size, lines.last.size - 1, lines.last + rest ]
+    end
+
+    # Used to quickly convert a string into a regular expression
+    # usable by the string scanner.
+    def regexp(thing)
+      /#{Regexp.escape(thing)}/
+    end
+
+    # Raises a SyntaxError. The message should be the name of the
+    # error - other details such as line number and position are
+    # handled for you.
+    def error(message, pos = position)
+      raise SyntaxError.new(message, pos)
+    end
+  end
+end