handlebars-engine 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5687452a43187e2eb02f0f14b8cdfbb9326f7a45324aff57036ca6f40f1e3f1b
-  data.tar.gz: f6f11a588f3db269fd34beb13e5c74ed0c8d15e8533e6dca1f99d6fa6737ae8f
+  metadata.gz: 0b6bc490b95cc268a0cc7ee638660caecbfe9d978a13335b8c3588f89e16c3db
+  data.tar.gz: 014eb30c05c4edba8b9f9a340e3539a8542edabd94954efa189b2611456e10d8
 SHA512:
-  metadata.gz: 19f3131b68bb2b4062e30c730becb77efdf9d62b057863d2b2e2c97369ddab4216c1d08eb370070b1f9e5950ff75015414a72c6b04d8c0df277954ee2beedc9a
-  data.tar.gz: b28fbad17ce848de5b10a6a023a6ee227c0c2175d996587338f726f320b9e9f75995b3927662005c35d3460b8c5fc2d9f27f40c962e6b4fd628f8355035b457d
+  metadata.gz: a092e8fdae258e997d6afb3505b20a67898caf7d08bfd37efee1a50f663b0e084648902b6d396fe392acb46a8e5587deee277e2ec750f31ce103ad8dd42d1d6b
+  data.tar.gz: 99c271de356730e76c660fb806d8dd619edb0f522951a5e822f6460e0e415c02e20311aab2e5be55e89f9b2ffd161e87b75784726512df26d5c59d002ec06f9a

data/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

data/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
 

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.2.0"
   end
 end

data/lib/handlebars/engine.rb

@@ -1,9 +1,224 @@
 # frozen_string_literal: true
 
+require "handlebars/source"
+require "json"
+require "mini_racer"
+require "securerandom"
 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
+    # Creates a new instance.
+    #
+    # @param lazy [true, false] immediately loads and initializes the JavaScript
+    #   environment.
+    def initialize(lazy: false)
+      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.
+    #
+    # @param name [String, Symbol] the name of the helper
+    # @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)
+    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 = ->(*a) { @context.call(var, *a) }
+        finalizer = ->(*) { evaluate("delete #{var}") }
+        ObjectSpace.define_finalizer(result, finalizer)
+      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(::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
+      }
+    end
   end
 end

metadata

@@ -1,18 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: handlebars-engine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Zach Gianos
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-13 00:00:00.000000000 Z
-dependencies: []
+date: 2022-01-27 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: "    A simple interface to Handlebars.js for Ruby.\n"
 email:
-- zach.gianos@gmail.com
+- zach.gianos+git@gmail.com
 executables:
 - handlebars
 extensions: []
@@ -23,14 +51,15 @@ files:
 - README.md
 - exe/handlebars
 - lib/handlebars/engine.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:
 rdoc_options: []