htx 0.0.9 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 395620b3af20b4da17e4413632418481ee28d6d0fe6b46427af240475087efce
-  data.tar.gz: bc15b61294daaf218b3a3d5a106de7c9279a7d9e8cb7ebd01002fcd618491b1f
+  metadata.gz: bbd968d3152b9ef4c7813f1e08139a4dc386ae99f8822758a0eb2574eb8beab5
+  data.tar.gz: e2fa1f7035a09e3518be5e3fe5f8c053fd4d7d8022f6f3d121e8caecea180d6a
 SHA512:
-  metadata.gz: 83805b10f30d1846a187b458579a0748339a3956a4123226b7b9ebdb6dcff6cae3dbcd94913c1bbab2c91186ef3f46642f30a4ed9c3f30b072b3efe2f2ceb1ca
-  data.tar.gz: 26e48419a9a719f1b8b582ef9e525ffcc37affdcb279f0cba95c6fe4cd2108cc6ec66e9ba4d3216a0ef02aad506d56c4743b059916ba78409f0dc672a760a1fc
+  metadata.gz: 3c15b1d31a60c7447137bd599bb2e7e767896d4f8ebef93878efb5981138beddd7a712744a974ea4150edd9b511593acf1d8ca0cb6754ae04f17ffbc85ce9ed1
+  data.tar.gz: adab39540cfe4261e26697a0a6af1081a620ab55305b38abcae5e446a919dfd5a5ac96cc01b5fa3cdd28bbbd3e6755c1c00a98f492530333ef102da43b4c5381

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2019-2022 Nate Pickens
+Copyright 2019-2023 Nate Pickens
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without

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)).
 
-# window['/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.0.9
+0.1.1

data/lib/htx/template.rb

@@ -17,7 +17,6 @@ module HTX
       'svg' => 'http://www.w3.org/2000/svg',
     }.freeze
 
-    INDENT_VALID = /^( +|\t+)$/.freeze
     INDENT_GUESS = /^( +|\t+)(?=\S)/.freeze
     INDENT_REGEX = /\n(?=[^\n])/.freeze
 
@@ -32,17 +31,14 @@ module HTX
     NON_WHITESPACE = /\S/.freeze
 
     ##
-    # Returns false. In the near future when support for the <:> tag has been dropped (in favor of
-    # <htx-content>), will return true if Nokogiri's HTML5 parser is available. To use it now, monkey patch
-    # this method to return true.
+    # Returns true if Nokogiri's HTML5 parser is available.
     #
     def self.html5_parser?
-      false # !!defined?(Nokogiri::HTML5)
+      defined?(Nokogiri::HTML5)
     end
 
     ##
-    # Returns Nokogiri's HTML5 parser if available and enabled, and Nokogiri's regular HTML parser
-    # otherwise.
+    # Returns Nokogiri's HTML5 parser if available or Nokogiri's default HTML (4) parser otherwise.
     #
     def self.nokogiri_parser
       html5_parser? ? Nokogiri::HTML5 : Nokogiri::HTML
@@ -62,24 +58,15 @@ module HTX
     ##
     # Compiles the HTX template.
     #
-    # * +assign_to+ - JavaScript object to assign the template function to (default: +window+).
-    # * +indent+ - DEPRECATED. Indentation amount (number) or string (must be only spaces or tabs but not
-    #   both) to use for indentation of compiled output (default: indentation of first indented line of
-    #   uncompiled template).
-    #
-    def compile(assign_to: nil, indent: (indent_omitted = true; nil))
-      @assign_to = assign_to || 'window'
-      @indent =
-        if indent.kind_of?(Numeric)
-          ' ' * indent
-        elsif indent && !indent.match?(INDENT_VALID)
-          raise("Invalid indent value #{indent.inspect}: only spaces and tabs (but not both) are allowed")
-        else
-          indent || @content[INDENT_GUESS] || INDENT_DEFAULT
-        end
-
-      warn('The indent: option for HTX template compilation is deprecated.') unless indent_omitted
-
+    # * +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
       @whitespace_buff = nil
@@ -158,14 +145,33 @@ module HTX
     # * +node+ - Nokogiri node to process.
     #
     def process_fragment_node(node)
-      append("#{@assign_to}['#{@name}'] = function(htx) {")
-      @whitespace_buff = "\n"
+      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 unless @as_module
 
       node.children.each do |child|
         process(child)
       end
 
-      append("\n}\n",)
+      append("\n\n#{@indent}return $renderer.rootNode")
+
+      @indent = @as_module ? '' : @base_indent
+
+      append(
+        <<~JS
+
+          #{@indent}}
+
+          #{@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
+      )
+
       flush
     end
 
@@ -179,15 +185,10 @@ module HTX
       children = node.children
       childless = children.empty? || (children.size == 1 && self.class.formatting_node?(children.first))
       dynamic_key = self.class.attribute_value(node.attr(DYNAMIC_KEY_ATTR))
-      attributes = self.class.process_attributes(node)
+      attributes = self.class.process_attributes(node, xmlns: xmlns)
       xmlns ||= !!self.class.namespace(node)
 
       if self.class.htx_content_node?(node)
-        if node.name != CONTENT_TAG
-          warn("#{@name}:#{node.line}: The <#{node.name}> tag has been deprecated. Use <#{CONTENT_TAG}> "\
-            "for identical functionality.")
-        end
-
         if attributes.size > 0
           raise(MalformedTemplateError.new("<#{node.name}> tags may not have attributes other than "\
             "#{DYNAMIC_KEY_ATTR}", @name, node))
@@ -269,7 +270,7 @@ module HTX
         close_count = @close_count
         @close_count = 0
 
-        append("htx.close(#{close_count unless close_count == 1})")
+        append("$renderer.close(#{close_count unless close_count == 1})")
       end
 
       if @whitespace_buff
@@ -289,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?
@@ -300,7 +301,7 @@ module HTX
       args << 0 unless args.last.kind_of?(Integer)
       args[-1] |= (@static_key += 1) << FLAG_BITS
 
-      append("htx.node(#{args.join(', ')})")
+      append("$renderer.node(#{args.join(', ')})")
     end
 
     ##
@@ -336,7 +337,7 @@ module HTX
     # * +node+ - Nokogiri node to check.
     #
     def self.htx_content_node?(node)
-      node && (node.name == CONTENT_TAG || node.name == 'htx-text' || node.name == ':')
+      node&.name == CONTENT_TAG
     end
 
     ##
@@ -344,10 +345,10 @@ module HTX
     #
     # * +node+ - Nokogiri node to process the attributes of.
     #
-    def self.process_attributes(node)
+    def self.process_attributes(node, xmlns:)
       attributes = []
 
-      if !node.attribute('xmlns') && (xmlns = namespace(node))
+      if !xmlns && !node.attribute('xmlns') && (xmlns = namespace(node))
         attributes.push(
           attribute_name('xmlns'),
           attribute_value(xmlns)
@@ -402,15 +403,10 @@ module HTX
       text ? TextParser.new(text, statement_allowed: false).parse : nil
     end
 
-    # The Nokogiri HTML parser downcases all tag and attribute names, but SVG tags and attributes are case
-    # sensitive and often mix cased. These maps are used to restore the correct case of such tags and
-    # attributes.
-    #
-    # Note: Nokogiri's newer HTML5 parser resulting from the Nokogumbo merge fixes this issue, but it is
-    # currently not available for JRuby. It also does not parse <:> as a tag, which is why it's been
-    # deprecated in favor of <htx-content>. Once support for <:> has been completely removed, the HTML5
-    # parser will be used for regular Ruby and this tag and attribute mapping hack reserved for JRuby (and
-    # any other potential environments where the HTML5 parser is not available).
+    # The Nokogiri::HTML5 parser is used whenever possible, which correctly handles mix-cased SVG tag and
+    # attribute names. But when falling back to the Nokogiri::HTML parser (e.g. in JRuby environments where
+    # Nokogiri::HTML5 is not available), all tag and attribute names get downcased. These maps are used to
+    # restore the correct case.
 
     # Source: https://developer.mozilla.org/en-US/docs/Web/SVG/Element
     TAG_MAP = %w[

data/lib/htx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTX
-  VERSION = '0.0.9'
+  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.
   #
@@ -21,18 +27,4 @@ module HTX
   def self.compile(name, content, options = EMPTY_HASH)
     Template.new(name, content).compile(**options)
   end
-
-  ##
-  # DEPRECATED. Use HTX::Template.new instead. HTX was formerly a class that would be instantiated for
-  # compilation. This method allows HTX.new calls to continue working (but support will be removed in the
-  # near future).
-  #
-  # * +name+ - Template name. Conventionally the path of the template file.
-  # * +content+ - Template content.
-  #
-  def self.new(name, content)
-    warn('HTX.new is deprecated. Please use HTX::Template.new instead.')
-
-    Template.new(name, content)
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: htx
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.1
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-31 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.2.32
+rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
 summary: A Ruby compiler for HTX templates.