Update rubocop_todo

.rubocop_todo.yml

@@ -1,13 +1,21 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2022-05-18 19:25:47 UTC using RuboCop version 1.29.1.
+# on 2022-06-01 17:13:35 UTC using RuboCop version 1.30.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 1
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Include.
+# Include: **/*.gemspec
+Gemspec/DeprecatedAttributeAssignment:
+  Exclude:
+    - 'liquid.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: TreatCommentsAsGroupSeparators, ConsiderPunctuation, Include.
 # Include: **/*.gemspec
 Gemspec/OrderedDependencies:
@@ -15,13 +23,13 @@ Gemspec/OrderedDependencies:
     - 'liquid.gemspec'
 
 # Offense count: 6
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 Layout/ClosingHeredocIndentation:
   Exclude:
     - 'test/integration/tags/for_tag_test.rb'
 
 # Offense count: 34
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 Layout/EmptyLineAfterGuardClause:
   Exclude:
     - 'lib/liquid/block.rb'
@@ -41,7 +49,7 @@ Layout/EmptyLineAfterGuardClause:
     - 'performance/shopify/paginate.rb'
 
 # Offense count: 8
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowAliasSyntax, AllowedMethods.
 # AllowedMethods: alias_method, public, protected, private
 Layout/EmptyLinesAroundAttributeAccessor:
@@ -52,7 +60,7 @@ Layout/EmptyLinesAroundAttributeAccessor:
     - 'test/unit/strainer_template_unit_test.rb'
 
 # Offense count: 17
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: aligned, indented
 Layout/LineEndStringConcatenationIndentation:
@@ -61,7 +69,7 @@ Layout/LineEndStringConcatenationIndentation:
     - 'test/integration/tags/increment_tag_test.rb'
 
 # Offense count: 1
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: aligned, indented
 Layout/MultilineOperationIndentation:
@@ -113,7 +121,7 @@ Style/ClassVars:
     - 'lib/liquid/condition.rb'
 
 # Offense count: 3
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 Style/ExplicitBlockArgument:
   Exclude:
     - 'test/integration/context_test.rb'
@@ -121,14 +129,14 @@ Style/ExplicitBlockArgument:
     - 'test/integration/tags/for_tag_test.rb'
 
 # Offense count: 2982
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
 # SupportedStyles: single_quotes, double_quotes
 Style/StringLiterals:
   Enabled: false
 
 # Offense count: 20
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: single_quotes, double_quotes
 Style/StringLiteralsInInterpolation:
@@ -140,7 +148,7 @@ Style/StringLiteralsInInterpolation:
     - 'performance/shopify/tag_filter.rb'
 
 # Offense count: 6
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInArrayLiteral:
@@ -152,7 +160,7 @@ Style/TrailingCommaInArrayLiteral:
     - 'test/unit/parse_tree_visitor_test.rb'
 
 # Offense count: 1
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInHashLiteral:
@@ -160,7 +168,7 @@ Style/TrailingCommaInHashLiteral:
     - 'lib/liquid/expression.rb'
 
 # Offense count: 19
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, MinSize, WordRegex.
 # SupportedStyles: percent, brackets
 Style/WordArray:
@@ -173,7 +181,7 @@ Style/WordArray:
     - 'test/integration/standard_filter_test.rb'
 
 # Offense count: 117
-# This cop supports safe auto-correction (--auto-correct).
+# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, IgnoredPatterns.
 # URISchemes: http, https
 Layout/LineLength:

Gemfile

@@ -18,7 +18,7 @@ group :benchmark, :test do
 end
 
 group :test do
-  gem 'rubocop-shopify', '~> 2.7.0', require: false
+  gem 'rubocop-shopify', '~> 2.6', require: false
   gem 'rubocop-performance', require: false
 
   platform :mri, :truffleruby do

History.md

@@ -11,10 +11,9 @@
 ### Fixes
 * `PartialCache` now shares snippet cache with subcontexts by default (#1553) [Chris AtLee]
 * Hash registers no longer leak into subcontexts as static registers (#1564) [Chris AtLee]
-* Fix `ParseTreeVisitor` for `with` variable expressions in `Render` tag (#1596) [CP Clermont]
 
 ### Changed
-* Liquid::Context#registers now always returns a Liquid::Registers object, though supports the most used Hash functions for compatibility (#1553)
+* Liquid::Context#registers now always returns a Liquid::StaticRegisters object, though supports the most used Hash functions for compatibility (#1553)
 
 ## 5.3.0 2022-03-22
 

lib/liquid.rb

@@ -84,7 +84,8 @@ require 'liquid/tokenizer'
 require 'liquid/parse_context'
 require 'liquid/partial_cache'
 require 'liquid/usage'
-require 'liquid/registers'
+require 'liquid/register'
+require 'liquid/static_registers'
 require 'liquid/template_factory'
 
 # Load all the tags of the standard library

lib/liquid/context.rb

@@ -28,7 +28,7 @@ module Liquid
 
       @static_environments = [static_environments].flat_map(&:freeze).freeze
       @scopes              = [(outer_scope || {})]
-      @registers           = registers.is_a?(Registers) ? registers : Registers.new(registers)
+      @registers           = registers.is_a?(StaticRegisters) ? registers : StaticRegisters.new(registers)
       @errors              = []
       @partial             = false
       @strict_variables    = false
@@ -144,7 +144,7 @@ module Liquid
       self.class.build(
         resource_limits: resource_limits,
         static_environments: static_environments,
-        registers: Registers.new(registers)
+        registers: StaticRegisters.new(registers)
       ).tap do |subcontext|
         subcontext.base_scope_depth   = base_scope_depth + 1
         subcontext.exception_renderer = exception_renderer

lib/liquid/forloop_drop.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type object
-  # @liquid_name forloop
-  # @liquid_summary
-  #   Information about a parent [`for` loop](/api/liquid/tags#for).
   class ForloopDrop < Drop
     def initialize(name, length, parentloop)
       @name       = name
@@ -14,71 +9,33 @@ module Liquid
       @index      = 0
     end
 
-    # @liquid_public_docs
-    # @liquid_name length
-    # @liquid_summary
-    #   The total number of iterations in the loop.
-    # @liquid_return [number]
-    attr_reader :length
-
-    # @liquid_public_docs
-    # @liquid_name parentloop
-    # @liquid_summary
-    #   The parent `forloop` object.
-    # @liquid_description
-    #   If the current `for` loop isn't nested inside another `for` loop, then `nil` is returned.
-    # @liquid_return [forloop]
-    attr_reader :parentloop
+    attr_reader :length, :parentloop
 
     def name
       Usage.increment('forloop_drop_name')
       @name
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of the current iteration.
-    # @liquid_return [number]
     def index
       @index + 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 0-based index of the current iteration.
-    # @liquid_return [number]
     def index0
       @index
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of the current iteration, in reverse order.
-    # @liquid_return [number]
     def rindex
       @length - @index
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 0-based index of the current iteration, in reverse order.
-    # @liquid_return [number]
     def rindex0
       @length - @index - 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current iteration is the first. Returns `false` if not.
-    # @liquid_return [boolean]
     def first
       @index == 0
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current iteration is the last. Returns `false` if not.
-    # @liquid_return [boolean]
     def last
       @index == @length - 1
     end

lib/liquid/register.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Liquid
+  class Register
+  end
+end

lib/liquid/standardfilters.rb

@@ -22,99 +22,39 @@ module Liquid
     )
     STRIP_HTML_TAGS = /<.*?>/m
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Returns the size of a string or array.
-    # @liquid_description
-    #   The size of a string is the number of characters that the string includes. The size of an array is the number of items
-    #   in the array.
-    # @liquid_syntax variable | size
-    # @liquid_return [number]
+    # Return the size of an array or of an string
     def size(input)
       input.respond_to?(:size) ? input.size : 0
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Converts a string to all lowercase characters.
-    # @liquid_syntax string | downcase
-    # @liquid_return [string]
+    # convert an input string to DOWNCASE
     def downcase(input)
       input.to_s.downcase
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Converts a string to all uppercase characters.
-    # @liquid_syntax string | upcase
-    # @liquid_return [string]
+    # convert an input string to UPCASE
     def upcase(input)
       input.to_s.upcase
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Capitalizes the first word in a string.
-    # @liquid_syntax string | capitalize
-    # @liquid_return [string]
+    # capitalize words in the input centence
     def capitalize(input)
       input.to_s.capitalize
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Escapes a string.
-    # @liquid_syntax string | escape
-    # @liquid_return [string]
     def escape(input)
       CGI.escapeHTML(input.to_s) unless input.nil?
     end
     alias_method :h, :escape
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Escapes a string without changing characters that have already been escaped.
-    # @liquid_syntax string | escape_once
-    # @liquid_return [string]
     def escape_once(input)
       input.to_s.gsub(HTML_ESCAPE_ONCE_REGEXP, HTML_ESCAPE)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Converts any URL-unsafe characters in a string to the
-    #   [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) equivalent.
-    # @liquid_description
-    #   > Note:
-    #   > Spaces are converted to a `+` character, instead of a percent-encoded character.
-    # @liquid_syntax string | url_encode
-    # @liquid_return [string]
     def url_encode(input)
       CGI.escape(input.to_s) unless input.nil?
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Decodes any [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) characters
-    #   in a string.
-    # @liquid_syntax string | url_decode
-    # @liquid_return [string]
     def url_decode(input)
       return if input.nil?
 
@@ -124,64 +64,26 @@ module Liquid
       result
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Encodes a string to [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
-    # @liquid_syntax string | base64_encode
-    # @liquid_return [string]
     def base64_encode(input)
       Base64.strict_encode64(input.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Decodes a string in [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
-    # @liquid_syntax string | base64_decode
-    # @liquid_return [string]
     def base64_decode(input)
       Base64.strict_decode64(input.to_s)
     rescue ::ArgumentError
       raise Liquid::ArgumentError, "invalid base64 provided to base64_decode"
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Encodes a string to URL-safe [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
-    # @liquid_syntax string | base64_url_safe_encode
-    # @liquid_return [string]
     def base64_url_safe_encode(input)
       Base64.urlsafe_encode64(input.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Decodes a string in URL-safe [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
-    # @liquid_syntax string | base64_url_safe_decode
-    # @liquid_return [string]
     def base64_url_safe_decode(input)
       Base64.urlsafe_decode64(input.to_s)
     rescue ::ArgumentError
       raise Liquid::ArgumentError, "invalid base64 provided to base64_url_safe_decode"
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Returns a substring or series of array items, starting at a given 0-based index.
-    # @liquid_description
-    #   By default, the substring has a length of one character, and the array series has one array item. However, you can
-    #   provide a second parameter to specify the number of characters or array items.
-    # @liquid_syntax string | slice
-    # @liquid_return [string]
     def slice(input, offset, length = nil)
       offset = Utils.to_integer(offset)
       length = length ? Utils.to_integer(length) : 1
@@ -193,16 +95,7 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Truncates a string down to a given number of characters.
-    # @liquid_description
-    #   If the specified number of characters is less than the length of the string, then an ellipsis (`...`) is appended to
-    #   the truncated string. The ellipsis is included in the character count of the truncated string.
-    # @liquid_syntax string | truncate: number
-    # @liquid_return [string]
+    # Truncate a string down to x characters
     def truncate(input, length = 50, truncate_string = "...")
       return if input.nil?
       input_str = input.to_s
@@ -216,20 +109,6 @@ module Liquid
       input_str.length > length ? input_str[0...l].concat(truncate_string_str) : input_str
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Truncates a string down to a given number of words.
-    # @liquid_description
-    #   If the specified number of words is less than the number of words in the string, then an ellipsis (`...`) is appended to
-    #   the truncated string.
-    #
-    #   > Caution:
-    #   > HTML tags are treated as words, so you should strip any HTML from truncated content. If you don't strip HTML, then
-    #   > closing HTML tags can be removed, which can result in unexpected behavior.
-    # @liquid_syntax string | truncatewords: number
-    # @liquid_return [string]
     def truncatewords(input, words = 15, truncate_string = "...")
       return if input.nil?
       input = input.to_s
@@ -249,57 +128,27 @@ module Liquid
       wordlist.join(" ").concat(truncate_string.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Splits a string into an array of substrings based on a given separator.
-    # @liquid_syntax string | split: string
-    # @liquid_return [array[string]]
+    # Split input string into an array of substrings separated by given pattern.
+    #
+    # Example:
+    #   <div class="summary">{{ post | split '//' | first }}</div>
+    #
     def split(input, pattern)
       input.to_s.split(pattern.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Strips all whitespace from the left and right of a string.
-    # @liquid_syntax string | strip
-    # @liquid_return [string]
     def strip(input)
       input.to_s.strip
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Strips all whitespace from the left of a string.
-    # @liquid_syntax string | lstrip
-    # @liquid_return [string]
     def lstrip(input)
       input.to_s.lstrip
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Strips all whitespace from the right of a string.
-    # @liquid_syntax string | rstrip
-    # @liquid_return [string]
     def rstrip(input)
       input.to_s.rstrip
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Strips all HTML tags from a string.
-    # @liquid_syntax string | strip_html
-    # @liquid_return [string]
     def strip_html(input)
       empty  = ''
       result = input.to_s.gsub(STRIP_HTML_BLOCKS, empty)
@@ -307,35 +156,18 @@ module Liquid
       result
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Strips all newline characters (line breaks) from a string.
-    # @liquid_syntax string | strip_newlines
-    # @liquid_return [string]
+    # Remove all newlines from the string
     def strip_newlines(input)
       input.to_s.gsub(/\r?\n/, '')
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Combines all of the items in an array into a single string, separated by a space.
-    # @liquid_syntax array | join
-    # @liquid_return [string]
+    # Join elements of the array with certain character between them
     def join(input, glue = ' ')
       InputIterator.new(input, context).join(glue)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Sorts the items in an array in case-sensitive alphabetical, or numerical, order.
-    # @liquid_syntax array | sort
-    # @liquid_return [array[untyped]]
+    # Sort elements of the array
+    # provide optional property with which to sort an array of hashes or drops
     def sort(input, property = nil)
       ary = InputIterator.new(input, context)
 
@@ -354,17 +186,8 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Sorts the items in an array in case-insensitive alphabetical order.
-    # @liquid_description
-    #   > Caution:
-    #   > You shouldn't use the `sort_natural` filter to sort numerical values. When comparing items an array, each item is converted to a
-    #   > string, so sorting on numerical values can lead to unexpected results.
-    # @liquid_syntax array | sort_natural
-    # @liquid_return [array[untyped]]
+    # Sort elements of an array ignoring case if strings
+    # provide optional property with which to sort an array of hashes or drops
     def sort_natural(input, property = nil)
       ary = InputIterator.new(input, context)
 
@@ -383,15 +206,8 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Filters an array to include only items with a specific property value.
-    # @liquid_description
-    #   This requires you to provide both the property name and the associated value.
-    # @liquid_syntax array | where: string, string
-    # @liquid_return [array[untyped]]
+    # Filter the elements of an array to those with a certain property value.
+    # By default the target is any truthy value.
     def where(input, property, target_value = nil)
       ary = InputIterator.new(input, context)
 
@@ -418,13 +234,8 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Removes any duplicate items in an array.
-    # @liquid_syntax array | uniq
-    # @liquid_return [array[untyped]]
+    # Remove duplicate elements from an array
+    # provide optional property with which to determine uniqueness
     def uniq(input, property = nil)
       ary = InputIterator.new(input, context)
 
@@ -444,25 +255,13 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Reverses the order of the items in an array.
-    # @liquid_syntax array | reverse
-    # @liquid_return [array[untyped]]
+    # Reverse the elements of an array
     def reverse(input)
       ary = InputIterator.new(input, context)
       ary.reverse
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Creates an array of values from a specific property of the items in an array.
-    # @liquid_syntax array | map: string
-    # @liquid_return [array[untyped]]
+    # map/collect on a given property
     def map(input, property)
       InputIterator.new(input, context).map do |e|
         e = e.call if e.is_a?(Proc)
@@ -478,13 +277,8 @@ module Liquid
       raise_property_error(property)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Removes any `nil` items from an array.
-    # @liquid_syntax array | compact
-    # @liquid_return [array[untyped]]
+    # Remove nils within an array
+    # provide optional property with which to check for nil
     def compact(input, property = nil)
       ary = InputIterator.new(input, context)
 
@@ -504,35 +298,17 @@ module Liquid
       end
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Replaces any instance of a substring inside a string with a given string.
-    # @liquid_syntax string | replace: string, string
-    # @liquid_return [string]
+    # Replace occurrences of a string with another
     def replace(input, string, replacement = '')
       input.to_s.gsub(string.to_s, replacement.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Replaces the first instance of a substring inside a string with a given string.
-    # @liquid_syntax string | replace_first: string, string
-    # @liquid_return [string]
+    # Replace the first occurrences of a string with another
     def replace_first(input, string, replacement = '')
       input.to_s.sub(string.to_s, replacement.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Replaces the last instance of a substring inside a string with a given string.
-    # @liquid_syntax string | replace_last: string, string
-    # @liquid_return [string]
+    # Replace the last occurrences of a string with another
     def replace_last(input, string, replacement)
       input = input.to_s
       string = string.to_s
@@ -547,61 +323,26 @@ module Liquid
       output
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Removes any instance of a substring inside a string.
-    # @liquid_syntax string | remove: string
-    # @liquid_return [string]
+    # remove a substring
     def remove(input, string)
       replace(input, string, '')
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Removes the first instance of a substring inside a string.
-    # @liquid_syntax string | remove_first: string
-    # @liquid_return [string]
+    # remove the first occurrences of a substring
     def remove_first(input, string)
       replace_first(input, string, '')
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Removes the last instance of a substring inside a string.
-    # @liquid_syntax string | remove_last: string
-    # @liquid_return [string]
+    # remove the last occurences of a substring
     def remove_last(input, string)
       replace_last(input, string, '')
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Adds a given string to the end of a string.
-    # @liquid_syntax string | append: string
-    # @liquid_return [string]
+    # add one string to another
     def append(input, string)
       input.to_s + string.to_s
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Concatenates (combines) two arrays.
-    # @liquid_description
-    #   > Note:
-    #   > The `concat` filter won't filter out duplicates. If you want to remove duplicates, then you need to use the
-    #   > [`uniq` filter](/api/liquid/filters#uniq).
-    # @liquid_syntax array | concat: array
-    # @liquid_return [array[untyped]]
     def concat(input, array)
       unless array.respond_to?(:to_ary)
         raise ArgumentError, "concat filter requires an array argument"
@@ -609,24 +350,12 @@ module Liquid
       InputIterator.new(input, context).concat(array)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Adds a given string to the beginning of a string.
-    # @liquid_syntax string | prepend: string
-    # @liquid_return [string]
+    # prepend a string to another
     def prepend(input, string)
       string.to_s + input.to_s
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category string
-    # @liquid_summary
-    #   Converts newlines (`\n`) in a string to HTML line breaks (`<br>`).
-    # @liquid_syntax string | newline_to_br
-    # @liquid_return [string]
+    # Add <br /> tags in front of all newlines in input string
     def newline_to_br(input)
       input.to_s.gsub(/\r?\n/, "<br />\n")
     end
@@ -670,106 +399,58 @@ module Liquid
       date.strftime(format.to_s)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Returns the first item in an array.
-    # @liquid_syntax array | first
-    # @liquid_return [untyped]
+    # Get the first element of the passed in array
+    #
+    # Example:
+    #    {{ product.images | first | to_img }}
+    #
     def first(array)
       array.first if array.respond_to?(:first)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category array
-    # @liquid_summary
-    #   Returns the last item in an array.
-    # @liquid_syntax array | last
-    # @liquid_return [untyped]
+    # Get the last element of the passed in array
+    #
+    # Example:
+    #    {{ product.images | last | to_img }}
+    #
     def last(array)
       array.last if array.respond_to?(:last)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Returns the absolute value of a number.
-    # @liquid_syntax number | abs
-    # @liquid_return [number]
+    # absolute value
     def abs(input)
       result = Utils.to_number(input).abs
       result.is_a?(BigDecimal) ? result.to_f : result
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Adds two numbers.
-    # @liquid_syntax number | plus: number
-    # @liquid_return [number]
+    # addition
     def plus(input, operand)
       apply_operation(input, operand, :+)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Subtracts a given number from another number.
-    # @liquid_syntax number | minus: number
-    # @liquid_return [number]
+    # subtraction
     def minus(input, operand)
       apply_operation(input, operand, :-)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Multiplies a number by a given number.
-    # @liquid_syntax number | times: number
-    # @liquid_return [number]
+    # multiplication
     def times(input, operand)
       apply_operation(input, operand, :*)
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Divides a number by a given number.
-    # @liquid_syntax number | divided_by: number
-    # @liquid_return [number]
+    # division
     def divided_by(input, operand)
       apply_operation(input, operand, :/)
     rescue ::ZeroDivisionError => e
       raise Liquid::ZeroDivisionError, e.message
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Returns the remainder of dividing a number by a given number.
-    # @liquid_syntax number | modulo: number
-    # @liquid_return [number]
     def modulo(input, operand)
       apply_operation(input, operand, :%)
     rescue ::ZeroDivisionError => e
       raise Liquid::ZeroDivisionError, e.message
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Rounds a number to the nearest integer.
-    # @liquid_syntax number | round
-    # @liquid_return [number]
     def round(input, n = 0)
       result = Utils.to_number(input).round(Utils.to_number(n))
       result = result.to_f if result.is_a?(BigDecimal)
@@ -779,39 +460,18 @@ module Liquid
       raise Liquid::FloatDomainError, e.message
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Rounds a number up to the nearest integer.
-    # @liquid_syntax number | ceil
-    # @liquid_return [number]
     def ceil(input)
       Utils.to_number(input).ceil.to_i
     rescue ::FloatDomainError => e
       raise Liquid::FloatDomainError, e.message
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Rounds a number down to the nearest integer.
-    # @liquid_syntax number | floor
-    # @liquid_return [number]
     def floor(input)
       Utils.to_number(input).floor.to_i
     rescue ::FloatDomainError => e
       raise Liquid::FloatDomainError, e.message
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Limits a number to a minimum value.
-    # @liquid_syntax number | at_least
-    # @liquid_return [number]
     def at_least(input, n)
       min_value = Utils.to_number(n)
 
@@ -820,13 +480,6 @@ module Liquid
       result.is_a?(BigDecimal) ? result.to_f : result
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category math
-    # @liquid_summary
-    #   Limits a number to a maximum value.
-    # @liquid_syntax number | at_most
-    # @liquid_return [number]
     def at_most(input, n)
       max_value = Utils.to_number(n)
 
@@ -835,18 +488,16 @@ module Liquid
       result.is_a?(BigDecimal) ? result.to_f : result
     end
 
-    # @liquid_public_docs
-    # @liquid_type filter
-    # @liquid_category default
-    # @liquid_summary
-    #   Sets a default value for any variable whose value is one of the following:
+    # Set a default value when the input is nil, false or empty
+    #
+    # Example:
+    #    {{ product.title | default: "No Title" }}
+    #
+    # Use `allow_false` when an input should only be tested against nil or empty and not false.
+    #
+    # Example:
+    #    {{ product.title | default: "No Title", allow_false: true }}
     #
-    #   - [`empty`](/api/liquid/basics#empty)
-    #   - [`false`](/api/liquid/basics#truthy-and-falsy)
-    #   - [`nil`](/api/liquid/basics#nil)
-    # @liquid_syntax variable | default: variable
-    # @liquid_return [untyped]
-    # @liquid_optional_param allow_false [boolean] Whether to use false values instead of the default.
     def default(input, default_value = '', options = {})
       options = {} unless options.is_a?(Hash)
       false_check = options['allow_false'] ? input.nil? : !Liquid::Utils.to_liquid_value(input)

lib/liquid/static_registers.rb

@@ -1,35 +1,35 @@
 # frozen_string_literal: true
 
 module Liquid
-  class Registers
+  class StaticRegisters
     attr_reader :static
 
     def initialize(registers = {})
-      @static = registers.is_a?(Registers) ? registers.static : registers
-      @changes = {}
+      @static    = registers.is_a?(StaticRegisters) ? registers.static : registers
+      @registers = {}
     end
 
     def []=(key, value)
-      @changes[key] = value
+      @registers[key] = value
     end
 
     def [](key)
-      if @changes.key?(key)
-        @changes[key]
+      if @registers.key?(key)
+        @registers[key]
       else
         @static[key]
       end
     end
 
     def delete(key)
-      @changes.delete(key)
+      @registers.delete(key)
     end
 
     UNDEFINED = Object.new
 
     def fetch(key, default = UNDEFINED, &block)
-      if @changes.key?(key)
-        @changes.fetch(key)
+      if @registers.key?(key)
+        @registers.fetch(key)
       elsif default != UNDEFINED
         if block_given?
           @static.fetch(key, &block)
@@ -42,10 +42,7 @@ module Liquid
     end
 
     def key?(key)
-      @changes.key?(key) || @static.key?(key)
+      @registers.key?(key) || @static.key?(key)
     end
   end
-
-  # Alias for backwards compatibility
-  StaticRegisters = Registers
 end

lib/liquid/tablerowloop_drop.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type object
-  # @liquid_name tablerowloop
-  # @liquid_summary
-  #   Information about a parent [`tablerow` loop](/api/liquid/tags#tablerow).
   class TablerowloopDrop < Drop
     def initialize(length, cols)
       @length = length
@@ -15,92 +10,40 @@ module Liquid
       @index  = 0
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The total number of iterations in the loop.
-    # @liquid_return [number]
-    attr_reader :length
+    attr_reader :length, :col, :row
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of the current column.
-    # @liquid_return [number]
-    attr_reader :col
-
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of current row.
-    # @liquid_return [number]
-    attr_reader :row
-
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of the current iteration.
-    # @liquid_return [number]
     def index
       @index + 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 0-based index of the current iteration.
-    # @liquid_return [number]
     def index0
       @index
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 0-based index of the current column.
-    # @liquid_return [number]
     def col0
       @col - 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 1-based index of the current iteration, in reverse order.
-    # @liquid_return [number]
     def rindex
       @length - @index
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   The 0-based index of the current iteration, in reverse order.
-    # @liquid_return [number]
     def rindex0
       @length - @index - 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current iteration is the first. Returns `false` if not.
-    # @liquid_return [boolean]
     def first
       @index == 0
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current iteration is the last. Returns `false` if not.
-    # @liquid_return [boolean]
     def last
       @index == @length - 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current column is the first in the row. Returns `false` if not.
-    # @liquid_return [boolean]
     def col_first
       @col == 1
     end
 
-    # @liquid_public_docs
-    # @liquid_summary
-    #   Returns `true` if the current column is the last in the row. Returns `false` if not.
-    # @liquid_return [boolean]
     def col_last
       @col == @cols
     end

lib/liquid/tags/assign.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category variable
-  # @liquid_name assign
-  # @liquid_summary
-  #   Creates a new variable.
-  # @liquid_description
-  #   You can create variables of any [basic type](/api/liquid/basics#types), [object](/api/liquid/objects), or object property.
-  # @liquid_syntax
-  #   {% assign variable_name = value %}
-  # @liquid_syntax_keyword variable_name The name of the variable being created.
-  # @liquid_syntax_keyword value The value you want to assign to the variable.
+  # Assign sets a variable in your template.
+  #
+  #   {% assign foo = 'monkey' %}
+  #
+  # You can then use the variable later in the page.
+  #
+  #  {{ foo }}
+  #
   class Assign < Tag
     Syntax = /(#{VariableSignature}+)\s*=\s*(.*)\s*/om
 

lib/liquid/tags/break.rb

@@ -10,14 +10,6 @@ module Liquid
   #      {% endif %}
   #    {% endfor %}
   #
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category iteration
-  # @liquid_name break
-  # @liquid_summary
-  #   Stops a [`for` loop](/api/liquid/tags#for) from iterating.
-  # @liquid_syntax
-  #   {% break %}
   class Break < Tag
     INTERRUPT = BreakInterrupt.new.freeze
 

lib/liquid/tags/capture.rb

@@ -1,20 +1,17 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category variable
-  # @liquid_name capture
-  # @liquid_summary
-  #   Creates a new variable with a string value.
-  # @liquid_description
-  #   You can create complex strings with Liquid logic and variables.
-  # @liquid_syntax
-  #   {% capture variable %}
-  #     value
+  # Capture stores the result of a block into a variable without rendering it inplace.
+  #
+  #   {% capture heading %}
+  #     Monkeys!
   #   {% endcapture %}
-  # @liquid_syntax_keyword variable The name of the variable being created.
-  # @liquid_syntax_keyword value The value you want to assign to the variable.
+  #   ...
+  #   <h1>{{ heading }}</h1>
+  #
+  # Capture is useful for saving content for use later in your template, such as
+  # in a sidebar or footer.
+  #
   class Capture < Block
     Syntax = /(#{VariableSignature}+)/o
 

lib/liquid/tags/case.rb

@@ -1,27 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category conditional
-  # @liquid_name case
-  # @liquid_summary
-  #   Renders a specific expression depending on the value of a specific variable.
-  # @liquid_syntax
-  #   {% case variable %}
-  #     {% when first_value %}
-  #       first_expression
-  #     {% when second_value %}
-  #       second_expression
-  #     {% else %}
-  #       third_expression
-  #   {% endcase %}
-  # @liquid_syntax_keyword variable The name of the variable you want to base your case statement on.
-  # @liquid_syntax_keyword first_value A specific value to check for.
-  # @liquid_syntax_keyword second_value A specific value to check for.
-  # @liquid_syntax_keyword first_expression An expression to be rendered when the variable's value matches `first_value`.
-  # @liquid_syntax_keyword second_expression An expression to be rendered when the variable's value matches `second_value`.
-  # @liquid_syntax_keyword third_expression An expression to be rendered when the variable's value has no match.
   class Case < Block
     Syntax     = /(#{QuotedFragment})/o
     WhenSyntax = /(#{QuotedFragment})(?:(?:\s+or\s+|\s*\,\s*)(#{QuotedFragment}.*))?/om

lib/liquid/tags/comment.rb

@@ -1,19 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category syntax
-  # @liquid_name comment
-  # @liquid_summary
-  #   Prevents an expression from being rendered or output.
-  # @liquid_description
-  #   Any text inside `comment` tags won't be output, and any Liquid code won't be rendered.
-  # @liquid_syntax
-  #   {% comment %}
-  #     content
-  #   {% endcomment %}
-  # @liquid_syntax_keyword content The content of the comment.
   class Comment < Block
     def render_to_output_buffer(_context, output)
       output

lib/liquid/tags/continue.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category iteration
-  # @liquid_name continue
-  # @liquid_summary
-  #   Causes a [`for` loop](/api/liquid/tags#for) to skip to the next iteration.
-  # @liquid_syntax
-  #   {% continue %}
+  # Continue tag to be used to break out of a for loop.
+  #
+  # == Basic Usage:
+  #    {% for item in collection %}
+  #      {% if item.condition %}
+  #        {% continue %}
+  #      {% endif %}
+  #    {% endfor %}
+  #
   class Continue < Tag
     INTERRUPT = ContinueInterrupt.new.freeze
 

lib/liquid/tags/cycle.rb

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category iteration
-  # @liquid_name cycle
-  # @liquid_summary
-  #   Loops through a group of strings and outputs them one at a time for each iteration of a [`for` loop](/api/liquid/tags#for).
-  # @liquid_description
-  #   The `cycle` tag must be used inside a `for` loop.
+  # Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
+  #
+  #   {% for item in items %}
+  #     <div class="{% cycle 'red', 'green', 'blue' %}"> {{ item }} </div>
+  #   {% end %}
+  #
+  #    <div class="red"> Item one </div>
+  #    <div class="green"> Item two </div>
+  #    <div class="blue"> Item three </div>
+  #    <div class="red"> Item four </div>
+  #    <div class="green"> Item five</div>
   #
-  #   > Tip:
-  #   > Use the `cycle` tag to output text in a predictable pattern. For example, to apply odd/even classes to rows in a table.
-  # @liquid_syntax
-  #   {% cycle string, string, ... %}
   class Cycle < Tag
     SimpleSyntax = /\A#{QuotedFragment}+/o
     NamedSyntax  = /\A(#{QuotedFragment})\s*\:\s*(.*)/om

lib/liquid/tags/decrement.rb

@@ -1,23 +1,24 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category variable
-  # @liquid_name decrement
-  # @liquid_summary
-  #   Creates a new variable, with a default value of -1, that's decreased by 1 with each subsequent call.
-  # @liquid_description
-  #   Variables that are declared with `decrement` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
-  #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across
-  #   [snippets](/themes/architecture#snippets) included in the file.
+  # decrement is used in a place where one needs to insert a counter
+  #     into a template, and needs the counter to survive across
+  #     multiple instantiations of the template.
+  #     NOTE: decrement is a pre-decrement, --i,
+  #           while increment is post:      i++.
+  #
+  #     (To achieve the survival, the application must keep the context)
+  #
+  #     if the variable does not exist, it is created with value 0.
+
+  #   Hello: {% decrement variable %}
+  #
+  # gives you:
+  #
+  #    Hello: -1
+  #    Hello: -2
+  #    Hello: -3
   #
-  #   Similarly, variables that are created with `decrement` are independent from those created with [`assign`](/api/liquid/tags#assign)
-  #   and [`capture`](/api/liquid/tags#capture). However, `decrement` and [`increment`](/api/liquid/tags#increment) share
-  #   variables.
-  # @liquid_syntax
-  #   {% decrement variable_name %}
-  # @liquid_syntax_keyword variable_name The name of the variable being decremented.
   class Decrement < Tag
     def initialize(tag_name, markup, options)
       super

lib/liquid/tags/echo.rb

@@ -1,23 +1,16 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category syntax
-  # @liquid_name echo
-  # @liquid_summary
-  #   Outputs an expression.
-  # @liquid_description
-  #   Using the `echo` tag is the same as wrapping an expression in curly brackets (`{{` and `}}`). However, unlike the curly
-  #   bracket method, you can use the `echo` tag inside [`liquid` tags](/api/liquid/tags#liquid).
+  # Echo outputs an expression
+  #
+  #   {% echo monkey %}
+  #   {% echo user.name %}
+  #
+  # This is identical to variable output syntax, like {{ foo }}, but works
+  # inside {% liquid %} tags. The full syntax is supported, including filters:
+  #
+  #   {% echo user | link %}
   #
-  #   > Tip:
-  #   > You can use [filters](/api/liquid/filters) on expressions inside `echo` tags.
-  # @liquid_syntax
-  #   {% liquid
-  #     echo expression
-  #   %}
-  # @liquid_syntax_keyword expression The expression to be output.
   class Echo < Tag
     attr_reader :variable
 

lib/liquid/tags/for.rb

@@ -1,29 +1,50 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category iteration
-  # @liquid_name for
-  # @liquid_summary
-  #   Renders an expression for every item in an array.
-  # @liquid_description
-  #   You can do a maximum of 50 iterations with a `for` loop. If you need to iterate over more than 50 items, then use the
-  #   [`paginate` tag](/api/liquid/tags#paginate) to split the items over multiple pages.
+  # "For" iterates over an array or collection.
+  # Several useful variables are available to you within the loop.
+  #
+  # == Basic usage:
+  #    {% for item in collection %}
+  #      {{ forloop.index }}: {{ item.name }}
+  #    {% endfor %}
+  #
+  # == Advanced usage:
+  #    {% for item in collection %}
+  #      <div {% if forloop.first %}class="first"{% endif %}>
+  #        Item {{ forloop.index }}: {{ item.name }}
+  #      </div>
+  #    {% else %}
+  #      There is nothing in the collection.
+  #    {% endfor %}
+  #
+  # You can also define a limit and offset much like SQL.  Remember
+  # that offset starts at 0 for the first item.
+  #
+  #    {% for item in collection limit:5 offset:10 %}
+  #      {{ item.name }}
+  #    {% end %}
+  #
+  #  To reverse the for loop simply use {% for item in collection reversed %} (note that the flag's spelling is different to the filter `reverse`)
+  #
+  # == Available variables:
+  #
+  # forloop.name:: 'item-collection'
+  # forloop.length:: Length of the loop
+  # forloop.index:: The current item's position in the collection;
+  #                 forloop.index starts at 1.
+  #                 This is helpful for non-programmers who start believe
+  #                 the first item in an array is 1, not 0.
+  # forloop.index0:: The current item's position in the collection
+  #                  where the first item is 0
+  # forloop.rindex:: Number of items remaining in the loop
+  #                  (length - index) where 1 is the last item.
+  # forloop.rindex0:: Number of items remaining in the loop
+  #                   where 0 is the last item.
+  # forloop.first:: Returns true if the item is the first item.
+  # forloop.last:: Returns true if the item is the last item.
+  # forloop.parentloop:: Provides access to the parent loop, if present.
   #
-  #   > Tip:
-  #   > Every `for` loop has an associated [`forloop` object](/api/liquid/objects#forloop) with information about the loop.
-  # @liquid_syntax
-  #   {% for variable in array %}
-  #     expression
-  #   {% endfor %}
-  # @liquid_syntax_keyword variable The current item in the array.
-  # @liquid_syntax_keyword array The array to iterate over.
-  # @liquid_syntax_keyword expression The expression to render for each iteration.
-  # @liquid_optional_param limit [number] The number of iterations to perform.
-  # @liquid_optional_param offset [number] The 1-based index to start iterating at.
-  # @liquid_optional_param range [untyped] A custom numeric range to iterate over.
-  # @liquid_optional_param reversed [untyped] Iterate in reverse order.
   class For < Block
     Syntax = /\A(#{VariableSegment}+)\s+in\s+(#{QuotedFragment}+)\s*(reversed)?/o
 

lib/liquid/tags/if.rb

@@ -1,18 +1,16 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category conditional
-  # @liquid_name if
-  # @liquid_summary
-  #   Renders an expression if a specific condition is `true`.
-  # @liquid_syntax
-  #   {% if condition %}
-  #     expression
+  # If is the conditional block
+  #
+  #   {% if user.admin %}
+  #     Admin user!
+  #   {% else %}
+  #     Not admin user
   #   {% endif %}
-  # @liquid_syntax_keyword condition The condition to evaluate.
-  # @liquid_syntax_keyword expression The expression to render if the condition is met.
+  #
+  #    There are {% if count < 5 %} less {% else %} more {% endif %} items than you need.
+  #
   class If < Block
     Syntax                  = /(#{QuotedFragment})\s*([=!<>a-z_]+)?\s*(#{QuotedFragment})?/o
     ExpressionsAndOperators = /(?:\b(?:\s?and\s?|\s?or\s?)\b|(?:\s*(?!\b(?:\s?and\s?|\s?or\s?)\b)(?:#{QuotedFragment}|\S+)\s*)+)/o

lib/liquid/tags/include.rb

@@ -1,22 +1,20 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category theme
-  # @liquid_name include
-  # @liquid_summary
-  #   Renders a [snippet](/themes/architecture#snippets).
-  # @liquid_description
-  #   Inside the snippet, you can access and alter variables that are [created](/api/liquid/tags#variable-tags) outside of the
-  #   snippet.
-  # @liquid_syntax
-  #   {% include 'filename' %}
-  # @liquid_syntax_keyword filename The name of the snippet to render, without the `.liquid` extension.
-  # @liquid_deprecated
-  #   Deprecated because the way that variables are handled reduces performance and makes code harder to both read and maintain.
+  # Include allows templates to relate with other templates
+  #
+  # Simply include another template:
+  #
+  #   {% include 'product' %}
+  #
+  # Include a template with a local variable:
+  #
+  #   {% include 'product' with products[0] %}
+  #
+  # Include a template for a collection:
+  #
+  #   {% include 'product' for products %}
   #
-  #   The `include` tag has been replaced by [`render`](/api/liquid/tags#render).
   class Include < Tag
     prepend Tag::Disableable
 

lib/liquid/tags/increment.rb

@@ -1,23 +1,21 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category variable
-  # @liquid_name increment
-  # @liquid_summary
-  #   Creates a new variable, with a default value of 0, that's increased by 1 with each subsequent call.
-  # @liquid_description
-  #   Variables that are declared with `increment` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
-  #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across
-  #   [snippets](/themes/architecture#snippets) included in the file.
+  # increment is used in a place where one needs to insert a counter
+  #     into a template, and needs the counter to survive across
+  #     multiple instantiations of the template.
+  #     (To achieve the survival, the application must keep the context)
+  #
+  #     if the variable does not exist, it is created with value 0.
+  #
+  #   Hello: {% increment variable %}
+  #
+  # gives you:
+  #
+  #    Hello: 0
+  #    Hello: 1
+  #    Hello: 2
   #
-  #   Similarly, variables that are created with `increment` are independent from those created with [`assign`](/api/liquid/tags#assign)
-  #   and [`capture`](/api/liquid/tags#capture). However, `increment` and [`decrement`](/api/liquid/tags#decrement) share
-  #   variables.
-  # @liquid_syntax
-  #   {% increment variable_name %}
-  # @liquid_syntax_keyword variable_name The name of the variable being incremented.
   class Increment < Tag
     def initialize(tag_name, markup, options)
       super

lib/liquid/tags/inline_comment.rb

@@ -1,19 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category syntax
-  # @liquid_name inline_comment
-  # @liquid_summary
-  #   Prevents an expression from being rendered or output.
-  # @liquid_description
-  #   Any text inside an `inline_comment` tag won't be rendered or output.
-  #
-  #   You can create multi-line inline comments. However, each line must begin with a `#`.
-  # @liquid_syntax
-  #   {% # content %}
-  # @liquid_syntax_keyword content The content of the comment.
   class InlineComment < Tag
     def initialize(tag_name, markup, options)
       super

lib/liquid/tags/raw.rb

@@ -1,17 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category syntax
-  # @liquid_name raw
-  # @liquid_summary
-  #   Outputs any Liquid code as text instead of rendering it.
-  # @liquid_syntax
-  #   {% raw %}
-  #     expression
-  #   {% endraw %}
-  # @liquid_syntax_keyword expression The expression to be output without being rendered.
   class Raw < Block
     Syntax = /\A\s*\z/
     FullTokenPossiblyInvalid = /\A(.*)#{TagStart}\s*(\w+)\s*(.*)?#{TagEnd}\z/om

lib/liquid/tags/render.rb

@@ -1,37 +1,13 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category theme
-  # @liquid_name render
-  # @liquid_summary
-  #   Renders a [snippet](/themes/architecture#snippets) or [app block](/themes/architecture/sections/section-schema#render-app-blocks).
-  # @liquid_description
-  #   Inside snippets and app blocks, you can't directly access variables that are [created](/api/liquid/tags#variable-tags) outside
-  #   of the snippet or app block. However, you can [specify variables as parameters](/api/liquid/tags#render-passing-variables-to-snippets)
-  #   to pass outside variables to snippets.
-  #
-  #   While you can't directly access created variables, you can access global objects, as well as any objects that are
-  #   directly accessible outside the snippet or app block. For example, a snippet or app block inside the [product template](/themes/architecture/templates/product)
-  #   can access the [`product` object](/api/liquid/objects#product), and a snippet or app block inside a [section](/themes/architecture/sections)
-  #   can access the [`section` object](/api/liquid/objects#section).
-  #
-  #   Outside a snippet or app block, you can't access variables created inside the snippet or app block.
-  #
-  #   > Note:
-  #   > When you render a snippet using the `render` tag, you can't use the [`include` tag](/api/liquid/tags#include)
-  #   > inside the snippet.
-  # @liquid_syntax
-  #   {% render 'filename' %}
-  # @liquid_syntax_keyword filename The name of the snippet to render, without the `.liquid` extension.
   class Render < Tag
     FOR = 'for'
     SYNTAX = /(#{QuotedString}+)(\s+(with|#{FOR})\s+(#{QuotedFragment}+))?(\s+(?:as)\s+(#{VariableSegment}+))?/o
 
     disable_tags "include"
 
-    attr_reader :template_name_expr, :variable_name_expr, :attributes
+    attr_reader :template_name_expr, :attributes
 
     def initialize(tag_name, markup, options)
       super
@@ -99,7 +75,6 @@ module Liquid
       def children
         [
           @node.template_name_expr,
-          @node.variable_name_expr,
         ] + @node.attributes.values
       end
     end

lib/liquid/tags/table_row.rb

@@ -1,28 +1,6 @@
 # frozen_string_literal: true
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category iteration
-  # @liquid_name tablerow
-  # @liquid_summary
-  #   Generates HTML table rows for every item in an array.
-  # @liquid_description
-  #   The `tablerow` tag must be wrapped in HTML `<table>` and `</table>` tags.
-  #
-  #   > Tip:
-  #   > Every `tablerow` loop has an associated [`tablerowloop` object](/api/liquid/objects#tablerowloop) with information about the loop.
-  # @liquid_syntax
-  #   {% tablerow variable in array %}
-  #     expression
-  #   {% endtablerow %}
-  # @liquid_syntax_keyword variable The current item in the array.
-  # @liquid_syntax_keyword array The array to iterate over.
-  # @liquid_syntax_keyword expression The expression to render.
-  # @liquid_optional_param cols [number] The number of columns that the table should have.
-  # @liquid_optional_param limit [number] The number of iterations to perform.
-  # @liquid_optional_param offset [number] The 1-based index to start iterating at.
-  # @liquid_optional_param range [untyped] A custom numeric range to iterate over.
   class TableRow < Block
     Syntax = /(\w+)\s+in\s+(#{QuotedFragment}+)/o
 

lib/liquid/tags/unless.rb

@@ -3,21 +3,10 @@
 require_relative 'if'
 
 module Liquid
-  # @liquid_public_docs
-  # @liquid_type tag
-  # @liquid_category conditional
-  # @liquid_name unless
-  # @liquid_summary
-  #   Renders an expression unless a specific condition is `true`.
-  # @liquid_description
-  #   > Tip:
-  #   > Similar to the [`if` tag](/api/liquid/tags#if), you can use `elsif` to add more conditions to an `unless` tag.
-  # @liquid_syntax
-  #   {% unless condition %}
-  #     expression
-  #   {% endunless %}
-  # @liquid_syntax_keyword condition The condition to evaluate.
-  # @liquid_syntax_keyword expression The expression to render unless the condition is met.
+  # Unless is a conditional just like 'if' but works on the inverse logic.
+  #
+  #   {% unless x < 0 %} x is greater than zero {% endunless %}
+  #
   class Unless < If
     def render_to_output_buffer(context, output)
       # First condition is interpreted backwards ( if not )

lib/liquid/variable.rb

@@ -47,7 +47,7 @@ module Liquid
 
       name_markup   = Regexp.last_match(1)
       filter_markup = Regexp.last_match(2)
-      @name         = parse_context.parse_expression(name_markup)
+      @name         = Expression.parse(name_markup)
       if filter_markup =~ FilterMarkupRegex
         filters = Regexp.last_match(1).scan(FilterParser)
         filters.each do |f|
@@ -65,7 +65,7 @@ module Liquid
 
       return if p.look(:end_of_string)
 
-      @name = parse_context.parse_expression(p.expression)
+      @name = Expression.parse(p.expression)
       while p.consume?(:pipe)
         filtername = p.consume(:id)
         filterargs = p.consume?(:colon) ? parse_filterargs(p) : []
@@ -122,9 +122,9 @@ module Liquid
       unparsed_args.each do |a|
         if (matches = a.match(JustTagAttributes))
           keyword_args           ||= {}
-          keyword_args[matches[1]] = parse_context.parse_expression(matches[2])
+          keyword_args[matches[1]] = Expression.parse(matches[2])
         else
-          filter_args << parse_context.parse_expression(a)
+          filter_args << Expression.parse(a)
         end
       end
       result = [filter_name, filter_args]

lib/liquid/variable_lookup.rb

@@ -32,10 +32,6 @@ module Liquid
       end
     end
 
-    def lookup_command?(lookup_index)
-      @command_flags & (1 << lookup_index) != 0
-    end
-
     def evaluate(context)
       name   = context.evaluate(@name)
       object = context.find_variable(name)
@@ -59,7 +55,7 @@ module Liquid
           # Some special cases. If the part wasn't in square brackets and
           # no key with the same name was found we interpret following calls
           # as commands and call them on the current object
-        elsif lookup_command?(i) && object.respond_to?(key)
+        elsif @command_flags & (1 << i) != 0 && object.respond_to?(key)
           object = object.send(key).to_liquid
 
           # No key was present with the desired value and it wasn't one of the directly supported

liquid.gemspec

@@ -22,7 +22,8 @@ Gem::Specification.new do |s|
 
   s.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  s.files = Dir.glob("{lib}/**/*") + %w(LICENSE README.md)
+  s.test_files  = Dir.glob("{test}/**/*")
+  s.files       = Dir.glob("{lib}/**/*") + %w(LICENSE README.md)
 
   s.extra_rdoc_files = ["History.md", "README.md"]
 

test/integration/context_test.rb

@@ -529,7 +529,7 @@ class ContextTest < Minitest::Test
     registers = {
       my_register: :my_value,
     }
-    super_context = Context.new({}, {}, Registers.new(registers))
+    super_context = Context.new({}, {}, StaticRegisters.new(registers))
     super_context.registers[:my_register] = :my_alt_value
     subcontext                            = super_context.new_isolated_subcontext
     assert_equal(:my_value, subcontext.registers[:my_register])
@@ -623,12 +623,12 @@ class ContextTest < Minitest::Test
       my_register: :my_value,
     }
     c = Context.new({}, {}, registers)
-    assert_instance_of(Registers, c.registers)
+    assert_instance_of(StaticRegisters, c.registers)
     assert_equal(:my_value, c.registers[:my_register])
 
-    r = Registers.new(registers)
+    r = StaticRegisters.new(registers)
     c = Context.new({}, {}, r)
-    assert_instance_of(Registers, c.registers)
+    assert_instance_of(StaticRegisters, c.registers)
     assert_equal(:my_value, c.registers[:my_register])
   end
 

test/unit/parse_tree_visitor_test.rb

@@ -236,20 +236,6 @@ class ParseTreeVisitorTest < Minitest::Test
     )
   end
 
-  def test_render_with
-    assert_equal(
-      ["test"],
-      visit(%({% render "hai" with test %}))
-    )
-  end
-
-  def test_render_for
-    assert_equal(
-      ["test"],
-      visit(%({% render "hai" for test %}))
-    )
-  end
-
   def test_preserve_tree_structure
     assert_equal(
       [[nil, [

test/unit/partial_cache_unit_test.rb

@@ -132,7 +132,7 @@ class PartialCacheUnitTest < Minitest::Test
       'my_partial' => 'my shared value'
     )
     context = Liquid::Context.build(
-      registers: Liquid::Registers.new(
+      registers: Liquid::StaticRegisters.new(
         file_system: shared_file_system,
       )
     )

test/unit/static_registers_unit_test.rb

@@ -2,11 +2,11 @@
 
 require 'test_helper'
 
-class RegistersUnitTest < Minitest::Test
+class StaticRegistersUnitTest < Minitest::Test
   include Liquid
 
   def test_set
-    static_register = Registers.new(a: 1, b: 2)
+    static_register = StaticRegisters.new(a: 1, b: 2)
     static_register[:b] = 22
     static_register[:c] = 33
 
@@ -16,13 +16,13 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_get_missing_key
-    static_register = Registers.new
+    static_register = StaticRegisters.new
 
     assert_nil(static_register[:missing])
   end
 
   def test_delete
-    static_register = Registers.new(a: 1, b: 2)
+    static_register = StaticRegisters.new(a: 1, b: 2)
     static_register[:b] = 22
     static_register[:c] = 33
 
@@ -37,7 +37,7 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_fetch
-    static_register = Registers.new(a: 1, b: 2)
+    static_register = StaticRegisters.new(a: 1, b: 2)
     static_register[:b] = 22
     static_register[:c] = 33
 
@@ -61,7 +61,7 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_key
-    static_register = Registers.new(a: 1, b: 2)
+    static_register = StaticRegisters.new(a: 1, b: 2)
     static_register[:b] = 22
     static_register[:c] = 33
 
@@ -72,7 +72,7 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_static_register_can_be_frozen
-    static_register = Registers.new(a: 1)
+    static_register = StaticRegisters.new(a: 1)
 
     static_register.static.freeze
 
@@ -94,14 +94,14 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_new_static_retains_static
-    static_register = Registers.new(a: 1, b: 2)
+    static_register = StaticRegisters.new(a: 1, b: 2)
     static_register[:b] = 22
     static_register[:c] = 33
 
-    new_static_register = Registers.new(static_register)
+    new_static_register = StaticRegisters.new(static_register)
     new_static_register[:b] = 222
 
-    newest_static_register = Registers.new(new_static_register)
+    newest_static_register = StaticRegisters.new(new_static_register)
     newest_static_register[:c] = 333
 
     assert_equal(1, static_register[:a])
@@ -118,11 +118,11 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_multiple_instances_are_unique
-    static_register_1 = Registers.new(a: 1, b: 2)
+    static_register_1 = StaticRegisters.new(a: 1, b: 2)
     static_register_1[:b] = 22
     static_register_1[:c] = 33
 
-    static_register_2 = Registers.new(a: 10, b: 20)
+    static_register_2 = StaticRegisters.new(a: 10, b: 20)
     static_register_2[:b] = 220
     static_register_2[:c] = 330
 
@@ -138,11 +138,11 @@ class RegistersUnitTest < Minitest::Test
   end
 
   def test_initialization_reused_static_same_memory_object
-    static_register_1 = Registers.new(a: 1, b: 2)
+    static_register_1 = StaticRegisters.new(a: 1, b: 2)
     static_register_1[:b] = 22
     static_register_1[:c] = 33
 
-    static_register_2 = Registers.new(static_register_1)
+    static_register_2 = StaticRegisters.new(static_register_1)
 
     assert_equal(1, static_register_2[:a])
     assert_equal(2, static_register_2[:b])