htx 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83c2b45f8852d11b5faa35989c0552a4135c3270d20aaaa2af8d170e696ad840
-  data.tar.gz: dcbbb3aac2484f55b445a029c9916e282dc75b93197f630b40227110aba02c28
+  metadata.gz: bbd968d3152b9ef4c7813f1e08139a4dc386ae99f8822758a0eb2574eb8beab5
+  data.tar.gz: e2fa1f7035a09e3518be5e3fe5f8c053fd4d7d8022f6f3d121e8caecea180d6a
 SHA512:
-  metadata.gz: 8a26b13b0f0cdddf7d9338f1876c23e59adaef4abd2d706cae4a984bd74ca207465e93d6c1d1f0877adf5f27999ddbfd59d93c703ffe098ea7cfc239bc8f391d
-  data.tar.gz: e6ace0fd8c2289e1b2062e6f9e976e017b3e639cfd0eb0777bf5e4bd9ded53d8774c843cfcb1cc55a1c491d0fe6d4f81e337455897ec471bebc0d333db202ba5
+  metadata.gz: 3c15b1d31a60c7447137bd599bb2e7e767896d4f8ebef93878efb5981138beddd7a712744a974ea4150edd9b511593acf1d8ca0cb6754ae04f17ffbc85ce9ed1
+  data.tar.gz: adab39540cfe4261e26697a0a6af1081a620ab55305b38abcae5e446a919dfd5a5ac96cc01b5fa3cdd28bbbd3e6755c1c00a98f492530333ef102da43b4c5381

data/README.md

@@ -1,8 +1,7 @@
 # HTX Ruby Compiler
 
 HTX templates are compiled to JavaScript before being used. This library provides a Ruby implementation of
-the compiler. For more information on HTX, see
-[https://github.com/npickens/htx](https://github.com/npickens/htx).
+the compiler. For more information on HTX, see the main [README](https://github.com/npickens/htx).
 
 ## Installation
 
@@ -20,24 +19,39 @@ gem install htx
 
 ## Usage
 
-To compile an HTX template, pass a name (conventionally the path of the template file) and template content
-as strings to the `HTX.compile` method (all other arguments are optional):
+HTX templates can be compiled to either a JavaScript module format or an IIFE assigned to a property on
+either `globalThis` or a custom object. To compile as a module:
 
 ```ruby
 path = '/components/crew.htx'
-template = File.read(File.join('some/asset/dir', path))
+content = File.read("/assets#{path}")
+
+HTX.compile(path, content, as_module: true, import_path: 'vendor/htx.js')
+# => "import * as HTX from 'vendor/htx.js'
+#
+#     ...
+#
+#     export function Template { ... }"
+#
+```
 
-HTX.compile(path, template)
+Note that with the module format the name of the template does not appear anywhere in its compiled form, but
+is still used/useful for tracking down errors when compilation is handled by an overall asset management
+system (such as [Darkroom](https://github.com/npickens/darkroom)).
 
-# globalThis['/components/crew.htx'] = function(htx) {
-#   // ...
-# }
+To compile to an IIFE assigned to a custom object:
 
-HTX.compile(path, template, assign_to: 'myTemplates')
+```ruby
+HTX.compile(path, content, as_module: false, assign_to: 'myTemplates')
+# => "myTemplates['/components/crew.htx'] = ..."
+```
 
-# myTemplates['/components/crew.htx'] = function(htx) {
-#   // ...
-# }
+Options can be configured globally so they don't have to be passed to `HTX.compile` every time:
+
+```ruby
+HTX.as_module = true              # Default: false
+HTX.import_path = 'vendor/htx.js' # Default: "/htx/htx.js"
+HTX.assign_to = 'myTemplates'     # Default: "globalThis"
 ```
 
 ## Contributing

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/htx/template.rb

@@ -58,10 +58,14 @@ module HTX
     ##
     # Compiles the HTX template.
     #
-    # * +assign_to+ - JavaScript object to assign the template function to (default: +globalThis+).
-    #
-    def compile(assign_to: nil)
-      @assign_to = assign_to || 'globalThis'
+    # * +as_module+ - Boolean indicating whether or not to compile as a JavaScript module.
+    # * +import_path+ - Path to HTX JavaScript library for module import statement.
+    # * +assign_to+ - JavaScript object to assign the template function to if module not being used.
+    #
+    def compile(as_module: nil, import_path: nil, assign_to: nil)
+      @as_module = as_module.nil? ? HTX.as_module : as_module
+      @import_path = import_path || HTX.import_path
+      @assign_to = assign_to || HTX.assign_to
       @base_indent = @indent = @content[INDENT_GUESS] || INDENT_DEFAULT
       @static_key = 0
       @close_count = 0
@@ -141,32 +145,30 @@ module HTX
     # * +node+ - Nokogiri node to process.
     #
     def process_fragment_node(node)
-      append(
-        <<~JS
-          #{@assign_to}['#{@name}'] = ((HTX) => {
-          #{@indent}function render($rndr) {
-        JS
-      )
+      append("#{
+        @as_module ? "import * as HTX from '#{@import_path}'\n\n"
+                   : "#{@assign_to}['#{@name}'] = ((HTX) => {\n#{@indent}"
+      }function render($renderer) {\n")
 
-      @indent = @base_indent * 2
+      @indent = @base_indent * 2 unless @as_module
 
       node.children.each do |child|
         process(child)
       end
 
-      append("\n\n#{@indent}return $rndr.rootNode")
+      append("\n\n#{@indent}return $renderer.rootNode")
 
-      @indent = @base_indent
+      @indent = @as_module ? '' : @base_indent
 
       append(
-        +<<~JS
+        <<~JS
 
           #{@indent}}
 
-          #{@indent}return function Template(context) {
-          #{@indent * 2}this.render = render.bind(context, new HTX.Renderer)
-          #{@indent}}
-          })(globalThis.HTX ||= {});
+          #{@indent}#{@as_module ? 'export' : 'return'} function Template(context) {
+          #{@indent}#{@base_indent}this.render = render.bind(context, new HTX.Renderer)
+          #{@indent}}#{
+          "\n})(globalThis.HTX ||= {});" unless @as_module}
         JS
       )
 
@@ -268,7 +270,7 @@ module HTX
         close_count = @close_count
         @close_count = 0
 
-        append("$rndr.close(#{close_count unless close_count == 1})")
+        append("$renderer.close(#{close_count unless close_count == 1})")
       end
 
       if @whitespace_buff
@@ -288,9 +290,9 @@ module HTX
     end
 
     ##
-    # Appends an +htx.node+ call to the compiled template function string.
+    # Appends an +$renderer.node+ call to the compiled template function string.
     #
-    # * +args+ - Arguments to use for the +htx.node+ call (any +nil+ ones are removed).
+    # * +args+ - Arguments to use for the +$renderer.node+ call (any +nil+ ones are removed).
     #
     def append_htx_node(*args)
       return if args.first.nil?
@@ -299,7 +301,7 @@ module HTX
       args << 0 unless args.last.kind_of?(Integer)
       args[-1] |= (@static_key += 1) << FLAG_BITS
 
-      append("$rndr.node(#{args.join(', ')})")
+      append("$renderer.node(#{args.join(', ')})")
     end
 
     ##

data/lib/htx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTX
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/htx.rb

@@ -11,6 +11,12 @@ require('htx/version')
 module HTX
   EMPTY_HASH = {}.freeze
 
+  @as_module = false
+  @import_path = '/htx/htx.js'
+  @assign_to = 'globalThis'
+
+  class << self; attr_accessor(:as_module, :import_path, :assign_to); end
+
   ##
   # Convenience method to create a new Template instance and compile it.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: htx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
 summary: A Ruby compiler for HTX templates.