simple_templates 0.8.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 08fc7fb9189730ce991dc231ca4eb5de54768e86
+  data.tar.gz: bd1845c3b3f7546f69c066e9a1681c8cd2cac5e9
+SHA512:
+  metadata.gz: 1d1921e2541648638553bfaaf71854956c166c785fbffb60b62e88132ae84d340df3d06b86cedcfacebfe49fdfd35cd466954b3dfdb9fee789ed630e265c5f11
+  data.tar.gz: 079629726b5675b0ad18fb41b27152b43fc7997049b97fd5311fa8afbdb132e7c066e7a277c51c531285e5003b9a1eeef3f554637702f565a692bb34fac9990c

data/.gitignore

@@ -0,0 +1,6 @@
+Gemfile.lock
+coverage/
+*.gem
+*.DS_Store
+.yardoc/
+doc/

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+#ruby=ruby
+
+gemspec

data/Guardfile

@@ -0,0 +1,30 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Guard internally checks for changes in the Guardfile and exits.
+## If you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+##
+##  $ while bundle exec guard; do echo "Restarting Guard..."; done
+##
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest, :bundler => false do
+  watch(%r{^test/(.*)\/?(.*)_test\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Stack Builders, Inc.
+
+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.

data/README.md

@@ -0,0 +1,62 @@
+# simple_templates
+
+[![Circle CI](https://circleci.com/gh/stackbuilders/simple_templates.svg?style=shield&circle-token=caa5840efa6767d08ac3082270580367327a8906)](https://circleci.com/gh/stackbuilders/simple_templates)
+
+`simple_templates` is a minimalistic templates engine. This gem allows you to
+work with several types of templates.
+
+##Installation
+
+Clone the project
+```
+git@github.com:stackbuilders/simple_templates.git
+```
+
+Install the dependencies
+```
+bundle install
+```
+
+Run the tests
+```
+rake test
+```
+
+##Quick Start
+
+The basic use of the library can be seen like this:
+
+You can send a `String` with the raw input that includes your placeholders and
+a list of `String` containing the allowed placeholders, if it is `nil`, then all
+the placeholders are allowed.
+
+A example without errors, that allows us to call the method `render`
+```ruby
+  template = SimpleTemplates.parse("Hi <name>", %w[name])
+  template.render({ name: "Bob" }) if template.errors.empty?
+  => "Hi Bob"
+  template.remaining_tokens
+  => []
+```
+
+An example with errors. Since the allowed placeholder is not in the raw input.
+So we get are going to get a list of errors when parsing
+```ruby
+  template = SimpleTemplates.parse("Hi <name>", %w[date])
+  template.errors
+  => [...] # unknown placeholder
+```
+
+##Tasks
+The default task executed by `rake` is only
+```
+rake test
+```
+
+Additionally you can generate the documentation by running
+```
+rake docs
+```
+
+##License
+MIT. See [LICENSE](https://github.com/stackbuilders/simple_templates/blob/master/LICENSE)

data/Rakefile

@@ -0,0 +1,20 @@
+require "rake/testtask"
+
+task :default => [:test]
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ["lib/**/*.rb"]
+    t.stats_options = ["--list-undoc", "--compact"]
+  end
+
+  task :docs    => [:yard]
+rescue LoadError
+end
+
+Rake::TestTask.new do |t|
+  t.verbose = true
+  t.libs.push("demo", "test")
+  t.pattern = "test/**/*_test.rb"
+end

data/bin/simple-template

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.expand_path("../../lib", __FILE__)
+$:<<lib_dir unless $:.include?(lib_dir)
+
+require 'simple_templates'
+
+template = ARGV.shift or
+  abort "Usage: #{$0} \"<person> has <pet>\" person:Bob pet:dog"
+
+args = Hash[ARGV.map{|v| k,v = v.split(":",2); [k.to_sym, v]}]
+
+puts SimpleTemplates.parse(template).render(args)

data/lib/simple_templates.rb

@@ -0,0 +1,38 @@
+require 'simple_templates/template'
+require 'simple_templates/lexer'
+require 'simple_templates/parser'
+require 'simple_templates/unescapes'
+require 'simple_templates/delimiter'
+
+# A minimalistic templates engine
+module SimpleTemplates
+  #
+  # Builds a template renderer from given string template and list of
+  # allowed placeholders
+  #
+  # @param raw_template_string      String        the template to render
+  # @param allowed_placeholders Array[String] list of allowed placeholders
+  # @return [<SimpleTemplates::Template>]
+  #   A template cointaining a list of ASTs, errors and unparsed tokens
+  #
+  # @example template without errors
+  #   template = SimpleTemplates.parse("Hi <name>", %w[name])
+  #   template.render({ name: "Bob" }) if template.errors.empty?
+  #   => "Hi Bob"
+  #
+  # @example template with errors
+  #   template = SimpleTemplates.parse("Hi <name>", %w[date])
+  #   template.errors
+  #   => [...] # unknown placeholder
+  #
+  def self.parse(raw_template_string, allowed_placeholders = nil)
+    Template.new(
+      *Parser.new(
+        Unescapes.new('<', '>'),
+        Lexer.new(Delimiter.new(/\\</, /\\>/, /\</, /\>/), raw_template_string).
+          tokenize,
+        allowed_placeholders
+      ).parse
+    )
+  end
+end

data/lib/simple_templates/AST/node.rb

@@ -0,0 +1,59 @@
+module SimpleTemplates
+  # A module with the Abstract Syntax Tree for The Templates
+  module AST
+    #
+    # Parent class for a node in the AST.
+    # This  class is not supposed to be instantiated.
+    #
+    # @!attribute [r] contents
+    #   @return [String] the content of the node
+    # @!attribute [r] pos
+    #   @return [Number] the position of the content in the input
+    # @!attribute [r] allowed
+    #   @return [Boolean] if the node is allowed. (see allowed?)
+    class Node
+      attr_reader :contents, :pos, :allowed
+
+      # Initializes a new Node. Please note that this class is not supposed to
+      # be instantiated.
+      # @param contents [String] the content of the node
+      # @param pos [Numbers] the position of the content in the input
+      # @param allowed [Boolean] if the node is allowed
+      def initialize(contents, pos, allowed)
+        @contents = contents
+        @pos      = pos
+        @allowed  = allowed
+      end
+
+      # Compares the node to other node by comparing the attributes of the
+      # objects.
+      # @param other [SimpleTemplates::AST::Node]
+      # @return [Boolean]
+      def ==(other)
+        contents == other.contents && pos == other.pos && allowed == other.allowed
+      end
+
+      # Checks if the Node is allowed by returning the value in the class
+      # attribute +allowed+.
+      def allowed?
+        allowed
+      end
+
+      # Returns only the name of the class without the namespace.
+      # @return [String]
+      def name
+        self.class.to_s.split('::').last
+      end
+
+      # Not implemented method to render a Node that must be especialized by
+      # the class inheriting from this class.
+      # @param context [Hash{ Symbol => String }]
+      # @return [String] substituded contexts
+      # :nocov:
+      def render(context)
+        raise NotImplementedError
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/simple_templates/AST/placeholder.rb

@@ -0,0 +1,25 @@
+require 'simple_templates/AST/node'
+
+module SimpleTemplates
+  module AST
+    #
+    # A Placeholder specialized Node that implements the +render+ method for
+    # placeholders
+    #
+    class Placeholder < Node
+      #
+      # Renders the substitutions in the input.
+      # Raises an error if it is not allowed. (see allowed?)
+      # @param substitutions [Hash{ Symbol => String }]
+      # @return [String] the content of the placeholder
+      #
+      def render(substitutions)
+        if allowed?
+          substitutions.fetch(contents.to_sym)
+        else
+          raise 'Unable to render invalid placeholder!'
+        end
+      end
+    end
+  end
+end

data/lib/simple_templates/AST/text.rb

@@ -0,0 +1,28 @@
+require 'simple_templates/AST/node'
+
+module SimpleTemplates
+  module AST
+    #
+    # A Text specialized Node that implements the +render+ method for text
+    # inputs
+    #
+    class Text < Node
+      # Renders the content of the node. It doesn't use the context just takes
+      # the class contents.
+      # @param context [Hash{ Symbol => String }]
+      # @return [String] returns the +contents+ of the class since it doesn't
+      #   apply any substitution
+      def render(context)
+        contents
+      end
+
+      # Appends the content of the Text node to another node, keeping the
+      # position and checking if both are allowed or not.
+      # @param other [SimpleTemplates::AST::Text]
+      # @return [SimpleTemplates::AST::Text]
+      def +(other)
+        Text.new(contents + other.contents, pos, allowed && other.allowed)
+      end
+    end
+  end
+end

data/lib/simple_templates/delimiter.rb

@@ -0,0 +1,6 @@
+module SimpleTemplates
+
+  # A +Struct+ for a Delimiter that takes +Regexp+ for the quoted start and
+  # quoted end of the placeholder as well as the start and end
+  Delimiter = Struct.new(:quoted_ph_start, :quoted_ph_end, :ph_start, :ph_end)
+end

data/lib/simple_templates/lexer.rb

@@ -0,0 +1,73 @@
+require 'strscan'
+
+module SimpleTemplates
+
+  # The +SimpleTemplates::Lexer+ tokenizes the raw input into a more usable form
+  # for the +SimpleTemplates::Parser+.
+
+  class Lexer
+
+    # A +Struct+ for a Lexer::Token that takes the type, the content and
+    # position of a token.
+    Token = Struct.new(:type, :content, :pos)
+
+    # A Hash with the allowed +Regexp+ for a valid placeholder name
+    # @return [Hash{Symbol => Regexp}] a hash with the allowed Regexp for the
+    #   placeholder name +:ph_name+
+    VALID_PLACEHOLDER = { ph_name: /[A-Za-z0-9_]+/ }.freeze
+
+    # Initializes a new Lexer
+    # @param delimiter [SimpleTemplates::Delimiter] a delimiter object
+    # @param input [String] a raw input for the lexer
+    def initialize(delimiter, input)
+      @input    = input.clone.freeze
+      @matchers = delimiter.to_h.merge(text: /./m).freeze
+      @matchers_with_placeholder_name = VALID_PLACEHOLDER.merge(@matchers)
+    end
+
+    # Tokenizes the raw input and returns a list of tokens.
+    # @return <Array[SimpleTemplates::Lexer::Token]>
+    def tokenize
+      tokens = []
+      ss = StringScanner.new(@input)
+
+      until ss.eos?
+        tok = next_token(tokens, ss)
+
+        if tokens.any? && tok.type == :text && tokens.last.type == :text
+          tokens.last.content += tok.content
+        else
+          tokens << tok
+        end
+      end
+
+      tokens
+    end
+
+    private
+
+    # Returns a new token and moves to the next position in the +StringScanner+
+    # @param tokens <Array[SimpleTemplates::Lexer::Token]> list of tokens
+    # @param ss [StringScanner] a +StringScanner+ for the input
+    # @return [SimpleTemplates::Lexer::Token] the next token
+    def next_token(tokens, ss)
+      pos = ss.pos
+      token_type, _ = current_matchers(tokens).find { |_, pattern| ss.scan(pattern) }
+
+      Token.new(token_type, ss.matched, pos)
+    end
+
+    # Checks if the last token was the start of a placeholder to use include
+    #   the placeholder name +:ph_name+ in the hash of matchers
+    # @param tokens <Array[SimpleTemplates::Lexer::Token]> the list of tokens
+    # @return [Hash {Symbol => Regexp}]
+    # (see #next_token)
+    def current_matchers(tokens)
+      if tokens.any? && tokens.last.type == :ph_start
+        @matchers_with_placeholder_name
+      else
+        @matchers
+      end
+    end
+  end
+end

data/lib/simple_templates/parser.rb

@@ -0,0 +1,111 @@
+require 'simple_templates/parser/error'
+require 'simple_templates/parser/placeholder'
+require 'simple_templates/parser/text'
+
+module SimpleTemplates
+  # Parsing the SimpleTemplate means verifying that there are no malformed tags,
+  # and all tags are in the 'allowed' list.
+  class Parser
+
+    # A +static+ Hash with the meaning of each tag name
+    # @return [Hash{Symbol => String}]
+    FRIENDLY_TAG_NAMES = {
+      ph_start:        'placeholder start',
+      ph_name:         'placeholder name',
+      ph_end:          'placeholder end',
+      quoted_ph_start: 'quoted placeholder start',
+      quoted_ph_end:   'quoted placeholder end',
+      text:            'text'
+    }.freeze
+
+    # Initializes a new Parser.
+    # @param unescapes [SimpleTemplates::Unescapes] a Unescapes object
+    # @param tokens <Array[SimpleTemplates::Lexer::Token]> a list of tokens
+    # @param allowed_placeholders <Array[String]> a list with allowed
+    #   placeholders if is left as nil, then all placeholders are permitted
+    def initialize(unescapes, tokens, allowed_placeholders)
+      @unescapes            = unescapes.clone.freeze
+      @tokens               = tokens.clone.freeze
+
+      @allowed_placeholders = allowed_placeholders &&
+        allowed_placeholders.clone.freeze
+    end
+
+    # Returns a Parser::Result containing the parsed AST nodes, the errors
+    # found when parsing and the remaining tokens that have not been parsed.
+    # @return [Array<Array<SimpleTemplates::AST::Node>,
+    #   Array<SimpleTemplates::Parser::Error>,
+    #   Array<SimpleTemplates::Lexer::Token>>]
+    def parse
+      ast    = []
+      errors = []
+
+      tok_stream = tokens.dup
+
+      while tok_stream.any?
+        parser = detect_parser(tok_stream)
+
+        if parser.nil?
+          errors <<
+          Error.new("Encountered unexpected token in stream " +
+                    "(#{FRIENDLY_TAG_NAMES[tok_stream.first.type]}), but expected to " +
+                    "see one of the following types: #{acceptable_starting_tokens}.")
+          tok_stream = []
+
+        else
+          template, errors_result, remaining_tokens = parser.parse
+
+          if remaining_tokens.nil?
+            raise "Parser #{parser.class} shouldn't return nil remaining " +
+                  "tokens (should be an Array), please report this bug."
+          end
+
+          if errors_result.empty?
+            tok_stream = remaining_tokens
+            ast        = ast.concat(template)
+
+          else
+            # Once we get a syntax error, we can't really determine if anything
+            # else is broken syntactically, so return with the first Error.
+            tok_stream = []
+            errors.concat(errors_result)
+
+          end
+        end
+      end
+
+      errors.concat(invalid_node_content_errors(ast))
+
+      [ast, errors, tok_stream]
+    end
+
+    private
+
+    attr_reader :tokens, :allowed_placeholders, :unescapes
+
+    def invalid_node_content_errors(ast)
+      ast.reject(&:allowed?).map do |node|
+        Error.new("Invalid #{node.name} with contents, '#{node.contents}' " +
+                  "found starting at position #{node.pos}.")
+      end
+    end
+
+    def acceptable_starting_tokens
+      (Placeholder::STARTING_TOKENS | Text::STARTING_TOKENS).map do |tag|
+        FRIENDLY_TAG_NAMES[tag]
+      end.join(', ')
+    end
+
+    def detect_parser(tokens_to_parse)
+      toks = tokens_to_parse.clone.freeze
+
+      [Placeholder, Text].each do |parser_class|
+        if parser_class.applicable?(toks)
+          return parser_class.new(unescapes, toks, allowed_placeholders)
+        end
+      end
+
+      nil
+    end
+  end
+end