liquid 5.7.3 → 5.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 914cff799e3bd2ac8b59184ae521d8b8eccce15ee3d0dac103e471bcab5f1255
-  data.tar.gz: 38b104ec712e953540ab7316ce2e4cfac13a5964f5bc32ca39bc1252b908ac43
+  metadata.gz: d27b4c9417e479c5eec775f4ec1e5dd6165a2fb5fe76a8b769b31bc5acaff334
+  data.tar.gz: 77aef473425cf804dd4dfe1a17f00a424e70e30143952c9670c20d947fa038aa
 SHA512:
-  metadata.gz: f7c7f4e17b845a60ef8d7e2bf21b5378f5c116806ca62bb5f310b595275b3080294e378ea57bf2d70f35809ff4570142ccc77a62f0ac1c0afdd629ae6b1a5980
-  data.tar.gz: 48b4101e4e4c293ae10ef34ef701c8fcc3bbf764a55eca7b5a1022b95fa8f7e64d13f1e7ecc9cae5f456c12f30de9172baed90016de088384ec6847950a711b4
+  metadata.gz: 40f39337b8767db07e12beb2aa2a155a3bfb975752e02a09626b7fe3d53ef73c0c79252f29f2cb4a6edc63b8f0afff06d0df663d9a74d27a1f9507efd5db4a2c
+  data.tar.gz: 350ee158bdd4dabfb8781c937ca6426ee06cbaaedaffa469aa324fe717d7b7fbbf1f7a82aebd61a0bd9f96bc0ae4a94e887115385d1ca1f9c76aa2613ef88881

data/History.md

@@ -1,24 +1,30 @@
 # Liquid Change Log
 
-## 5.7.3 (unreleased)
+## 5.8.1 (unreleased)
 
-* Raise Liquid::SyntaxError when parsing invalidly encoded strings
+## 5.8.0
+
+* Introduce the new `{% doc %}` tag [Guilherme Carreiro]
+
+## 5.7.3
+
+* Raise Liquid::SyntaxError when parsing invalidly encoded strings [Chris AtLee]
 
 ## 5.7.2 2025-01-31
 
-* Fix array filters to not support nested properties
+* Fix array filters to not support nested properties [Guilherme Carreiro]
 
 ## 5.7.1 2025-01-24
 
-* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays
-* Fix the `has` filter to return `false` when filtering empty arrays
+* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays [Guilherme Carreiro]
+* Fix the `has` filter to return `false` when filtering empty arrays [Guilherme Carreiro]
 
 ## 5.7.0 2025-01-16
 
 ### Features
 
-* Add `find`, `find_index`, `has`, and `reject` filters to arrays
-* Compatibility with Ruby 3.4
+* Add `find`, `find_index`, `has`, and `reject` filters to arrays [Guilherme Carreiro]
+* Compatibility with Ruby 3.4 [Ian Ker-Seymer]
 
 ## 5.6.4 2025-01-14
 

data/lib/liquid/locales/en.yml

@@ -2,12 +2,14 @@
   errors:
     syntax:
       tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: %{tag}"
+      block_tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: {% %{tag} %}{% end%{tag} %}"
       assign: "Syntax Error in 'assign' - Valid syntax: assign [var] = [source]"
       capture: "Syntax Error in 'capture' - Valid syntax: capture [var]"
       case: "Syntax Error in 'case' - Valid syntax: case [condition]"
       case_invalid_when: "Syntax Error in tag 'case' - Valid when condition: {% when [condition] [or condition2...] %}"
       case_invalid_else: "Syntax Error in tag 'case' - Valid else condition: {% else %} (no parameters) "
       cycle: "Syntax Error in 'cycle' - Valid syntax: cycle [name :] var [, var2, var3 ...]"
+      doc_invalid_nested: "Syntax Error in 'doc' - Nested doc tags are not allowed"
       for: "Syntax Error in 'for loop' - Valid syntax: for [item] in [collection]"
       for_invalid_in: "For loops require an 'in' clause"
       for_invalid_attribute: "Invalid attribute in for loop. Valid attributes are limit and offset"

data/lib/liquid/tags/doc.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name doc
+  # @liquid_summary
+  #   Documents template elements with annotations.
+  # @liquid_description
+  #   The `doc` tag allows developers to include documentation within Liquid
+  #   templates. Any content inside `doc` tags is not rendered or outputted.
+  #   Liquid code inside will be parsed but not executed. This facilitates
+  #   tooling support for features like code completion, linting, and inline
+  #   documentation.
+  # @liquid_syntax
+  #   {% doc %}
+  #     Renders a message.
+  #
+  #     @param {string} foo - A foo value.
+  #     @param {string} [bar] - An optional bar value.
+  #
+  #     @example
+  #     {% render 'message', foo: 'Hello', bar: 'World' %}
+  #   {% enddoc %}
+  #   {{ foo }}, {{ bar }}!
+  class Doc < Block
+    NO_UNEXPECTED_ARGS = /\A\s*\z/
+
+    def initialize(tag_name, markup, parse_context)
+      super
+      ensure_valid_markup(tag_name, markup, parse_context)
+    end
+
+    def parse(tokens)
+      while (token = tokens.shift)
+        tag_name = token =~ BlockBody::FullTokenPossiblyInvalid && Regexp.last_match(2)
+
+        raise_nested_doc_error if tag_name == @tag_name
+
+        if tag_name == block_delimiter
+          parse_context.trim_whitespace = (token[-3] == WhitespaceControl)
+          return
+        end
+      end
+
+      raise_tag_never_closed(block_name)
+    end
+
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def blank?
+      true
+    end
+
+    private
+
+    def ensure_valid_markup(tag_name, markup, parse_context)
+      unless NO_UNEXPECTED_ARGS.match?(markup)
+        raise SyntaxError, parse_context.locale.t("errors.syntax.block_tag_unexpected_args", tag: tag_name)
+      end
+    end
+
+    def raise_nested_doc_error
+      raise SyntaxError, parse_context.locale.t("errors.syntax.doc_invalid_nested")
+    end
+  end
+end

data/lib/liquid/tags.rb

@@ -19,6 +19,7 @@ require_relative "tags/comment"
 require_relative "tags/raw"
 require_relative "tags/render"
 require_relative "tags/cycle"
+require_relative "tags/doc"
 
 module Liquid
   module Tags
@@ -42,6 +43,7 @@ module Liquid
       'if' => If,
       'echo' => Echo,
       'tablerow' => TableRow,
+      'doc' => Doc,
     }.freeze
   end
 end

data/lib/liquid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Liquid
-  VERSION = "5.7.3"
+  VERSION = "5.8.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: liquid
 version: !ruby/object:Gem::Version
-  version: 5.7.3
+  version: 5.8.0
 platform: ruby
 authors:
 - Tobias Lütke
 bindir: bin
 cert_chain: []
-date: 2025-02-24 00:00:00.000000000 Z
+date: 2025-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: strscan
@@ -120,6 +120,7 @@ files:
 - lib/liquid/tags/continue.rb
 - lib/liquid/tags/cycle.rb
 - lib/liquid/tags/decrement.rb
+- lib/liquid/tags/doc.rb
 - lib/liquid/tags/echo.rb
 - lib/liquid/tags/for.rb
 - lib/liquid/tags/if.rb