minibars 0.0.1.alpha → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c72e077ae845e99620f99cace6436fbee1531c1de7bf61e3c57bd619b3a562
-  data.tar.gz: 573d6b494c9b427fd3c79b9408faa9bf8ac5426284ab8abf11a2a94ae1ba6d66
+  metadata.gz: 29dfecb36dae3be442ea406501052e3df52fa71578647ad1d1e74410e49ddc92
+  data.tar.gz: 767861cecb3604b98b8ee615148f784eb9478a13d35bb1bad531eea9a4a631c4
 SHA512:
-  metadata.gz: 20e5a241a27a1214634f9a126cdb785c9b6defe7ee104eaf70705c4eee67aab2d6944b849eded5db5bff2b5f009e3120e95061601fe855b1efa70797cfb95885
-  data.tar.gz: 52b47d651c260ae2e16ef8e2b3498a91d2e4929feeec4510e5f22540818adf029355351b52e904c85322d58b194f3d4463414a200cc2088096fbd27740fa627b
+  metadata.gz: aa966dac5605965607974dcaf968f762e5b6b0644d3b67fcfd001ba8586503b164d2a593f11051c1226c2af85f2d887a762bf5335bbdf9a2688884ad6147f289
+  data.tar.gz: 1c2f503e4c77cfc66e01562b61138fa3d7336dca719ade8282deff74d80c292c85caaab4424befeaafd4282584e4457ba4ff4fcbecaadabd8eed343929d96e6f

data/README.md

@@ -0,0 +1,81 @@
+![Tests](https://github.com/delonnewman/minibars/workflows/tests/badge.svg)
+
+# Minibars
+
+A (mostly) drop-in replacement for [Handlebars.rb][3] based on [MiniRacer][1] rather than [therubyracer][2].
+
+An appropriately revised quote from the [Handlebars.rb][3] README:
+
+> This uses ~~therubyracer~~[MiniRacer][1] to bind to the _actual_ JavaScript implementation of [Handlebars.js](https://github.com/handlebars-lang/handlebars.js) so that you can use it from ruby.
+
+# Why?
+
+Minibars is a stripped down implementation of [Handlerbars.rb][3] using [MiniRacer][1]. It eschews capabilities that require two-way binding with the JS runtime, making it a good choice for those with simple Handlebars templates who need an upgrade path for their ARM64 architecture.
+
+# Usage
+
+## Simple Stuff
+
+```ruby
+require 'minibars'
+minibars = Minibars::Context.new
+template = minibars.compile("{{say}} {{what}}")
+template.call(say: "Hey", what: "Yuh!") #=> "Hey Yuh!"
+```
+
+## Functions as Properties
+
+This feature differs from [Handlebars.rb][3] since Minibars templates won't pass a `this` argument to property functions.
+
+```ruby
+template.call(say: "Hey ", what: ->{ ("yo" * 2) + "!"}) #=> "Hey yoyo!"
+```
+
+## Helpers
+
+JavaScript helpers can be loaded as individual files or as a glob
+
+```ruby
+minibars.load_helpers("#{__dir__}/javascripts/helpers/**/*.js")
+minibars.load_helper("#{__dir__}/javascripts/helpers/admin.js")
+```
+
+## Partials
+
+You can directly register partials
+
+```ruby
+minibars.register_partial("whoami", "I am {{who}}")
+minibars.compile("{{>whoami}}").call(who: 'Legend') #=> I am Legend
+```
+
+## SafeStrings
+
+By default, handlebars will escape strings that are returned by your block helpers. To mark a string as safe:
+
+```ruby
+template = minibars.compile("{{safe}}")
+template.call(safe: Minibars::SafeString.new("<pre>Totally Safe!<pre>"))
+```
+
+## Compatibility
+
+`Handlebars::Context` aliases `Minibars::Context` and `Handlebars::SafeString` aliases `Minibars::SafeString` unless they are already defined.
+
+```ruby
+require 'handlebars` # Applies the compatibility layer found in lib/handlebars.rb and loads minibars
+```
+
+## Limitations
+
+- No Ruby helpers
+
+## Security
+
+In general, you should not trust user-provided templates: a template can call any method (with no arguments) or access any property on any object in the `Minibars::Context`.
+
+If you'd like to render user-provided templates, you'd want to make sure you do so in a sanitized Context, e.g. no filesystem access, read-only or no database access, etc.
+
+[1]: https://github.com/rubyjs/mini_racer
+[2]: https://github.com/rubyjs/therubyracer
+[3]: https://github.com/cowboyd/handlebars.rb

data/Rakefile

@@ -4,14 +4,8 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-APP_RAKEFILE = File.expand_path("../spec/internal/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
-
-load 'rails/tasks/statistics.rake'
-
 Bundler::GemHelper.install_tasks
 
-
 # Add Rspec tasks
 require 'rspec/core/rake_task'
 

data/lib/handlebars.rb

@@ -0,0 +1,8 @@
+# Handlebars Compatibility
+# Allows Minibars to be a drop in replacement for Handlebars (minus features that are not supported)
+require 'minibars'
+
+module Handlebars
+  Context = Minibars::Context unless defined? Context
+  SafeString = Minibars::SafeString unless defined? SafeString
+end

data/lib/minibars/context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Minibars
+  # A context for compiling handlebars templates, registering partials, and loading helpers.
+  #
+  # @example
+  #   minibars = Minibars::Context.new
+  #   template = minibars.compile("{{say}} {{what}}")
+  #   template.call(:say => "Hey", :what => "Yuh!") #=> "Hey Yuh!"
+  class Context
+    # Instantiate a new Minibars context, optionally, specify a handlebars file to load.
+    #
+    # @param handlebars_file [String]
+    def initialize(handlebars_file: Handlebars::Source.bundled_path)
+      @js = MiniRacer::Context.new.tap do |js|
+        js.load(handlebars_file)
+      end
+    end
+
+    # Compile the given template string and return a template object.
+    #
+    # @param template [String]
+    # @raise [Minibars::Error] if the template is not a string
+    #
+    # @return [Minibars::Template]
+    def compile(template)
+      Template.compile(self, @js, template)
+    end
+
+    # Register the partial with the given name.
+    #
+    # @example
+    #   minibars.register_partial("whoami", "I am {{who}}")
+    #   minibars.compile("{{>whoami}}").call(:who => 'Legend') #=> I am Legend
+    #
+    # @param name [String] partial name
+    # @param partial [String] partial content
+    #
+    # @raise [Minibars::Error] if the name or the partial content are not strings
+    # @return [Minibars::Context]
+    def register_partial(name, partial)
+      raise Error, 'Partial name should be a string'    unless name.is_a?(String)
+      raise Error, 'Partial content should be a string' unless partial.is_a?(String)
+
+      @js.eval("Handlebars.registerPartial(#{name.to_json}, #{partial.to_json})")
+
+      self
+    end
+
+    # Load JavaScript handlebars helpers from the directory specified by the given glob pattern.
+    #
+    # @example
+    #   minibars.load_helpers("#{__dir__}/javascripts/helpers/**/*.js")
+    #
+    # @see https://rubyapi.org/3.1/o/dir#method-c-glob Dir.glob
+    #
+    # @param helpers_pattern [String]
+    #
+    # @return [Minibars::Context]
+    def load_helpers(helpers_pattern)
+      Dir[helpers_pattern].each do |path|
+        load_helper(path)
+      end
+
+      self
+    end
+
+    # Load a handlebars helper from a single JavaScript file.
+    #
+    # @example
+    #   minibars.load_helper("#{__dir__}/javascripts/helpers/admin.js")
+    #
+    # @param path [String]
+    #
+    # @return [Minibars::Context]
+    def load_helper(path)
+      @js.load(path)
+
+      self
+    end
+  end
+end

data/lib/minibars/error.rb

@@ -0,0 +1,3 @@
+module Minibars
+  class Error < RuntimeError; end
+end

data/lib/minibars/safe_string.rb

@@ -0,0 +1,13 @@
+module Minibars
+  # Mark a string as safe to avoid it being escaped by Handlebars
+  class SafeString
+    def initialize(string)
+      @string = string
+    end
+
+    # @api private
+    def to_json(*)
+      "new Handlebars.SafeString(#{@string.to_json})"
+    end
+  end
+end

data/lib/minibars/template.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Minibars
+  # A compiled handlebars template.
+  class Template
+    attr_reader :content, :name
+
+    # @api private
+    def self.compile(context, js, content)
+      new(context, js, content).compile
+    end
+
+    # @api private
+    def initialize(context, js, content)
+      @content = content
+      @context = context
+      @js      = js
+      @name    = "Minibars_Template_#{hash_combine(@context.hash, @content.hash).abs}"
+    end
+
+    # @api private
+    def compile
+      raise Error, 'Template content should be a string' unless content.is_a?(String)
+
+      @js.eval("#{name} = Handlebars.compile(#{content.to_json})")
+
+      self
+    end
+
+    # Render the template with the given parameters.
+    #
+    # @param params [Hash]
+    #
+    # @return [String]
+    def call(params = EMPTY_HASH)
+      @js.eval("#{name}(#{JSON.generate process_params(params)})")
+    end
+
+    private
+
+    def process_params(params)
+      return params if params.empty?
+
+      params.transform_values do |value|
+        if value.respond_to?(:call)
+          value.call
+        else
+          value
+        end
+      end
+    end
+
+    def hash_combine(seed, hash)
+      # a la boost, a la clojure
+      seed ^= hash + 0x9e3779b9 + (seed << 6) + (seed >> 2)
+      seed
+    end
+  end
+end

data/lib/minibars/version.rb

@@ -1,3 +1,3 @@
 module Minibars
-  VERSION = "0.0.1.alpha"
+  VERSION = "0.2.0"
 end

data/lib/minibars.rb

@@ -1,4 +1,17 @@
-require 'rails/all'
+# frozen_string_literal: true
 
+require 'json'
+require 'mini_racer'
+require 'handlebars/source'
+
+require 'minibars/error'
+require 'minibars/context'
+require 'minibars/template'
+
+require_relative 'minibars/safe_string'
+
+# Make use of Handlebars templates from Ruby using mini_racer
 module Minibars
+  EMPTY_HASH = {}.freeze
+  private_constant :EMPTY_HASH
 end

metadata

@@ -1,59 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: minibars
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicholas Jakobsen
+- Delon Newman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-29 00:00:00.000000000 Z
+date: 2024-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: mini_racer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: 0.6.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: 0.6.4
 - !ruby/object:Gem::Dependency
-  name: combustion
+  name: handlebars-source
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: mysql2
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.4.10
-  type: :development
+        version: '0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -66,25 +53,36 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
-description: Minibars is a stripped down implmentation of Handlerbars using MiniRacer.
+description: Minibars is a stripped down implementation of Handlerbars using MiniRacer.
   It eschews capabilities that require two-way binding with the JS runtime, making
-  it a good upgrade path for those with simple Handlebars templates who need an upgrade
-  path for their Arm64 architecture.
+  it a good choice for those with simple Handlebars templates who need an upgrade
+  path for their ARM64 architecture.
 email:
 - nicholas@combinaut.com
+- contact@delonnewman.name
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.md
 - Rakefile
+- lib/handlebars.rb
 - lib/minibars.rb
+- lib/minibars/context.rb
+- lib/minibars/error.rb
+- lib/minibars/safe_string.rb
+- lib/minibars/template.rb
 - lib/minibars/version.rb
-- lib/tasks/minibars_tasks.rake
 homepage: https://github.com/combinaut/minibars
 licenses:
 - MIT
-metadata: {}
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/combinaut/minibars
+  source_code_uri: https://github.com/combinaut/minibars
+  changelog_uri: https://github.com/combinaut/minibars/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/minibars
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -96,12 +94,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.5.13
 signing_key:
 specification_version: 4
-summary: Minibars is a stripped down implmentation of Handlerbars using MiniRacer.
+summary: Minibars is a stripped down implementation of Handlerbars using MiniRacer.
 test_files: []

data/lib/tasks/minibars_tasks.rake

@@ -1,2 +0,0 @@
-namespace :minibars do
-end