simple_templates 0.8.7

data/lib/simple_templates/parser/error.rb

@@ -0,0 +1,6 @@
+module SimpleTemplates
+  class Parser
+    # A +Struct+ that takes a message to create a parser error
+    Error = Struct.new(:message)
+  end
+end

data/lib/simple_templates/parser/node_parser.rb

@@ -0,0 +1,45 @@
+require 'set'
+
+module SimpleTemplates
+  class Parser
+    # A Base class for the Placeholders and Text parsers
+    class NodeParser
+
+      # The Base class doesn't accept any tokens for parsing, since it isn't
+      # supposed to be instantiated.
+      # @return [Set<Object>]
+      STARTING_TOKENS = Set[]
+
+      # Checks if the class is applicable for the first token in the list
+      # @param tokens <Array[SimpleTemplates::Lexer::Token]> a list of tokens
+      def self.applicable?(tokens)
+        tokens.any? && self::STARTING_TOKENS.include?(tokens.first.type)
+      end
+
+      # Initializes a new NodeParser. Please note that this class is not
+      # supposed to be instantiated.
+      # Raises an error if it is not applicable.
+      # @param unescapes [SimpleTemplates::Unescapes] a Unescapes object
+      # @param tokens <Array[SimpleTemplates::Lexer::Token]> a list of tokens
+      # @param allowed_placeholders <Array[String]> a list of allowed placeholders
+      def initialize(unescapes, tokens, allowed_placeholders)
+        raise ArgumentError, "Invalid Parser for String!" unless self.class.applicable?(tokens)
+
+        @unescapes                = unescapes.to_h.clone.freeze
+        @tokens                   = tokens.clone.freeze
+
+        # Placeholders to match are mapped to strings for our validity checks.
+        # This is because if we go the other way and convert all possible
+        # placeholder names to symbols before comparing to the whitelist, we
+        # could cause a memory leak by allocating an infinite amount of symbols
+        # that won't be garbage-collected.
+        @allowed_placeholders = allowed_placeholders &&
+                                allowed_placeholders.map(&:to_s).freeze
+      end
+
+      private
+
+      attr_reader :tokens, :allowed_placeholders, :unescapes
+    end
+  end
+end

data/lib/simple_templates/parser/placeholder.rb

@@ -0,0 +1,83 @@
+require 'set'
+
+require 'simple_templates/parser/node_parser'
+require 'simple_templates/AST/placeholder'
+
+module SimpleTemplates
+  class Parser
+    # Recognizes a set of input tokens as a Placeholder.
+    class Placeholder < NodeParser
+
+      # The expected tag order for a valid placeholder.
+      EXPECTED_TAG_ORDER = [:ph_start, :ph_name, :ph_end]
+
+      # The starting token that the input must have
+      STARTING_TOKENS = Set[:ph_start]
+
+      # If this stream starts with a placeholder token, parse out the
+      # Placeholder, or a Result with errors indicating the syntax problem.
+      # @return <Array <Array[SimpleTemplates::AST::Placeholder]>,
+      #   <Array[SimpleTemplates::Parser::Error]>,
+      #   <Array[SimpleTemplates::Lexer::Token]>> an +Array+ with the
+      #   AST::Placeholder as first element, a list of parser errors and a list
+      #   of the remaining tokens.
+      def parse
+        errors = check_placeholder_syntax
+
+        remaining_tokens = []
+
+        placeholder_ast = if errors.empty?
+          remaining_tokens = tokens[3..-1] || []
+
+          allowed = allowed_placeholders.nil? ||
+                    allowed_placeholders.include?(tag_name.content)
+
+          [AST::Placeholder.new(tag_name.content, tag_start.pos, allowed)]
+        else
+          [] # we don't have an AST portion to return if we encountered errors
+        end
+
+        [placeholder_ast, errors, remaining_tokens]
+      end
+
+      private
+
+      def check_placeholder_syntax
+        expected_order_with_found_tokens = EXPECTED_TAG_ORDER.zip(tag_tokens)
+
+        errors = expected_order_with_found_tokens.
+                   reduce([]) do |errs, (expected_type, found_tag)|
+
+          if found_tag.nil?
+            break errs << Parser::Error.new(
+              "Expected #{FRIENDLY_TAG_NAMES.fetch(expected_type)} token, but" +
+              " reached end of input.")
+
+          elsif expected_type != found_tag.type
+            break errs << Parser::Error.new(
+              "Expected #{FRIENDLY_TAG_NAMES.fetch(expected_type)} token at " +
+              "character position #{found_tag.pos}, but found a " +
+              "#{FRIENDLY_TAG_NAMES.fetch(found_tag.type)} token instead.")
+
+          else
+            # This token was expected at this point in the placeholder sequence,
+            # no need to add errors.
+            errs
+          end
+        end
+      end
+
+      def tag_tokens
+        tokens[0..2].compact
+      end
+
+      def tag_start
+        tokens[0]
+      end
+
+      def tag_name
+        tokens[1]
+      end
+    end
+  end
+end

data/lib/simple_templates/parser/text.rb

@@ -0,0 +1,52 @@
+require 'set'
+
+require 'simple_templates/parser/node_parser'
+require 'simple_templates/AST/text'
+
+module SimpleTemplates
+  class Parser
+    #Recognizes a set of input tokens as a Text
+    class Text < NodeParser
+
+      # The starting tokens that the input can have
+      # @return [Set<Symbol>]
+      STARTING_TOKENS = Set[:quoted_ph_start, :quoted_ph_end, :text]
+
+      # A hash containing the method for a quoted placeholder start or end
+      # @return [Hash{ Symbol => Symbol }]
+      UNESCAPE_METHODS = {
+        quoted_ph_start: :start,
+        quoted_ph_end:   :end
+      }
+
+      # It parses the stream, if it starts with a text node then it parses out
+      # the text until it is not applicable for the input anymore.
+      # @return <Array <Array[SimpleTemplates::AST::Text]>,
+      #   <Array>,
+      #   <Array[SimpleTemplates::Lexer::Token]>> an +Array+ with a list of
+      #   AST::Text as first element, always an Empty list of Errors and the
+      #   remaining unparsed tokens.
+      def parse
+        txt_node = nil
+        toks     = tokens.dup
+
+        while self.class.applicable?(toks)
+          next_txt_token = toks.shift
+
+          this_txt_node =
+            AST::Text.new(unescape(next_txt_token), next_txt_token.pos, true)
+
+          txt_node = txt_node.nil? ? this_txt_node : txt_node + this_txt_node
+        end
+
+        [[txt_node], [], toks || []]
+      end
+
+      private
+
+      def unescape(token)
+        unescapes[UNESCAPE_METHODS[token.type]] || token.content
+      end
+    end
+  end
+end

data/lib/simple_templates/template.rb

@@ -0,0 +1,65 @@
+require 'set'
+
+require 'simple_templates/AST/placeholder'
+
+module SimpleTemplates
+  #
+  # A +Template+ is a renderable collection of SimpleTemplates::AST nodes.
+  #
+  # @!attribute [r] ast
+  #   @return <Array[SimpleTemplates::AST::Node]> a list of renderable nodes
+  # @!attribute [r] errors
+  #   @return <Array[SimpleTemplates::Parser::Error]> a list of errors found
+  #     during parsing
+  # @!attribute [r] remaining_tokens
+  #   @return <Array[SimpleTemplates::Lexer::Token]> a list of the remaining
+  #     not parsed tokens
+  #
+  class Template
+
+    attr_reader :ast, :errors, :remaining_tokens
+
+    # Initializes a new Template
+    # @param ast <Array[SimpleTemplates::AST::Node]> list of AST nodes
+    # @param errors <Array[SimpleTemplates::Parser::Error]> a list of errors
+    #   found during parsing
+    # @param remaining_tokens <Array[SimpleTemplates::Lexer::Token]> list of
+    #   unparsed tokens from the input
+    def initialize(ast = [], errors = [], remaining_tokens = [])
+      @ast              = ast.clone.freeze
+      @errors           = errors.clone.freeze
+      @remaining_tokens = remaining_tokens.clone.freeze
+    end
+
+    # Returns all placeholder names used in the template.
+    # @return [Set<String>] Placeholders content
+    def placeholder_names
+      placeholders.map(&:contents).to_set
+    end
+
+    # Accepts a hash with the placeholder names as keys and the values for
+    # substitution
+    # @param substitutions [Hash{Symbol => String}] a hash with the placeholder
+    #   name as the key and the substitution for that placeholder as value
+    # @return [String] The concatenated result of rendering the substitutions
+    def render(substitutions)
+      raise errors.map(&:message).join(", ") unless errors.empty?
+      ast.map { |node| node.render(substitutions) }.join
+    end
+
+    # Returns all the +SimpleTemplates::AST::Placeholder+ nodes in the +ast+
+    #   list of the instance
+    # @return [Set<SimpleTemplates::AST::Placeholder>]
+    def placeholders
+      ast.select{ |node| SimpleTemplates::AST::Placeholder === node }.to_set
+    end
+
+    # Compares a +Template+ with another by comparing the +ast+, +errors+
+    # and the +remaining_tokens+ of each one
+    def ==(other)
+      ast == other.ast &&
+        errors == other.errors &&
+        remaining_tokens == other.remaining_tokens
+    end
+  end
+end

data/lib/simple_templates/unescapes.rb

@@ -0,0 +1,5 @@
+module SimpleTemplates
+  # A +Struct+ for the unescaped symbols. You want this to mark the placeholder
+  # tags. Takes a character for start and another for the end tag
+  Unescapes = Struct.new(:start, :end)
+end

data/lib/simple_templates/version.rb

@@ -0,0 +1,3 @@
+module SimpleTemplates
+  VERSION = "0.8.7"
+end

data/simple_templates.gemspec

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# -*- encoding: utf-8 -*-
+
+require File.expand_path("../lib/simple_templates/version.rb", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = "simple_templates"
+  s.version = SimpleTemplates::VERSION
+  s.authors = ["Michal Papis"]
+  s.email = ["support@stackbuilders.com"]
+  s.homepage = "https://github.com/stackbuilders/simple_templates"
+  s.summary = "Minimalistic templates engine"
+  s.license = "MIT"
+  s.files = `git ls-files`.split("\n")
+  s.executables << "simple-template"
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.required_ruby_version = ">= 2.0.0"
+  %w{rake minitest simplecov coveralls guard-minitest yard}.each do |name|
+    s.add_development_dependency(name)
+  end
+  s.add_development_dependency("guard", ">=2.12.8", "<3")
+  # s.add_development_dependency("smf-gem")
+end

data/test/simple_templates/AST/node_test.rb

@@ -0,0 +1,50 @@
+require_relative "../../test_helper"
+
+module SimpleTemplates
+  module AST
+    class TestNodeImpl < Node
+      def render(context)
+      end
+    end
+  end
+end
+
+describe SimpleTemplates::AST::Node do
+  let(:target)   {SimpleTemplates::AST::Node}
+  let(:allowed)  {target.new("a", 0, true)}
+  let(:impl)     {SimpleTemplates::AST::TestNodeImpl.new("a", 0, true)}
+
+  describe "==" do
+    it "is equal" do
+      allowed.must_equal target.new("a", 0, true)
+    end
+    it "isn't equal" do
+      allowed.wont_equal target.new("b", 0, true)
+      allowed.wont_equal target.new("a", 1, true)
+      allowed.wont_equal target.new("a", 0, false)
+      allowed.wont_equal target.new("b", 1, false)
+    end
+  end
+
+  describe "allowed?" do
+    it "is allowed?" do
+      allowed.allowed?.must_equal true
+    end
+    it "isn't allowed?" do
+      target.new("a", 0, false).allowed?.must_equal false
+    end
+  end
+
+  describe "render" do
+    let(:context) { {a: 1} }
+    it "fails" do
+      ->(){
+        allowed.render(context)
+      }.must_raise NotImplementedError
+    end
+    it "succeeds" do
+      impl.render(context).must_be_nil
+    end
+  end
+
+end

data/test/simple_templates/AST/placeholder_test.rb

@@ -0,0 +1,28 @@
+require_relative "../../test_helper"
+
+describe SimpleTemplates::AST::Placeholder do
+  let(:target)  {SimpleTemplates::AST::Placeholder}
+
+  describe "render" do
+
+    let(:substitutions) { { my_placeholder: 'result1' } }
+
+    it "fails when the placeholder name is not in the given Hash" do
+      ->(){
+        target.new('not_in_substitutions', 0, true).render(substitutions)
+      }.must_raise KeyError
+    end
+
+    it "fails when the placeholder is marked as invalid" do
+      ->(){
+        target.new('my_placeholder', 0, false).render(substitutions)
+      }.must_raise RuntimeError
+    end
+
+    it "succeeds" do
+      target.new('my_placeholder', 0, true).
+        render(substitutions).must_equal("result1")
+    end
+  end
+
+end

data/test/simple_templates/AST/text_test.rb

@@ -0,0 +1,23 @@
+require_relative "../../test_helper"
+
+describe SimpleTemplates::AST::Text do
+  let(:target)  {SimpleTemplates::AST::Text}
+  let(:valid)   {target.new("a", 0, true)}
+  let(:context) {Struct.new(:a).new("result1")}
+
+  describe "render" do
+    it "succeeds" do
+      valid.render(context).must_equal("a")
+    end
+  end
+
+  describe "+" do
+    it "adds valid" do
+      valid.+(target.new("b", 1, true)).must_equal target.new("ab", 0, true)
+    end
+    it "adds invalid" do
+      valid.+(target.new("b", 1, false)).must_equal target.new("ab", 0, false)
+    end
+  end
+
+end

data/test/simple_templates/lexer_test.rb

@@ -0,0 +1,145 @@
+require_relative "../test_helper"
+
+describe SimpleTemplates::Lexer do
+  let(:delimiter) { SimpleTemplates::Delimiter.new(/\\</, /\\>/, /\</, /\>/) }
+  let(:token) { SimpleTemplates::Lexer::Token }
+
+  describe '#tokenize' do
+    it 'tokenizes a string with no placeholders' do
+      raw_input = 'string with no placeholders'
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with no placeholders', 0)
+      ]
+    end
+
+    it 'tokenizes a string with placeholders' do
+      raw_input = 'string with <placeholder>'
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, 'placeholder', 13),
+        token.new(:ph_end, '>', 24)
+      ]
+    end
+
+    it 'tokenizes a string with invalid placeholders, containing a new line character' do
+      raw_input = "string with <foo\nbar> text"
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, 'foo', 13),
+        token.new(:text, "\nbar", 16),
+        token.new(:ph_end, '>', 20),
+        token.new(:text, ' text', 21)
+      ]
+    end
+
+    it 'tokenizes a string with invalid placeholders, contains leading and trailing space' do
+      raw_input = "string with < foobar > text"
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:text, ' foobar ', 13),
+        token.new(:ph_end, '>', 21),
+        token.new(:text, ' text', 22)
+      ]
+    end
+
+    it 'tokenizes a string with placeholders and a newline character' do
+      raw_input = "string with <placeholder>\n Something else"
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, 'placeholder', 13),
+        token.new(:ph_end, '>', 24),
+        token.new(:text, "\n Something else", 25)
+      ]
+    end
+
+    it 'tokenizes a string with invalid placeholder and an empty placeholder name' do
+      raw_input = "string with <> text"
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_end, '>', 13),
+        token.new(:text, ' text', 14)
+      ]
+    end
+    it 'tokenizes a string with placeholders having a new line character in the placeholder name' do
+      raw_input = "string with <placeholder\n> Something else"
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, 'placeholder', 13),
+        token.new(:text, "\n", 24),
+        token.new(:ph_end, '>', 25),
+        token.new(:text, " Something else", 26)
+      ]
+    end
+
+    it 'tokenizes a string with a placeholder containing numbers' do
+      raw_input = 'string with <1placeholder1>'
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, '1placeholder1', 13),
+        token.new(:ph_end, '>', 26),
+      ]
+    end
+
+    it 'tokenizes a string with a placeholder containing underscores' do
+      raw_input = 'string with <_place_holder_>'
+      tokens = SimpleTemplates::Lexer.new(
+        delimiter,
+        raw_input
+      ).tokenize
+
+      tokens.must_equal [
+        token.new(:text, 'string with ', 0),
+        token.new(:ph_start, '<', 12),
+        token.new(:ph_name, '_place_holder_', 13),
+        token.new(:ph_end, '>', 27),
+      ]
+    end
+  end
+end