handlebars-engine 0.1.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5687452a43187e2eb02f0f14b8cdfbb9326f7a45324aff57036ca6f40f1e3f1b
-  data.tar.gz: f6f11a588f3db269fd34beb13e5c74ed0c8d15e8533e6dca1f99d6fa6737ae8f
+  metadata.gz: 93107a1a86ac4a02cadbbfd8221cba9515ff839e948e39dc37c61a3de1d15400
+  data.tar.gz: '0091362554954a3f86ab24b7c0bc701595818b9b72af4b8780bccd3d6e4193ec'
 SHA512:
-  metadata.gz: 19f3131b68bb2b4062e30c730becb77efdf9d62b057863d2b2e2c97369ddab4216c1d08eb370070b1f9e5950ff75015414a72c6b04d8c0df277954ee2beedc9a
-  data.tar.gz: b28fbad17ce848de5b10a6a023a6ee227c0c2175d996587338f726f320b9e9f75995b3927662005c35d3460b8c5fc2d9f27f40c962e6b4fd628f8355035b457d
+  metadata.gz: 7cd86ebb6fbeb64acd29dc3c4cb0f6853a7193983c53e05d32e42490a38b70f37c8d99ae7b214e3f76923c7931b46c1d3dcda1326339dfcdfa00ec29be745ae9
+  data.tar.gz: 6f5fd77a08e73e9f2b9f40c1c769f2eca5a0359a35e9aa02ca9fd7d430e83e8f61d6c26541f0b2bbaf5caf3ff990663962cdedfc5dd61e8892c842a8b6404fec

data/CHANGELOG.md

@@ -6,3 +6,51 @@ 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.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.
+
+### 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

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
 
@@ -26,7 +36,170 @@ 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
+
+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
+
+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
 

data/lib/handlebars/engine/function.rb

@@ -0,0 +1,27 @@
+# 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
+        ObjectSpace.define_finalizer(self, self.class.finalizer(context, name))
+      end
+
+      def call(*args)
+        @context.call(@name, *args)
+      end
+
+      def self.finalizer(context, name)
+        proc {
+          begin
+            context.eval("delete #{name}")
+          rescue ThreadError # rubocop:disable Lint/SuppressedException
+          end
+        }
+      end
+    end
+  end
+end

data/lib/handlebars/engine/init.js

@@ -0,0 +1,43 @@
+var {
+  compile,
+  precompile,
+  registerPartial,
+  unregisterPartial,
+  registerHelper,
+  unregisterHelper,
+  VERSION,
+} = Handlebars;
+
+var template = (spec) => {
+  eval(`spec = ${spec}`);
+  return Handlebars.template(spec);
+};
+
+var registerPartial = Handlebars.registerPartial.bind(Handlebars);
+var unregisterPartial = Handlebars.unregisterPartial.bind(Handlebars);
+
+var registerHelper = (...args) => {
+  const fn = args[args.length - 1];
+  function wrapper(...args) {
+    args.unshift(this);
+    return fn(...args);
+  }
+  args[args.length - 1] = wrapper;
+  return Handlebars.registerHelper(...args);
+};
+
+var unregisterHelper = Handlebars.unregisterHelper.bind(Handlebars);
+
+var partialMissing;
+
+const partialsHandler = {
+  get(partials, name) {
+    const partial = partials[name] ?? partialMissing?.(name);
+    if (partial) {
+      partials[name] = partial;
+    }
+    return partial;
+  },
+};
+
+Handlebars.partials = new Proxy(Handlebars.partials, partialsHandler);

data/lib/handlebars/engine/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Handlebars
-  module Engine
-    VERSION = "0.1.0"
+  class Engine
+    VERSION = "0.3.2"
   end
 end

data/lib/handlebars/engine.rb

@@ -1,9 +1,236 @@
 # frozen_string_literal: true
 
+require "handlebars/source"
+require "json"
+require "mini_racer"
+require "securerandom"
+require_relative "engine/function"
 require_relative "engine/version"
 
 module Handlebars
   # The Handlebars engine.
-  module Engine
+  #
+  # 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.
+    # @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
+
+    ###################################
+    # Compilation
+    ###################################
+
+    # Compiles a template so it can be executed immediately.
+    #
+    # @param template [String] the template string to compile
+    # @param options [Hash] the options
+    # @return [Proc] the template function to call
+    # @see https://handlebarsjs.com/api-reference/compilation.html#handlebars-compile-template-options
+    def compile(*args)
+      call(__method__, args, assign: true)
+    end
+
+    # Precompiles a given template so it can be executed without compilation.
+    #
+    # @param template [String] the template string to precompiled
+    # @param options [Hash] the options
+    # @return [String] the precompiled template spec
+    # @see https://handlebarsjs.com/api-reference/compilation.html#handlebars-precompile-template-options
+    def precompile(*args)
+      call(__method__, args)
+    end
+
+    # Sets up a template that was precompiled with `precompile`.
+    #
+    # @param spec [String] the precompiled template spec
+    # @return [Proc] the template function to call
+    # @see #precompile
+    # @see https://handlebarsjs.com/api-reference/compilation.html#handlebars-template-templatespec
+    def template(*args)
+      call(__method__, args, assign: true)
+    end
+
+    ###################################
+    # Runtime
+    ###################################
+
+    # 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 = 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.
+    #
+    # @param name [String, Symbol] the name of the helper
+    # @see https://handlebarsjs.com/api-reference/runtime.html#handlebars-unregisterhelper-name
+    def unregister_helper(name)
+      call(:unregisterHelper, [name])
+    end
+
+    # Registers partials accessible by any template in the environment.
+    #
+    # @param name [String, Symbol] the name of the partial
+    # @param partial [String] the partial template
+    # @see https://handlebarsjs.com/api-reference/runtime.html#handlebars-registerpartial-name-partial
+    def register_partial(name = nil, partial = nil, **partials)
+      partials[name] = partial if name
+      call(:registerPartial, [partials])
+    end
+
+    # Unregisters a previously registered partial.
+    #
+    # @param name [String, Symbol] the name of the partial
+    # @see https://handlebarsjs.com/api-reference/runtime.html#handlebars-unregisterpartial-name
+    def unregister_partial(name)
+      call(:unregisterPartial, [name])
+    end
+
+    ###################################
+    # Hooks
+    ###################################
+
+    # Registers the hook called when a mustache or a block-statement is missing.
+    #
+    # @param type [Symbol] the type of hook to register (`:basic` or `:block`)
+    # @yieldparam arguments [Object] the arguments (optional)
+    # @yieldparam options [Hash] the options hash (optional)
+    # @see https://handlebarsjs.com/guide/hooks.html#helpermissing
+    def register_helper_missing(type = :basic, &block)
+      name = helper_missing_name(type)
+      register_helper(name, &block)
+    end
+
+    # Unregisters the previously registered hook.
+    #
+    # @param type [Symbol] the type of hook to register (`:basic` or `:block`)
+    # @see https://handlebarsjs.com/guide/hooks.html#helpermissing
+    def unregister_helper_missing(type = :basic)
+      name = helper_missing_name(type)
+      unregister_helper(name)
+    end
+
+    # Registers the hook called when a partial is missing.
+    #
+    # Note: This is not a part of the offical Handlebars API. It is provided for
+    # convenience.
+    #
+    # @yieldparam name [String] the name of the undefined partial
+    def register_partial_missing(&block)
+      attach(:partialMissing, &block)
+    end
+
+    # Unregisters the previously registered hook.
+    def unregister_partial_missing
+      evaluate("delete partialMissing")
+    end
+
+    ###################################
+    # Miscellaneous
+    ###################################
+
+    # Returns the version of Handlebars.
+    #
+    # @return [String] the Handlebars version.
+    def version
+      evaluate("VERSION")
+    end
+
+    ###################################
+    # Private
+    ###################################
+
+    private
+
+    def attach(name, &block)
+      init!
+      @context.attach(name.to_s, block)
+    end
+
+    def call(name, args, assign: false, eval: false)
+      init!
+      name = name.to_s
+
+      if assign || eval
+        call_via_eval(name, args, assign: assign)
+      else
+        @context.call(name, *args)
+      end
+    end
+
+    def call_via_eval(name, args, assign: false)
+      args = js_args(args)
+
+      var = assign ? "v#{SecureRandom.alphanumeric}" : nil
+
+      code = "#{name}(#{args.join(", ")})"
+      code = "#{var} = #{code}" if var
+
+      result = evaluate(code)
+
+      if var && result.is_a?(MiniRacer::JavaScriptFunction)
+        result = Function.new(@context, var)
+      end
+
+      result
+    end
+
+    def evaluate(code)
+      @context.eval(code)
+    end
+
+    def helper_missing_name(type)
+      case type
+      when :basic
+        :helperMissing
+      when :block
+        :blockHelperMissing
+      end
+    end
+
+    def init!
+      return if @init
+
+      @context = MiniRacer::Context.new
+      @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| JSON.generate(arg) }
+    end
   end
 end

data/lib/handlebars-engine.rb

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

metadata

@@ -1,18 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: handlebars-engine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Zach Gianos
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-01-13 00:00:00.000000000 Z
-dependencies: []
-description: "    A simple interface to Handlebars.js for Ruby.\n"
+date: 2022-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: handlebars-source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mini_racer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+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@gmail.com
+- zach.gianos+git@gmail.com
 executables:
 - handlebars
 extensions: []
@@ -22,17 +59,20 @@ 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
 licenses:
 - MIT
 metadata:
   changelog_uri: https://github.com/gi/handlebars-ruby/CHANGELOG.md
+  github_repo: https://github.com/gi/handlebars-ruby
   homepage_uri: https://github.com/gi/handlebars-ruby
-  rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/gi/handlebars-ruby
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -47,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: []