lib: initial implementation (#1)

Author: gi

.github/workflows/ci.yml

@@ -53,6 +53,7 @@ jobs:
           - ruby-2.6
           - ruby-2.7
           - ruby-3.0
+          - ruby-3.1
           # - jruby
           # - truffleruby
     runs-on: ${{ matrix.os }}

.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

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

@@ -35,4 +35,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