handlebars-engine 0.2.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6bc490b95cc268a0cc7ee638660caecbfe9d978a13335b8c3588f89e16c3db
-  data.tar.gz: 014eb30c05c4edba8b9f9a340e3539a8542edabd94954efa189b2611456e10d8
+  metadata.gz: 554df376a361ca161ddf847bbe992c6d75d1cac32ba355d16c22a849781462fc
+  data.tar.gz: ec2e1de82a986c6dd024b1ec90af293c39f49becf8d03a628625b3cf5beada10
 SHA512:
-  metadata.gz: a092e8fdae258e997d6afb3505b20a67898caf7d08bfd37efee1a50f663b0e084648902b6d396fe392acb46a8e5587deee277e2ec750f31ce103ad8dd42d1d6b
-  data.tar.gz: 99c271de356730e76c660fb806d8dd619edb0f522951a5e822f6460e0e415c02e20311aab2e5be55e89f9b2ffd161e87b75784726512df26d5c59d002ec06f9a
+  metadata.gz: d4e2470b91cae56cc9f6f18c079d763c10babd1eaa66d0660b13f68afce67f9513504f1515b12a6850739d0b9b19fa47a64c2e57e040fc34ebbbd43694cba55d
+  data.tar.gz: 0270460ce862b0e079f27b96e20829e28d84059a5b3f4d0d2301fd5257d62804cc35489db0cf39aed45c263ae74144f10fa573a89e352ee21e8b119ef9ea023b

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2022-02-17
+
+### Changed
+- `engine/function`: remove object finalizer (fixes [#14](https://github.com/gi/handlebars-ruby/issues/14))
+
+## [0.3.2] - 2022-02-17
+
+### Changed
+- `engine`: fixed issue with memory leak ([#15](https://github.com/gi/handlebars-ruby/pull/15))
+
+## [0.3.1] - 2022-02-04
+
+### Added
+- `engine`: added `Error` class
+- `specs`: added tests for (pre)compiling with options
+
+### Changed
+- `gem`/`readme`: updated description
+
+## [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.

data/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
 
@@ -82,6 +92,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

data/lib/handlebars/engine/function.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Handlebars
+  class Engine
+    # A proxy for a JavaScript function defined in the context.
+    class Function
+      def initialize(context, name)
+        @context = context
+        @name = name
+      end
+
+      def call(*args)
+        @context.call(@name, *args)
+      end
+    end
+  end
+end

data/lib/handlebars/engine/version.rb

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

data/lib/handlebars/engine.rb

@@ -4,6 +4,7 @@ require "handlebars/source"
 require "json"
 require "mini_racer"
 require "securerandom"
+require_relative "engine/function"
 require_relative "engine/version"
 
 module Handlebars
@@ -12,11 +13,16 @@ 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
     #   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 +66,29 @@ module Handlebars
 
     # 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.
@@ -179,9 +200,7 @@ module Handlebars
       result = evaluate(code)
 
       if var && result.is_a?(MiniRacer::JavaScriptFunction)
-        result = ->(*a) { @context.call(var, *a) }
-        finalizer = ->(*) { evaluate("delete #{var}") }
-        ObjectSpace.define_finalizer(result, finalizer)
+        result = Function.new(@context, var)
       end
 
       result
@@ -204,21 +223,14 @@ module Handlebars
       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

data/lib/handlebars-engine.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: handlebars-engine
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.3
 platform: ruby
 authors:
 - Zach Gianos
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-01-27 00:00:00.000000000 Z
+date: 2022-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: handlebars-source
@@ -38,7 +38,16 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "    A simple interface to Handlebars.js for Ruby.\n"
+description: |2
+      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.
 email:
 - zach.gianos+git@gmail.com
 executables:
@@ -50,7 +59,9 @@ files:
 - LICENSE
 - README.md
 - exe/handlebars
+- lib/handlebars-engine.rb
 - lib/handlebars/engine.rb
+- lib/handlebars/engine/function.rb
 - lib/handlebars/engine/init.js
 - lib/handlebars/engine/version.rb
 homepage: https://github.com/gi/handlebars-ruby
@@ -61,7 +72,7 @@ metadata:
   github_repo: https://github.com/gi/handlebars-ruby
   homepage_uri: https://github.com/gi/handlebars-ruby
   source_code_uri: https://github.com/gi/handlebars-ruby
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -76,8 +87,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
-signing_key:
+rubygems_version: 3.3.3
+signing_key: 
 specification_version: 4
-summary: A simple interface to Handlebars.js for Ruby.
+summary: A complete interface to Handlebars.js for Ruby.
 test_files: []