htx 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83c2b45f8852d11b5faa35989c0552a4135c3270d20aaaa2af8d170e696ad840
-  data.tar.gz: dcbbb3aac2484f55b445a029c9916e282dc75b93197f630b40227110aba02c28
+  metadata.gz: d869f62a146bed898334d085ce1dc507d214950d166454b65e502058bc68e6b6
+  data.tar.gz: fd81c8b3b82f2bd95e85899f14ee35f881f11a8b0f8b07b38af1f5b0ee599a87
 SHA512:
-  metadata.gz: 8a26b13b0f0cdddf7d9338f1876c23e59adaef4abd2d706cae4a984bd74ca207465e93d6c1d1f0877adf5f27999ddbfd59d93c703ffe098ea7cfc239bc8f391d
-  data.tar.gz: e6ace0fd8c2289e1b2062e6f9e976e017b3e639cfd0eb0777bf5e4bd9ded53d8774c843cfcb1cc55a1c491d0fe6d4f81e337455897ec471bebc0d333db202ba5
+  metadata.gz: bd23ac9b3363d467c1e47258654ed3d9a136e32e66379374b2d33a1abeeb358a1957de66364ad5af3dd20768a4ace5226ccb57c256b18b232de0381fe3144d25
+  data.tar.gz: e304e3e8b87c093eabc07628c0179c15eef76d9870483d96a129ce9f2f1358d0ec50df14e369e2c052aa59b992bcae2647753f3cb62f9e37de1d06b221332f4b

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2019-2023 Nate Pickens
+Copyright 2019-2024 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)).
 
-# 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
+1.0.0

data/lib/htx/template.rb

@@ -20,8 +20,8 @@ module HTX
     INDENT_GUESS = /^( +|\t+)(?=\S)/.freeze
     INDENT_REGEX = /\n(?=[^\n])/.freeze
 
-    NO_SEMICOLON_BEGIN = /\A\s*[\n;}]/.freeze
-    NO_SEMICOLON_END = /(\A|[\n;{}][^\S\n]*)\z/.freeze
+    AUTO_SEMICOLON_BEGIN = /\A\s*[\n;}]/.freeze
+    AUTO_SEMICOLON_END = /(\A|[\n;{}][^\S\n]*)\z/.freeze
 
     NEWLINE_BEGIN = /\A\s*\n/.freeze
     NEWLINE_END = /\n[^\S\n]*\z/.freeze
@@ -58,10 +58,14 @@ module HTX
     ##
     # Compiles the HTX template.
     #
-    # * +assign_to+ - JavaScript object to assign the template function to (default: +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(assign_to: nil)
-      @assign_to = assign_to || 'globalThis'
+    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
       )
 
@@ -180,6 +182,7 @@ module HTX
     # * +xmlns+ - True if node is the descendant of a node with an xmlns attribute.
     #
     def process_element_node(node, xmlns: false)
+      is_template = node.name == 'template'
       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))
@@ -199,19 +202,21 @@ module HTX
           dynamic_key: dynamic_key,
         )
       else
-        append_htx_node(
-          "'#{self.class.tag_name(node.name)}'",
-          *attributes,
-          dynamic_key,
-          ELEMENT | (childless ? CHILDLESS : 0) | (xmlns ? XMLNS : 0),
-        )
+        unless is_template
+          append_htx_node(
+            "'#{self.class.tag_name(node.name)}'",
+            *attributes,
+            dynamic_key,
+            ELEMENT | (childless ? CHILDLESS : 0) | (xmlns ? XMLNS : 0),
+          )
+        end
 
         unless childless
           children.each do |child|
             process(child, xmlns: xmlns)
           end
 
-          @close_count += 1
+          @close_count += 1 unless is_template
         end
       end
     end
@@ -268,7 +273,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
@@ -279,8 +284,14 @@ module HTX
 
       if (confirmed_newline || @statement_buff.match?(NEWLINE_END)) && !text.match?(NEWLINE_BEGIN)
         @statement_buff << @indent
-      elsif !@statement_buff.match?(NO_SEMICOLON_END) && !text.match?(NO_SEMICOLON_BEGIN)
-        @statement_buff << ";#{' ' unless text.match?(WHITESPACE_BEGIN)}"
+      else
+        unless @statement_buff.match?(AUTO_SEMICOLON_END) || text.match?(AUTO_SEMICOLON_BEGIN)
+          @statement_buff << ";"
+        end
+
+        unless @statement_buff.empty? || text.match?(WHITESPACE_BEGIN)
+          @statement_buff << ' '
+        end
       end
 
       flush if text.match?(NON_WHITESPACE)
@@ -288,9 +299,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 +310,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
 
     ##
@@ -408,24 +419,100 @@ module HTX
 
     # Source: https://developer.mozilla.org/en-US/docs/Web/SVG/Element
     TAG_MAP = %w[
-      animateMotion animateTransform clipPath feBlend feColorMatrix feComponentTransfer feComposite
-      feConvolveMatrix feDiffuseLighting feDisplacementMap feDistantLight feDropShadow feFlood feFuncA
-      feFuncB feFuncG feFuncR feGaussianBlur feImage feMerge feMergeNode feMorphology feOffset fePointLight
-      feSpecularLighting feSpotLight feTile feTurbulence foreignObject linearGradient radialGradient
+      animateMotion
+      animateTransform
+      clipPath
+      feBlend
+      feColorMatrix
+      feComponentTransfer
+      feComposite
+      feConvolveMatrix
+      feDiffuseLighting
+      feDisplacementMap
+      feDistantLight
+      feDropShadow
+      feFlood
+      feFuncA
+      feFuncB
+      feFuncG
+      feFuncR
+      feGaussianBlur
+      feImage
+      feMerge
+      feMergeNode
+      feMorphology
+      feOffset
+      fePointLight
+      feSpecularLighting
+      feSpotLight
+      feTile
+      feTurbulence
+      foreignObject
+      linearGradient
+      radialGradient
       textPath
     ].map { |tag| [tag.downcase, tag] }.to_h.freeze
 
     # Source: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute
     ATTR_MAP = %w[
-      attributeName attributeType baseFrequency baseProfile calcMode clipPathUnits contentScriptType
-      contentStyleType diffuseConstant edgeMode filterRes filterUnits glyphRef gradientTransform
-      gradientUnits kernelMatrix kernelUnitLength keyPoints keySplines keyTimes lengthAdjust
-      limitingConeAngle markerHeight markerUnits markerWidth maskContentUnits maskUnits numOctaves
-      pathLength patternContentUnits patternTransform patternUnits pointsAtX pointsAtY pointsAtZ
-      preserveAlpha preserveAspectRatio primitiveUnits refX refY referrerPolicy repeatCount repeatDur
-      requiredExtensions requiredFeatures specularConstant specularExponent spreadMethod startOffset
-      stdDeviation stitchTiles surfaceScale systemLanguage tableValues targetX targetY textLength viewBox
-      viewTarget xChannelSelector yChannelSelector zoomAndPan
+      attributeName
+      attributeType
+      baseFrequency
+      baseProfile
+      calcMode
+      clipPathUnits
+      diffuseConstant
+      edgeMode
+      filterUnits
+      glyphRef
+      gradientTransform
+      gradientUnits
+      kernelMatrix
+      kernelUnitLength
+      keyPoints
+      keySplines
+      keyTimes
+      lengthAdjust
+      limitingConeAngle
+      markerHeight
+      markerUnits
+      markerWidth
+      maskContentUnits
+      maskUnits
+      numOctaves
+      pathLength
+      patternContentUnits
+      patternTransform
+      patternUnits
+      pointsAtX
+      pointsAtY
+      pointsAtZ
+      preserveAlpha
+      preserveAspectRatio
+      primitiveUnits
+      refX
+      refY
+      referrerPolicy
+      repeatCount
+      repeatDur
+      requiredExtensions
+      requiredFeatures
+      specularConstant
+      specularExponent
+      spreadMethod
+      startOffset
+      stdDeviation
+      stitchTiles
+      surfaceScale
+      systemLanguage
+      tableValues
+      targetX
+      targetY
+      textLength
+      viewBox
+      xChannelSelector
+      yChannelSelector
+      zoomAndPan
     ].map { |attr| [attr.downcase, attr] }.to_h.freeze
   end
 end

data/lib/htx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTX
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 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: 1.0.0
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2024-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -42,22 +42,16 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 5.11.2
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: '5.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 5.11.2
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: '5.21'
 description: HTX is a full-featured HTML template system that is simple, lightweight,
   and highly performant. This library is a Ruby implementation of the HTX template
   compiler--it converts HTX templates to their compiled JavaScript form.
@@ -78,9 +72,9 @@ homepage: https://github.com/npickens/htx
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/npickens/htx
-  source_code_uri: https://github.com/npickens/htx
+  bug_tracker_uri: https://github.com/npickens/htx/issues
+  documentation_uri: https://github.com/npickens/htx/blob/1.0.0/README.md
+  source_code_uri: https://github.com/npickens/htx/tree/1.0.0
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -89,14 +83,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: A Ruby compiler for HTX templates.