readme/specs: update description and test compile with options (#11)

* update description
* test compile with options

Author: gi

CONTRIBUTING.md

@@ -1,5 +1,18 @@
 # Contributing
 
+Bug reports and pull requests are welcome on GitHub:
+https://github.com/gi/handlebars-ruby.
+
+1. Fork the repository: https://github.com/gi/handlebars-ruby.
+1. Create an issue branch: `git checkout -b issue-N/summary origin/develop`)
+1. Run [setup](#Setup): `bin/setup`.
+1. Add tests for your updates.
+1. Run [tests](#Test): `bin/test`.
+1. Run linter: `bin/lint`.
+1. Commit changes: `git commit -am '[#N] Summary'`.
+1. Push changes: `git push origin head`.
+1. Create a pull request targeting `develop`.
+
 ## Branches
 
 This repository follows a modified version of the

README.md

@@ -1,12 +1,22 @@
 # Handlebars::Engine
 
 [![Gem Version](https://badge.fury.io/rb/handlebars-engine.svg)](https://rubygems.org/gems/handlebars-engine)
-[![Build Status](https://github.com/gi/handlebars-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/gi/handlebars-ruby/actions/workflows/ci.yml)
+[![CI Status](https://github.com/gi/handlebars-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/gi/handlebars-ruby/actions/workflows/ci.yml)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/45d98ad9e12ee3384161/test_coverage)](https://codeclimate.com/github/gi/handlebars-ruby/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/45d98ad9e12ee3384161/maintainability)](https://codeclimate.com/github/gi/handlebars-ruby/maintainability)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-A simple interface to [Handlebars.js](https://handlebarsjs.com) for Ruby.
+A complete interface to [Handlebars.js](https://handlebarsjs.com) for Ruby.
+
+`Handlebars::Engine` provides a complete Ruby API for the official JavaScript
+version of Handlebars, including the abilities to register Ruby blocks/procs as
+Handlebars helper functions and to dynamically register partials.
+
+It uses [MiniRacer](https://github.com/rubyjs/mini_racer) for the bridge between
+Ruby and the V8 JavaScript engine.
+
+`Handlebars::Engine` was created as a replacement for
+[handlebars.rb](https://github.com/cowboyd/handlebars.rb).
 
 ## Installation
 

handlebars-engine.gemspec

@@ -8,9 +8,17 @@ Gem::Specification.new do |spec|
   spec.authors = ["Zach Gianos"]
   spec.email = ["zach.gianos+git@gmail.com"]
 
-  spec.summary = "A simple interface to Handlebars.js for Ruby."
+  spec.summary = "A complete interface to Handlebars.js for Ruby."
   spec.description = <<-DESCRIPTION
-    A simple interface to Handlebars.js for Ruby.
+    A complete interface to Handlebars.js for Ruby.
+
+    Handlebars::Engine provides a complete Ruby API for the official JavaScript
+    version of Handlebars, including the abilities to register Ruby blocks/procs
+    as Handlebars helper functions and to dynamically register partials.
+
+    It uses MiniRacer for the bridge between Ruby and the V8 JavaScript engine.
+
+    Handlebars::Engine was created as a replacement for handlebars.rb.
   DESCRIPTION
 
   spec.homepage = "https://github.com/gi/handlebars-ruby"

lib/handlebars/engine.rb

@@ -12,6 +12,8 @@ module Handlebars
   # This API follows the JavaScript API as closely as possible:
   # https://handlebarsjs.com/api-reference/.
   class Engine
+    Error = MiniRacer::RuntimeError
+
     # Creates a new instance.
     #
     # @param lazy [true, false] immediately loads and initializes the JavaScript

spec/handlebars/engine_spec.rb

@@ -92,7 +92,7 @@
   shared_examples "rendering" do |error: false|
     if error
       it "raises an error" do
-        expect { render }.to raise_error(MiniRacer::RuntimeError)
+        expect { render }.to raise_error(Handlebars::Engine::Error)
       end
     else
       it "renders the template" do
@@ -101,6 +101,27 @@
     end
   end
 
+  shared_examples "compiling with options" do
+    let(:template_options) { {} }
+
+    describe "knownHelpers" do
+      let(:render_context) { { age: -30 } }
+      let(:rendered) { "Hello, you are 30!" }
+      let(:template) { "Hello, you are {{abs age}}!" }
+
+      before do
+        engine.register_helper(:abs) { |_ctx, age, _opts| age.abs }
+        template_options[:knownHelpers] = {
+          abs: true,
+        }
+      end
+
+      describe "rendering" do
+        include_examples "rendering"
+      end
+    end
+  end
+
   describe "#compile" do
     let(:renderer) { engine.compile(template, template_options) }
 
@@ -111,6 +132,8 @@
     describe "return value" do
       it_behaves_like "renderer"
     end
+
+    it_behaves_like "compiling with options"
   end
 
   describe "#precompile" do
@@ -138,6 +161,8 @@
     describe "return value" do
       it_behaves_like "renderer"
     end
+
+    it_behaves_like "compiling with options"
   end
 
   ###################################