mustachio-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 750349ee5695dec895a3677bae2df4d3938e4c8df4e6c8854957a9f54bed272f
+  data.tar.gz: b9573a2790c82d7a364c81ae07e8ae0e9d0561b4794951e0ce5e15b8a75b0fb7
+SHA512:
+  metadata.gz: af1247bcfefba49c2f5c6d5ee588079dc5f34798d37955f110431c284c2ca0464a394bfe5c08c4284ee74322e0a8e00fef04033325f4f4943bba86c1c69ccd0d
+  data.tar.gz: 18cc85a1b1a020ca78eb8655fd094b127ea4920fde7354679f7bc198f66bea40e03a4db43a640b9461e31f39a2d1ffb476ddbcfca298a7798a115c240b645dcd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 devjoaov
+
+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,210 @@
+# MustachioRuby
+
+A Ruby port of the powerful [Mustachio](https://github.com/ActiveCampaign/mustachio) templating engine for C# and .NET - a lightweight, fast, and safe templating engine with model inference capabilities.
+
+> **Note**: This is an unofficial Ruby port of the original [Mustachio](https://github.com/ActiveCampaign/mustachio) templating engine created by ActiveCampaign. All credit for the original design, concepts, and innovations goes to the ActiveCampaign team and the Mustachio contributors.
+
+#### What's this for?
+
+_MustachioRuby_ allows you to create simple text-based templates that are fast and safe to render. It's a Ruby implementation that brings the power of the templating engine behind [Postmark Templates](https://postmarkapp.com/blog/special-delivery-postmark-templates) to the Ruby ecosystem.
+
+#### How to use MustachioRuby:
+
+```ruby
+# Parse the template:
+source_template = "Dear {{name}}, this is definitely a personalized note to you. Very truly yours, {{sender}}"
+template = MustachioRuby.parse(source_template)
+
+# Create the values for the template model:
+model = {
+  "name" => "John",
+  "sender" => "Sally"
+}
+
+# Combine the model with the template to get content:
+content = template.call(model)
+# => "Dear John, this is definitely a personalized note to you. Very truly yours, Sally"
+```
+
+#### Extending MustachioRuby with Token Expanders:
+
+```ruby
+# You can add support for Partials via Token Expanders.
+# Token Expanders can be used to extend MustachioRuby for many other use cases,
+# such as: Date/Time formatters, Localization, etc., allowing also custom Token Render functions.
+
+source_template = "Welcome to our website! [[CONTENT]] Yours Truly, John Smith."
+string_data = "This is a partial. You can also add variables here {{ testVar }} or use other expanders. Watch out for infinite loops!"
+
+token_expander = MustachioRuby::TokenExpander.new
+token_expander.regex = /\[\[CONTENT\]\]/ # Custom syntax to avoid conflicts
+token_expander.expand_tokens = lambda do |s, base_options|
+  # Create new ParsingOptions to avoid infinite loops
+  new_options = MustachioRuby::ParsingOptions.new
+  MustachioRuby::Tokenizer.tokenize(string_data, new_options)
+end
+
+parsing_options = MustachioRuby::ParsingOptions.new
+parsing_options.token_expanders = [token_expander]
+template = MustachioRuby.parse(source_template, parsing_options)
+
+# Create the values for the template model:
+model = { "testVar" => "Test" }
+
+# Combine the model with the template to get content:
+content = template.call(model)
+```
+
+#### Installing MustachioRuby:
+
+MustachioRuby can be installed via [RubyGems](https://rubygems.org/):
+
+```bash
+gem install mustachio_ruby
+```
+
+Or add this line to your application's Gemfile:
+
+```ruby
+gem 'mustachio_ruby'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage Examples
+
+### Working with Arrays using `each` blocks:
+
+```ruby
+template = "{{#each items}}Item: {{name}} - ${{price}}\n{{/each}}"
+renderer = MustachioRuby.parse(template)
+
+model = {
+  "items" => [
+    { "name" => "Apple", "price" => 1.50 },
+    { "name" => "Banana", "price" => 0.75 }
+  ]
+}
+
+content = renderer.call(model)
+# => "Item: Apple - $1.5\nItem: Banana - $0.75\n"
+```
+
+### Complex Paths for Nested Objects:
+
+```ruby
+template = "User: {{user.profile.name}} ({{user.profile.age}}) from {{user.location.city}}, {{user.location.country}}"
+renderer = MustachioRuby.parse(template)
+
+model = {
+  "user" => {
+    "profile" => { "name" => "Alice Smith", "age" => 30 },
+    "location" => { "city" => "New York", "country" => "USA" }
+  }
+}
+
+content = renderer.call(model)
+# => "User: Alice Smith (30) from New York, USA"
+```
+
+### Conditional Sections:
+
+```ruby
+template = "{{#showMessage}}Hello, {{name}}!{{/showMessage}}{{^showMessage}}Goodbye!{{/showMessage}}"
+renderer = MustachioRuby.parse(template)
+
+# When showMessage is true
+model = { "showMessage" => true, "name" => "World" }
+content = renderer.call(model)
+# => "Hello, World!"
+
+# When showMessage is false
+model = { "showMessage" => false, "name" => "World" }
+content = renderer.call(model)
+# => "Goodbye!"
+```
+
+### HTML Escaping (Safe by Default):
+
+```ruby
+# Escaped by default for safety
+template = "Content: {{html}}"
+renderer = MustachioRuby.parse(template)
+model = { "html" => "<script>alert('xss')</script>" }
+content = renderer.call(model)
+# => "Content: &lt;script&gt;alert('xss')&lt;/script&gt;"
+
+# Unescaped with triple braces
+template = "Content: {{{html}}}"
+renderer = MustachioRuby.parse(template)
+content = renderer.call(model)
+# => "Content: <script>alert('xss')</script>"
+```
+
+### Model Inference:
+
+```ruby
+template = "Hello {{name}}! You have {{#each orders}}{{total}}{{/each}} orders."
+result = MustachioRuby.parse_with_model_inference(template)
+
+# result.parsed_template is the compiled template function
+# result.inferred_model contains information about expected model structure
+model = { "name" => "Alice", "orders" => [{ "total" => 5 }, { "total" => 3 }] }
+content = result.parsed_template.call(model)
+# => "Hello Alice! You have 53 orders."
+```
+
+### Advanced: Parsing Options
+
+```ruby
+options = MustachioRuby::ParsingOptions.new
+options.disable_content_safety = true  # Disable HTML escaping
+options.source_name = "my_template"    # For error reporting
+
+template = "Unsafe content: {{html}}"
+renderer = MustachioRuby.parse(template, options)
+model = { "html" => "<b>Bold Text</b>" }
+content = renderer.call(model)
+# => "Unsafe content: <b>Bold Text</b>"
+```
+
+##### Key differences between Mustachio and [Mustache](https://mustache.github.io/)
+
+MustachioRuby contains a few modifications to the core Mustache language that are important:
+
+1. `each` blocks are recommended for handling arrays of values. (We have a good reason!)
+2. Complex paths are supported, for example `{{ this.is.a.valid.path }}` and `{{ ../this.goes.up.one.level }}`
+3. Template partials are supported via Token Expanders.
+
+###### A little more about the differences:
+
+One awesome feature of Mustachio is that with a minor alteration in the mustache syntax, we can infer what model will be required to completely fill out a template. By using the `each` keyword when iterating over an array, our parser can infer whether an array or object (or scalar) should be expected when the template is used. Normal mustache syntax would prevent us from determining this.
+
+We think the model inference feature is compelling, because it allows for error detection, and faster debugging iterations when developing templates, which justifies this minor change to 'vanilla' mustache syntax.
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Acknowledgments
+
+This Ruby port would not be possible without the incredible work of the original [Mustachio](https://github.com/ActiveCampaign/mustachio) team at ActiveCampaign. Special thanks to:
+
+- **ActiveCampaign Team**: For creating and maintaining the original Mustachio templating engine
+- **All Mustachio Contributors**: For their valuable contributions to the original project
+- **Postmark Team**: For demonstrating the power of this templating approach in production
+
+MustachioRuby aims to faithfully port the original concepts and functionality while adapting them to Ruby's idioms and conventions.
+
+## License
+
+The gem is available as open source under the [MIT License](LICENSE).

data/lib/mustachio_ruby/context_object.rb

@@ -0,0 +1,80 @@
+require "cgi"
+
+module MustachioRuby
+  class ContextObject
+    PATH_FINDER = /(\.\.[\\\/]{1})|([^.]+)/
+
+    attr_accessor :parent, :value, :key
+
+    def initialize
+      @parent = nil
+      @value = nil
+      @key = ""
+    end
+
+    def get_context_for_path(path)
+      elements = path.scan(PATH_FINDER).map { |match| match.compact.first }
+      get_context_for_path_elements(elements)
+    end
+
+    def exists?
+      return false if @value.nil?
+      return false if @value == false
+      return false if @value == 0
+      return false if @value == 0.0
+      return false if @value == ""
+
+      if @value.respond_to?(:empty?)
+        return !@value.empty?
+      end
+
+      true
+    end
+
+    def to_s
+      return "" if @value.nil?
+
+      case @value
+      when String
+        @value.to_s
+      when Integer
+        @value.to_s
+      when Float
+        # Format floats like integers when they're whole numbers
+        @value == @value.to_i ? @value.to_i.to_s : @value.to_s
+      when TrueClass, FalseClass
+        @value.to_s
+      else
+        ""
+      end
+    end
+
+    def get_context_for_path_elements(elements)
+      return self if elements.empty?
+
+      element = elements.shift
+
+      if element&.start_with?("..")
+        if @parent
+          @parent.get_context_for_path_elements(elements)
+        else
+          get_context_for_path_elements(elements)
+        end
+      else
+        inner_context = ContextObject.new
+        inner_context.key = element
+        inner_context.parent = self
+
+        if @value.respond_to?(:[])
+          begin
+            inner_context.value = @value[element]
+          rescue
+            inner_context.value = nil
+          end
+        end
+
+        inner_context.get_context_for_path_elements(elements)
+      end
+    end
+  end
+end

data/lib/mustachio_ruby/extended_parse_information.rb

@@ -0,0 +1,10 @@
+module MustachioRuby
+  class ExtendedParseInformation
+    attr_accessor :inferred_model, :parsed_template
+
+    def initialize
+      @inferred_model = nil
+      @parsed_template = nil
+    end
+  end
+end

data/lib/mustachio_ruby/indexed_parse_exception.rb

@@ -0,0 +1,14 @@
+module MustachioRuby
+  class IndexedParseException < StandardError
+    attr_reader :source_name, :line_number, :character_on_line
+
+    def initialize(source_name, location, message, *args)
+      @source_name = source_name
+      @line_number = location ? location[:line] : 0
+      @character_on_line = location ? location[:character] : 0
+
+      formatted_message = message % args
+      super("#{source_name} Line: #{@line_number} Column: #{@character_on_line} #{formatted_message}")
+    end
+  end
+end

data/lib/mustachio_ruby/inferred_template_model.rb

@@ -0,0 +1,29 @@
+module MustachioRuby
+  module UsedAs
+    SCALAR = :scalar
+    COLLECTION = :collection
+    CONDITIONAL_VALUE = :conditional_value
+  end
+
+  class InferredTemplateModel
+    attr_accessor :used_as, :children
+
+    def initialize
+      @children = {}
+      @used_as = nil
+    end
+
+    def get_inferred_model_for_path(path, usage)
+      path_parts = path.split('.')
+      current = self
+
+      path_parts.each do |part|
+        current.children[part] ||= InferredTemplateModel.new
+        current = current.children[part]
+      end
+
+      current.used_as = usage if current.used_as.nil?
+      current
+    end
+  end
+end

data/lib/mustachio_ruby/parser.rb

@@ -0,0 +1,209 @@
+require "cgi"
+
+module MustachioRuby
+  class Parser
+    def self.parse(template, options = ParsingOptions.new)
+      tokens_result = get_tokens_queue(template, options)
+      if !tokens_result.errors.empty?
+        raise tokens_result.errors.first
+      end
+
+      internal_template = parse_tokens(tokens_result.tokens, options)
+
+      lambda do |model|
+        output = ""
+        context = ContextObject.new
+        context.value = model
+        context.key = ""
+
+        internal_template.call(output, context)
+        output
+      end
+    end
+
+    def self.parse_with_model_inference(template_source, options = ParsingOptions.new)
+      tokens_result = get_tokens_queue(template_source, options)
+      if !tokens_result.errors.empty?
+        raise tokens_result.errors.first
+      end
+
+      inferred_model = InferredTemplateModel.new
+      internal_template = parse_tokens(tokens_result.tokens, options, inferred_model)
+
+      template = lambda do |model|
+        output = ""
+        context = ContextObject.new
+        context.value = model
+        context.key = ""
+
+        internal_template.call(output, context)
+        output
+      end
+
+      result = ExtendedParseInformation.new
+      result.inferred_model = inferred_model
+      result.parsed_template = template
+      result
+    end
+
+    private
+
+    def self.get_tokens_queue(template, options)
+      Tokenizer.tokenize(template, options)
+    end
+
+    def self.parse_tokens(tokens, options, current_scope = nil)
+      build_array = []
+
+      while !tokens.empty?
+        current_token = tokens.shift
+
+        case current_token.type
+        when TokenType::COMMENT
+          # Skip comments
+        when TokenType::CONTENT
+          build_array << handle_content(current_token.value)
+        when TokenType::COLLECTION_OPEN
+          build_array << handle_collection_open(current_token, tokens, options, current_scope)
+        when TokenType::ELEMENT_OPEN
+          build_array << handle_element_open(current_token, tokens, options, current_scope)
+        when TokenType::INVERTED_ELEMENT_OPEN
+          build_array << handle_inverted_element_open(current_token, tokens, options, current_scope)
+        when TokenType::COLLECTION_CLOSE, TokenType::ELEMENT_CLOSE
+          # Return current template function
+          return lambda do |output, context|
+            build_array.each { |action| action.call(output, context) }
+          end
+        when TokenType::ESCAPED_SINGLE_VALUE, TokenType::UNESCAPED_SINGLE_VALUE
+          build_array << handle_single_value(current_token, options, current_scope)
+        when TokenType::CUSTOM
+          if current_token.renderer
+            build_array << current_token.renderer.call(current_token.value, tokens, options, current_scope)
+          end
+        end
+      end
+
+      lambda do |output, context|
+        build_array.each { |action| action.call(output, context) }
+      end
+    end
+
+    def self.html_encode_string(content)
+      CGI.escapeHTML(content)
+    end
+
+    def self.handle_single_value(token, options, scope)
+      if scope
+        scope.get_inferred_model_for_path(token.value, UsedAs::SCALAR)
+      end
+
+      lambda do |output, context|
+        if context
+          c = context.get_context_for_path(token.value)
+          unless c.value.nil?
+            if token.type == TokenType::ESCAPED_SINGLE_VALUE && !options.disable_content_safety
+              output << html_encode_string(c.to_s)
+            else
+              output << c.to_s
+            end
+          end
+        end
+      end
+    end
+
+    def self.handle_content(token)
+      lambda { |output, context| output << token }
+    end
+
+    def self.handle_inverted_element_open(token, remainder, options, scope)
+      if scope
+        scope.get_inferred_model_for_path(token.value, UsedAs::CONDITIONAL_VALUE)
+      end
+
+      inner_template = parse_tokens(remainder, options, scope)
+
+      lambda do |output, context|
+        c = context.get_context_for_path(token.value)
+        unless c.exists?
+          inner_template.call(output, c)
+        end
+      end
+    end
+
+    def self.handle_collection_open(token, remainder, options, scope)
+      if scope
+        scope.get_inferred_model_for_path(token.value, UsedAs::COLLECTION)
+      end
+
+      inner_template = parse_tokens(remainder, options, scope)
+
+      lambda do |output, context|
+        c = context.get_context_for_path(token.value)
+        return unless c.exists?
+
+        if c.value.is_a?(Array)
+          # Handle arrays
+          index = 0
+          c.value.each do |item|
+            inner_context = ContextObject.new
+            inner_context.value = item
+            inner_context.key = "[#{index}]"
+            inner_context.parent = c
+
+            inner_template.call(output, inner_context)
+            index += 1
+          end
+        elsif c.value.respond_to?(:each) && !c.value.is_a?(String)
+          # Handle other enumerable objects (like hashes)
+          if c.value.respond_to?(:keys)
+            # Hash-like objects
+            index = 0
+            c.value.each do |key, item|
+              inner_context = ContextObject.new
+              inner_context.value = item
+              inner_context.key = "[#{index}]"
+              inner_context.parent = c
+
+              inner_template.call(output, inner_context)
+              index += 1
+            end
+          else
+            # Other enumerable objects
+            index = 0
+            c.value.each do |item|
+              inner_context = ContextObject.new
+              inner_context.value = item
+              inner_context.key = "[#{index}]"
+              inner_context.parent = c
+
+              inner_template.call(output, inner_context)
+              index += 1
+            end
+          end
+        else
+          raise IndexedParseException.new(
+            "",
+            nil,
+            "'%s' is used like an array by the template, but is a scalar value or object in your model.",
+            token.value
+          )
+        end
+      end
+    end
+
+    def self.handle_element_open(token, remainder, options, scope)
+      if scope
+        scope.get_inferred_model_for_path(token.value, UsedAs::CONDITIONAL_VALUE)
+      end
+
+      inner_template = parse_tokens(remainder, options, scope)
+
+      lambda do |output, context|
+        c = context.get_context_for_path(token.value)
+        if c.exists?
+          inner_template.call(output, c)
+        end
+      end
+    end
+  end
+end

data/lib/mustachio_ruby/parsing_options.rb

@@ -0,0 +1,11 @@
+module MustachioRuby
+  class ParsingOptions
+    attr_accessor :disable_content_safety, :source_name, :token_expanders
+
+    def initialize
+      @disable_content_safety = false
+      @source_name = ""
+      @token_expanders = []
+    end
+  end
+end

data/lib/mustachio_ruby/token_expander.rb

@@ -0,0 +1,15 @@
+module MustachioRuby
+  module Precedence
+    LOW = :low
+    MEDIUM = :medium
+    HIGH = :high
+  end
+
+  class TokenExpander
+    attr_accessor :regex, :precedence, :expand_tokens, :renderer
+
+    def initialize
+      @precedence = Precedence::MEDIUM
+    end
+  end
+end

data/lib/mustachio_ruby/token_tuple.rb

@@ -0,0 +1,28 @@
+module MustachioRuby
+  module TokenType
+    ESCAPED_SINGLE_VALUE = :escaped_single_value
+    UNESCAPED_SINGLE_VALUE = :unescaped_single_value
+    INVERTED_ELEMENT_OPEN = :inverted_element_open
+    ELEMENT_OPEN = :element_open
+    ELEMENT_CLOSE = :element_close
+    COMMENT = :comment
+    CONTENT = :content
+    COLLECTION_OPEN = :collection_open
+    COLLECTION_CLOSE = :collection_close
+    CUSTOM = :custom
+  end
+
+  class TokenTuple
+    attr_accessor :type, :value, :renderer
+
+    def initialize(type, value, renderer = nil)
+      @type = type
+      @value = value
+      @renderer = renderer
+    end
+
+    def to_s
+      "#{@type}, #{@value}"
+    end
+  end
+end

data/lib/mustachio_ruby/tokenize_result.rb

@@ -0,0 +1,10 @@
+module MustachioRuby
+  class TokenizeResult
+    attr_accessor :tokens, :errors
+
+    def initialize
+      @tokens = []
+      @errors = []
+    end
+  end
+end

data/lib/mustachio_ruby/tokenizer.rb

@@ -0,0 +1,230 @@
+module MustachioRuby
+  class Tokenizer
+    TOKEN_FINDER = /(\{\{[^{}]+?\}\})|(\{\{\{[^{}]+?\}\}\})/
+    NEWLINE_FINDER = /\n/
+    NEGATIVE_PATH_SPEC = /(\.{3,})|([^\w.\/_]+)|((?<!\.{2})[\/])|(\.{2,}($|[^\/]))/
+
+    def self.tokenize(template_string, parsing_options)
+      template_string ||= ""
+      matches = template_string.scan(TOKEN_FINDER).flatten.compact
+      scope_stack = []
+      source_name = parsing_options.source_name
+
+      idx = 0
+      tokens = []
+      parse_errors = []
+      lines = nil
+
+      template_string.scan(/(\{\{[^{}]+?\}\})|(\{\{\{[^{}]+?\}\}\})/) do |match|
+        token_match = match.compact.first
+        match_start = $~.begin(0)
+
+        # Add content before token
+        if match_start > idx
+          content = template_string[idx...match_start]
+          tokens << TokenTuple.new(TokenType::CONTENT, content)
+        end
+
+        process_token(token_match, match_start, template_string, tokens, parse_errors,
+                     scope_stack, source_name, parsing_options, lines)
+
+        idx = match_start + token_match.length
+      end
+
+      # Add remaining content
+      if idx < template_string.length
+        tokens << TokenTuple.new(TokenType::CONTENT, template_string[idx..-1])
+      end
+
+      # Check for unclosed scopes
+      unless scope_stack.empty?
+        scope_stack.reverse.each do |scope_info|
+          value = scope_info[:value].gsub(/[\{\}#]/, '').strip
+          value = value.sub(/^each /, '') if value.start_with?('each ')
+          location = humanize_character_location(template_string, scope_info[:index], lines)
+
+          parse_errors << IndexedParseException.new(
+            source_name,
+            location,
+            "A scope block to the following path was opened but not closed: '%s', please close it using the appropriate syntax.",
+            value
+          )
+        end
+      end
+
+      result = TokenizeResult.new
+      result.tokens = tokens
+      result.errors = parse_errors
+      result
+    end
+
+    private
+
+    def self.process_token(token_match, match_start, template_string, tokens, parse_errors,
+                          scope_stack, source_name, parsing_options, lines)
+
+      if token_match.match?(/^{{#each(\s|$)/)
+        handle_each_open(token_match, match_start, template_string, tokens, parse_errors,
+                        scope_stack, source_name, lines)
+      elsif token_match == "{{/each}}"
+        handle_each_close(token_match, match_start, template_string, tokens, parse_errors,
+                         scope_stack, source_name, lines)
+      elsif token_match.start_with?("{{#")
+        handle_element_open(token_match, match_start, template_string, tokens, parse_errors,
+                           scope_stack, source_name, lines)
+      elsif token_match.start_with?("{{^")
+        handle_inverted_element_open(token_match, match_start, template_string, tokens,
+                                   parse_errors, scope_stack, source_name, lines)
+      elsif token_match.start_with?("{{/")
+        handle_element_close(token_match, match_start, template_string, tokens, parse_errors,
+                            scope_stack, source_name, lines)
+      elsif token_match.start_with?("{{{") || token_match.start_with?("{{&")
+        handle_unescaped_value(token_match, match_start, template_string, tokens,
+                              parse_errors, source_name, lines)
+      elsif token_match.start_with?("{{!")
+        # Comment - ignore
+      else
+        handle_escaped_value(token_match, match_start, template_string, tokens,
+                            parse_errors, source_name, lines)
+      end
+    end
+
+    def self.handle_each_open(token_match, match_start, template_string, tokens, parse_errors,
+                             scope_stack, source_name, lines)
+      scope_stack << { value: token_match, index: match_start }
+      token_value = token_match.gsub(/[\{\}#]/, '').strip
+      token_value = token_value.sub(/^each/, '').strip
+
+      if token_value.empty?
+        location = humanize_character_location(template_string, match_start, lines)
+        parse_errors << IndexedParseException.new(
+          source_name,
+          location,
+          "The 'each' block being opened requires a model path to be specified in the form '{{#each <name>}}'."
+        )
+      else
+        validated_token = validate_token(token_value, template_string, match_start,
+                                       source_name, lines, parse_errors)
+        tokens << TokenTuple.new(TokenType::COLLECTION_OPEN, validated_token)
+      end
+    end
+
+    def self.handle_each_close(token_match, match_start, template_string, tokens, parse_errors,
+                              scope_stack, source_name, lines)
+      if !scope_stack.empty? && scope_stack.last[:value].match?(/^{{#each(\s|$)/)
+        scope_info = scope_stack.pop
+        tokens << TokenTuple.new(TokenType::COLLECTION_CLOSE, scope_info[:value])
+      else
+        location = humanize_character_location(template_string, match_start, lines)
+        parse_errors << IndexedParseException.new(
+          source_name,
+          location,
+          "An 'each' block is being closed, but no corresponding opening element ('{{#each <name>}}') was detected."
+        )
+      end
+    end
+
+    def self.handle_element_open(token_match, match_start, template_string, tokens, parse_errors,
+                                scope_stack, source_name, lines)
+      token_value = token_match.gsub(/[\{\}#]/, '').strip
+
+      if !scope_stack.empty? && scope_stack.last[:value] == token_value
+        validated_token = validate_token(token_value, template_string, match_start,
+                                       source_name, lines, parse_errors)
+        tokens << TokenTuple.new(TokenType::ELEMENT_CLOSE, validated_token)
+      else
+        scope_stack << { value: token_value, index: match_start }
+      end
+
+      validated_token = validate_token(token_value, template_string, match_start,
+                                     source_name, lines, parse_errors)
+      tokens << TokenTuple.new(TokenType::ELEMENT_OPEN, validated_token)
+    end
+
+    def self.handle_inverted_element_open(token_match, match_start, template_string, tokens,
+                                         parse_errors, scope_stack, source_name, lines)
+      token_value = token_match.gsub(/[\{\}\^]/, '').strip
+
+      if !scope_stack.empty? && scope_stack.last[:value] == token_value
+        validated_token = validate_token(token_value, template_string, match_start,
+                                       source_name, lines, parse_errors)
+        tokens << TokenTuple.new(TokenType::ELEMENT_CLOSE, validated_token)
+      else
+        scope_stack << { value: token_value, index: match_start }
+      end
+
+      validated_token = validate_token(token_value, template_string, match_start,
+                                     source_name, lines, parse_errors)
+      tokens << TokenTuple.new(TokenType::INVERTED_ELEMENT_OPEN, validated_token)
+    end
+
+    def self.handle_element_close(token_match, match_start, template_string, tokens, parse_errors,
+                                 scope_stack, source_name, lines)
+      token_value = token_match.gsub(/[\{\}\/]/, '').strip
+
+      if !scope_stack.empty? && scope_stack.last[:value] == token_value
+        scope_stack.pop
+        validated_token = validate_token(token_value, template_string, match_start,
+                                       source_name, lines, parse_errors)
+        tokens << TokenTuple.new(TokenType::ELEMENT_CLOSE, validated_token)
+      else
+        location = humanize_character_location(template_string, match_start, lines)
+        parse_errors << IndexedParseException.new(
+          source_name,
+          location,
+          "It appears that open and closing elements are mismatched."
+        )
+      end
+    end
+
+    def self.handle_unescaped_value(token_match, match_start, template_string, tokens,
+                                   parse_errors, source_name, lines)
+      token_value = token_match.gsub(/[\{\}&]/, '').strip
+      validated_token = validate_token(token_value, template_string, match_start,
+                                     source_name, lines, parse_errors)
+      tokens << TokenTuple.new(TokenType::UNESCAPED_SINGLE_VALUE, validated_token)
+    end
+
+    def self.handle_escaped_value(token_match, match_start, template_string, tokens,
+                                 parse_errors, source_name, lines)
+      token_value = token_match.gsub(/[\{\}]/, '').strip
+      validated_token = validate_token(token_value, template_string, match_start,
+                                     source_name, lines, parse_errors)
+      tokens << TokenTuple.new(TokenType::ESCAPED_SINGLE_VALUE, validated_token)
+    end
+
+    def self.validate_token(token, content, index, source_name, lines, exceptions)
+      token = token.strip
+
+      if NEGATIVE_PATH_SPEC.match(token)
+        location = humanize_character_location(content, index, lines)
+        exceptions << IndexedParseException.new(
+          source_name,
+          location,
+          "The path '%s' is not valid. Please see documentation for examples of valid paths.",
+          token
+        )
+      end
+
+      token
+    end
+
+    def self.humanize_character_location(content, character_index, lines)
+      lines ||= content.enum_for(:scan, NEWLINE_FINDER).map { Regexp.last_match.begin(0) }
+
+      line = lines.bsearch_index { |pos| pos > character_index } || lines.length
+      char_idx = character_index
+
+      if line > 0 && line <= lines.length
+        char_idx = character_index - (lines[line - 1] + 1)
+      elsif line > 0
+        char_idx = character_index - (lines.last + 1) if !lines.empty?
+      end
+
+      {
+        line: line + 1,
+        character: char_idx + 1
+      }
+    end
+  end
+end

data/lib/mustachio_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MustachioRuby
+  VERSION = "0.1.0"
+end

data/lib/mustachio_ruby.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "mustachio_ruby/version"
+require_relative "mustachio_ruby/parser"
+require_relative "mustachio_ruby/tokenizer"
+require_relative "mustachio_ruby/context_object"
+require_relative "mustachio_ruby/parsing_options"
+require_relative "mustachio_ruby/token_tuple"
+require_relative "mustachio_ruby/token_expander"
+require_relative "mustachio_ruby/tokenize_result"
+require_relative "mustachio_ruby/inferred_template_model"
+require_relative "mustachio_ruby/extended_parse_information"
+require_relative "mustachio_ruby/indexed_parse_exception"
+
+module MustachioRuby
+  class << self
+    def parse(template, options = ParsingOptions.new)
+      Parser.parse(template, options)
+    end
+
+    def parse_with_model_inference(template, options = ParsingOptions.new)
+      Parser.parse_with_model_inference(template, options)
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: mustachio-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- João Victor Assis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby port of the Postmark C# Mustachio templating engine with model
+  inference and extensible token support
+email:
+- joaovictorass95@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mustachio_ruby.rb
+- lib/mustachio_ruby/context_object.rb
+- lib/mustachio_ruby/extended_parse_information.rb
+- lib/mustachio_ruby/indexed_parse_exception.rb
+- lib/mustachio_ruby/inferred_template_model.rb
+- lib/mustachio_ruby/parser.rb
+- lib/mustachio_ruby/parsing_options.rb
+- lib/mustachio_ruby/token_expander.rb
+- lib/mustachio_ruby/token_tuple.rb
+- lib/mustachio_ruby/tokenize_result.rb
+- lib/mustachio_ruby/tokenizer.rb
+- lib/mustachio_ruby/version.rb
+homepage: https://github.com/bleu/mustachio-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/bleu/mustachio-ruby
+  source_code_uri: https://github.com/bleu/mustachio-ruby
+  changelog_uri: https://github.com/bleu/mustachio-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A powerful templating engine for Ruby
+test_files: []