Merge pull request #9 from gi:release/0.3.0

v0.3.0

Author: gi

.github/workflows/ci.yml

@@ -11,6 +11,19 @@ on:
       - main
 
 jobs:
+  build:
+    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: Build
+        run: bin/build
+
   coverage:
     runs-on: ubuntu-latest
     steps:
@@ -41,7 +54,7 @@ jobs:
           ruby-version: ruby-3
           bundler-cache: true
       - name: Lint
-        run: bundle exec rubocop
+        run: bin/lint
 
   test:
     strategy:
@@ -66,4 +79,4 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
       - name: Test
-        run: bundle exec rake
+        run: bin/rake

.github/workflows/publish.yml

@@ -4,8 +4,6 @@ on:
   push:
     branches:
       - main
-    paths:
-      - lib/**/version
 
 permissions:
   contents: write
@@ -14,6 +12,7 @@ permissions:
 jobs:
   github:
     name: GitHub
+    needs: tag
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -29,6 +28,7 @@ jobs:
         run: bin/release
   rubygems:
     name: RubyGems
+    needs: tag
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -42,3 +42,16 @@ jobs:
         env:
           GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_TOKEN}}"
         run: bin/release
+  tag:
+    name: Git Tag
+    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: Tag
+        run: bin/tag

.rubocop.yml

@@ -138,6 +138,10 @@ Metrics/ModuleLength:
 Metrics/ParameterLists:
   Max: 10
 
+Naming/FileName:
+  Exclude:
+    - lib/handlebars-engine.rb
+
 RSpec/ExampleLength:
   CountAsOne:
     - array

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2022-01-31
+
+### Added
+- `initialize`: add path parameter ([#5](https://github.com/gi/handlebars-ruby/pull/5))
+- `register_helper`: accept multiple helpers as keyword parameters ([#6](https://github.com/gi/handlebars-ruby/pull/6))
+- `register_helper`: accept javascript function as string ([#7](https://github.com/gi/handlebars-ruby/pull/7))
+- `ci`: verify gem builds ([#8](https://github.com/gi/handlebars-ruby/pull/8))
+- `require`: allow loading from `handlebars-engine` and `handlebars/engine` ([#8](https://github.com/gi/handlebars-ruby/pull/8))
+
 ## [0.2.0] - 2022-01-27
 
 This is the initial implementation, wrapping the JavaScript Handlebars.

README.md

@@ -82,6 +82,32 @@ See https://handlebarsjs.com/guide/#custom-helpers.
 
 ### Block Helpers
 
+Block helpers make it possible to define custom iterators and other
+functionality that can invoke the passed block with a new context.
+
+Currently, there is a limitation with the underlying JavaScript engine: it does
+not allow for reentrant calls from within attached Ruby functions: see
+[MiniRacer#225](https://github.com/rubyjs/mini_racer/issues/225). Thus, the
+block function returned to the helper (in `options.fn`) cannot be  invoked.
+
+Thus, for block helpers, a string of JavaScript must define the helper function:
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper(map: <<~JS)
+  function(...args) {
+    const ctx = this;
+    const opts = args.pop();
+    const items = args[0];
+    const separator = args[1];
+    const mapped = items.map((item) => opts.fn(item));
+    return mapped.join(separator);
+  }
+JS
+template = handlebars.compile("{{#map items '|'}}'{{this}}'{{/map}}")
+template.call({ items: [1, 2, 3] })
+# => "'1'|2'|'3'"
+```
+
 See https://handlebarsjs.com/guide/#block-helpers.
 
 ### Partials

bin/handlebars-engine bin/handlebarsbin/handlebars-engine renamed to bin/handlebars

@@ -4,7 +4,7 @@
 #
 # This file was generated by Bundler.
 #
-# The application 'handlebars-engine' is installed as part of a gem, and
+# The application 'handlebars' is installed as part of a gem, and
 # this file is here to facilitate running it.
 #
 
@@ -26,4 +26,4 @@ end
 require "rubygems"
 require "bundler/setup"
 
-load Gem.bin_path("handlebars-engine", "handlebars-engine")
+load Gem.bin_path("handlebars-engine", "handlebars")

bin/tag

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+dir="$(cd "$(dirname "${BASH_SOURCE[0]}" )" && pwd)"
+
+branch=$(git rev-parse --abbrev-ref HEAD)
+
+if [[ "${branch}" != "main" ]]; then
+  echo "Releases are restricted to the main branch."
+  exit 1
+fi
+
+diff=$(git diff HEAD --quiet; echo $?)
+
+if [[ "${diff}" != "0" ]]; then
+  echo "Releases are restricted to clean branches."
+  exit 1
+fi
+
+if [[ -n "${CI}" ]]; then
+  git config --global user.email "gi+handlebars-ruby@users.noreply.github.com"
+  git config --global user.name "handlebars-ruby"
+  git fetch --tags
+fi
+
+"${dir}/rake" release:source_control_push

lib/handlebars-engine.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "handlebars/engine"

lib/handlebars/engine.rb

@@ -16,7 +16,10 @@ class Engine
     #
     # @param lazy [true, false] immediately loads and initializes the JavaScript
     #   environment.
-    def initialize(lazy: false)
+    # @param path [String, nil] the path to the version of Handlebars to load.
+    #   If `nil`, the contents of `Handlebars::Source.bundled_path` is loaded.
+    def initialize(lazy: false, path: nil)
+      @path = path
       init! unless lazy
     end
 
@@ -60,14 +63,29 @@ def template(*args)
 
     # Registers helpers accessible by any template in the environment.
     #
+    # The function can be either a proc or a string:
+    # * When the function is a proc, it can be either passed in as a normal
+    #   parameter or as a block.
+    # * When the function is a string, it is interpreted as a JavaScript
+    #   function.
+    #
     # @param name [String, Symbol] the name of the helper
+    # @param function [Proc, String] the helper function
     # @yieldparam context [Hash] the current context
     # @yieldparam arguments [Object] the arguments (optional)
     # @yieldparam options [Hash] the options hash (optional)
     # @see https://handlebarsjs.com/api-reference/runtime.html#handlebars-registerhelper-name-helper
-    def register_helper(name, &block)
-      attach(name, &block)
-      call(:registerHelper, [name.to_s, name.to_sym], eval: true)
+    def register_helper(name = nil, function = nil, **helpers, &block)
+      helpers[name] = block || function if name
+      helpers.each do |n, f|
+        case f
+        when Proc
+          attach(n, &f)
+          evaluate("registerHelper('#{n}', #{n})")
+        when String, Symbol
+          evaluate("Handlebars.registerHelper('#{n}', #{f})")
+        end
+      end
     end
 
     # Unregisters a previously registered helper.
@@ -204,21 +222,14 @@ def init!
       return if @init
 
       @context = MiniRacer::Context.new
-      @context.load(::Handlebars::Source.bundled_path)
+      @context.load(@path || ::Handlebars::Source.bundled_path)
       @context.load(File.absolute_path("engine/init.js", __dir__))
 
       @init = true
     end
 
     def js_args(args)
-      args.map { |arg|
-        case arg
-        when Symbol
-          arg
-        else
-          JSON.generate(arg)
-        end
-      }
+      args.map { |arg| JSON.generate(arg) }
     end
   end
 end

lib/handlebars/engine/version.rb

@@ -2,6 +2,6 @@
 
 module Handlebars
   class Engine
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end