v0.2.0: initial implementation

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: ruby-3.0
+          ruby-version: ruby-3
           bundler-cache: true
       - name: Test
         run: bundle exec rake
@@ -38,7 +38,7 @@ jobs:
       - name: Install
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: ruby-3.0
+          ruby-version: ruby-3
           bundler-cache: true
       - name: Lint
         run: bundle exec rubocop
@@ -47,12 +47,13 @@ jobs:
     strategy:
       matrix:
         os:
-          # - macos-latest
+          - macos-latest
           - ubuntu-latest
         ruby:
           - ruby-2.6
           - ruby-2.7
           - ruby-3.0
+          - ruby-3.1
           # - jruby
           # - truffleruby
     runs-on: ${{ matrix.os }}

.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  github:
+    name: GitHub
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Install
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby-3
+          bundler-cache: true
+      - name: Publish to GitHub
+        env:
+          GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+          RUBYGEMS_HOST: https://rubygems.pkg.github.com/${{github.repository_owner}}
+        run: bin/release
+  rubygems:
+    name: RubyGems
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Install
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby-3
+          bundler-cache: true
+      - name: Publish to RubyGems
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_TOKEN}}"
+        run: bin/release

.gitignore

@@ -1,4 +1,5 @@
 /[._]*/
+!/.github/
 /doc/
 /pkg/
 /spec/reports/

.rubocop.yml

@@ -119,9 +119,6 @@ Metrics/ClassLength:
     - heredoc
   Max: 120
 
-Metrics/CyclomaticComplexity:
-  Max: 10
-
 Metrics/MethodLength:
   CountAsOne:
     - array
@@ -138,8 +135,14 @@ Metrics/ModuleLength:
 Metrics/ParameterLists:
   Max: 10
 
+RSpec/ExampleLength:
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
 RSpec/MultipleMemoizedHelpers:
-  Max: 10
+  Max: 20
 
 RSpec/NestedGroups:
   Max: 8

CHANGELOG.md

@@ -6,3 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [0.2.0] - 2022-01-27
+
+This is the initial implementation, wrapping the JavaScript Handlebars.
+
+### Added
+- `Handlebars::Engine#compile`
+- `Handlebars::Engine#precompile`
+- `Handlebars::Engine#template`
+- `Handlebars::Engine#register_helper`
+- `Handlebars::Engine#unregister_helper`
+- `Handlebars::Engine#register_partial`
+- `Handlebars::Engine#unregister_partial`
+- `Handlebars::Engine#register_helper_missing`
+- `Handlebars::Engine#unregister_helper_missing`
+- `Handlebars::Engine#register_partial_missing`
+- `Handlebars::Engine#unregister_partial_missing`
+- `Handlebars::Engine#version`
+
+## [0.1.0] - 2022-01-13
+
+This is the initial package.
+
+### Added
+- gem init

README.md

@@ -26,7 +26,144 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Quick Start
+
+```ruby
+handlebars = Handlebars::Engine.new
+template = handlebars.compile("{{firstname}} {{lastname}}")
+template.call({ firstname: "Yehuda", lastname: "Katz" })
+# => "Yehuda Katz"
+```
+
+### Custom Helpers
+
+Handlebars helpers can be accessed from any context in a template. You can
+register a helper with the `register_helper` method:
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper(:loud) do |ctx, arg, opts|
+  arg.upcase
+end
+template = handlebars.compile("{{firstname}} {{loud lastname}}")
+template.call({ firstname: "Yehuda", lastname: "Katz" })
+# => "Yehuda KATZ"
+```
+
+#### Helper Arguments
+
+Helpers receive the current context as the first argument of the block.
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper(:full_name) do |ctx, opts|
+  "#{ctx["firstname"]} #{ctx["lastname"]}"
+end
+template = handlebars.compile("{{full_name}}")
+template.call({ firstname: "Yehuda", lastname: "Katz" })
+# => "Yehuda Katz"
+```
+
+Any arguments to the helper are included as individual positional arguments.
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper(:join) do |ctx, *args, opts|
+  args.join(" ")
+end
+template = handlebars.compile("{{join firstname lastname}}")
+template.call({ firstname: "Yehuda", lastname: "Katz" })
+# => "Yehuda Katz"
+```
+
+The last argument is a hash of options.
+
+See https://handlebarsjs.com/guide/#custom-helpers.
+
+### Block Helpers
+
+See https://handlebarsjs.com/guide/#block-helpers.
+
+### Partials
+
+Handlebars partials allow for code reuse by creating shared templates.
+
+You can register a partial using the `register_partial` method:
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_partial(:person, "{{person.name}} is {{person.age}}.")
+template = handlebars.compile("{{> person person=.}}")
+template.call({ name: "Yehuda Katz", age: 20 })
+# => "Yehuda Katz is 20."
+```
+
+See https://handlebarsjs.com/guide/#partials.
+See https://handlebarsjs.com/guide/partials.html.
+
+### Hooks
+
+#### Helper Missing
+
+This hook is called for a mustache or a block-statement when
+* a simple mustache-expression is not a registered helper, *and*
+* it is not a property of the current evaluation context.
+
+You can add custom handling for those situations by registering a helper with
+the `register_helper_missing` method:
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper_missing do |ctx, *args, opts|
+  "Missing: #{opts["name"]}(#{args.join(", ")})"
+end
+
+template = handlebars.compile("{{foo 2 true}}")
+template.call
+# => "Missing: foo(2, true)"
+
+template = handlebars.compile("{{#foo true}}{{/foo}}")
+template.call
+# => "Missing: foo(true)"
+```
+
+See https://handlebarsjs.com/guide/hooks.html#helpermissing.
+
+##### Blocks
+
+This hook is called for a block-statement when
+* a block-expression calls a helper that is not registered, *and*
+* the name is a property of the current evaluation context.
+
+You can add custom handling for those situations by registering a helper with
+the `register_helper_missing` method (with a `:block` argument):
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper_missing(:block) do |ctx, *args, opts|
+  "Missing: #{opts["name"]}(#{args.join(", ")})"
+end
+
+template = handlebars.compile("{{#person}}{{name}}{{/person}}")
+template.call({ person: { name: "Yehuda Katz" } })
+# => "Missing: person"
+```
+
+See https://handlebarsjs.com/guide/hooks.html#blockhelpermissing.
+
+#### Partial Missing
+
+This hook is called for a partial that is not registered.
+
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_partial_missing do |name|
+  "partial: #{name}"
+end
+```
+
+Note: This is not a part of the offical Handlebars API. It is provided for
+convenience.
 
 ## Changelog
 

handlebars-engine.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name = "handlebars-engine"
   spec.version = Handlebars::Engine::VERSION
   spec.authors = ["Zach Gianos"]
-  spec.email = ["zach.gianos@gmail.com"]
+  spec.email = ["zach.gianos+git@gmail.com"]
 
   spec.summary = "A simple interface to Handlebars.js for Ruby."
   spec.description = <<-DESCRIPTION
@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.6.0"
 
   spec.metadata["changelog_uri"] = "#{spec.homepage}/CHANGELOG.md"
+  spec.metadata["github_repo"] = spec.homepage
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["rubygems_mfa_required"] = "true"
   spec.metadata["source_code_uri"] = spec.homepage
@@ -35,4 +36,7 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_dependency "handlebars-source"
+  spec.add_dependency "mini_racer"
 end