herb 0.10.4 → 0.11.0

data/lib/herb/engine/slots/state_kinds.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/engine/slots/state_kinds.rb.erb
+
+module Herb
+  class Engine
+    module Slots
+      # The kinds a `herb:state` default can have, and what each one means to the compiler.
+      #
+      module StateKinds
+        PRISM = {
+          "Prism::TrueNode" => :boolean,
+          "Prism::FalseNode" => :boolean,
+          "Prism::IntegerNode" => :integer,
+          "Prism::StringNode" => :string,
+          "Prism::SymbolNode" => :symbol,
+          "Prism::NilNode" => :nil,
+        }.freeze #: Hash[String, Symbol]
+
+        NODE = {
+          "boolean" => :boolean,
+          "integer" => :integer,
+          "string" => :string,
+          "symbol" => :symbol,
+          "nil" => :nil,
+        }.freeze #: Hash[String, Symbol]
+
+        LITERAL = [:boolean, :integer, :string, :symbol, :nil].freeze #: Array[Symbol]
+
+        UNKNOWN = [:bare, :seeded].freeze #: Array[Symbol]
+
+        FALSY = [:boolean, :nil, :seeded].freeze #: Array[Symbol]
+
+        NILABLE = [:nil, :seeded].freeze #: Array[Symbol]
+
+        ARTICLES = {
+          "boolean" => "a Boolean",
+          "integer" => "an Integer",
+          "float" => "a Float",
+          "string" => "a String",
+          "symbol" => "a Symbol",
+          "nil" => "a Nil",
+          "array" => "an Array",
+          "hash" => "a Hash",
+          "bare" => "a value",
+          "seeded" => "a value",
+          "missing" => "a value",
+        }.freeze #: Hash[String, String]
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/state_operators.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/engine/slots/state_operators.rb.erb
+
+module Herb
+  class Engine
+    module Slots
+      # The comparison operators a `herb:state` read may use, and what swapping or negating one
+      # turns it into.
+      #
+      module StateOperators
+        MIRRORED = {
+          ">" => "<",
+          ">=" => "<=",
+          "<" => ">",
+          "<=" => ">=",
+        }.freeze #: Hash[String, String]
+
+        NEGATED = {
+          "==" => "!=",
+          "!=" => "==",
+          ">" => "<=",
+          ">=" => "<",
+          "<" => ">=",
+          "<=" => ">",
+        }.freeze #: Hash[String, String]
+
+        ORDERED = [:>, :>=, :<, :<=].freeze #: Array[Symbol]
+
+        COMPARISONS = ["==", "!=", ">", ">=", "<", "<="].freeze #: Array[String]
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/state_overrides.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "bindings"
+
+module Herb
+  class Engine
+    module Slots
+      # Resolves the state values a client sent along with a values request.
+      #
+      # The values program evaluates the branch the state picks, so a client that wants the
+      # values for its own branches sends its state and the program initializes each declared
+      # state from it. A host makes that possible by answering `__herb_state_overrides` in the
+      # render context with a hash keyed by template identifier. Everything here degrades to
+      # the compiled defaults, since a missing, malformed or wrongly typed override must never
+      # break a render the defaults could serve.
+      #
+      # A render call that binds or seeds the template's states pushes a `Bindings` frame, and
+      # the frame layers with the client's values. A seed sits under them, since a client that
+      # has written the state since it was seeded knows better. A binding sits over them, since
+      # the client cannot tell two render sites of one partial apart.
+      #
+      module StateOverrides
+        HOOK = "__herb_state_overrides" #: String
+
+        #: (untyped, String) -> Hash[String, untyped]?
+        def self.resolve(raw, identifier)
+          frame = Bindings.current(identifier)
+          sent = raw.is_a?(Hash) ? raw[identifier] : nil
+
+          return nil if frame.nil? && !sent.is_a?(Hash)
+
+          layered = {} #: Hash[String, untyped]
+
+          layered.merge!(frame.fetch(:seeded)) if frame
+          layered.merge!(sent) if sent.is_a?(Hash)
+          layered.merge!(frame.fetch(:bound)) if frame
+
+          layered
+        end
+
+        #: (Hash[String, untyped]?, String, Symbol) { () -> untyped } -> untyped
+        def self.fetch(overrides, name, kind)
+          return yield if overrides.nil? || !overrides.key?(name)
+
+          coerced = coerce(overrides[name], kind)
+
+          coerced == :__herb_uncoercible ? yield : coerced
+        end
+
+        #: (untyped, Symbol) -> untyped
+        def self.coerce(value, kind)
+          return :__herb_uncoercible unless value.nil? || value.is_a?(String) || value.is_a?(Integer) || value.is_a?(Float) || value == true || value == false
+
+          case kind
+          when :boolean
+            return value if [true, false].include?(value)
+            return value == "true" if ["true", "false"].include?(value)
+
+            :__herb_uncoercible
+          when :integer
+            return value if value.is_a?(Integer)
+            return value.to_i if value.is_a?(String) && value.strip.match?(/\A-?\d+\z/)
+
+            :__herb_uncoercible
+          when :string, :symbol
+            return :__herb_uncoercible if value.nil?
+
+            string = value.is_a?(String) ? value : value.to_s
+
+            kind == :symbol ? string.to_sym : string
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/state_predicates.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/engine/slots/state_predicates.rb.erb
+
+module Herb
+  class Engine
+    module Slots
+      # The Ruby predicates a `herb:state` read may use, and the condition each one resolves into.
+      #
+      module StatePredicates
+        TABLE = {
+          "nil?" => {
+            comparand: "nil",
+            kinds: nil,
+            only: "every state",
+          },
+          "zero?" => {
+            comparand: "0",
+            kinds: [:integer],
+            only: "an Integer state",
+          },
+          "one?" => {
+            comparand: "1",
+            kinds: [:integer],
+            only: "an Integer state",
+            rewrite: "== 1",
+          },
+          "positive?" => {
+            comparand: "0",
+            operator: ">",
+            kinds: [:integer],
+            only: "an Integer state",
+          },
+          "empty?" => {
+            comparand: "\"\"",
+            kinds: [:string, :symbol],
+            only: "a String or a Symbol state",
+          },
+          "blank?" => {
+            operator: "blank",
+            kinds: [:boolean, :string, :nil],
+            only: "a Boolean, a String or a Nil state",
+          },
+          "present?" => {
+            operator: "present",
+            kinds: [:boolean, :string, :nil],
+            only: "a Boolean, a String or a Nil state",
+          },
+        }.freeze #: Hash[String, Hash[Symbol, untyped]]
+
+        NEGATED = {
+          "blank" => "present",
+          "present" => "blank",
+        }.freeze #: Hash[String, String]
+
+        UNARY = {
+          "blank" => "blank?",
+          "present" => "present?",
+        }.freeze #: Hash[String, String]
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/state_transforms.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/engine/slots/state_transforms.rb.erb
+
+module Herb
+  class Engine
+    module Slots
+      # The Ruby methods a `herb:state` read may call to transform a state's value before comparing
+      # it, and the operation each one becomes on the wire.
+      #
+      module StateTransforms
+        TABLE = {
+          "length" => {
+            operation: "length",
+            kinds: [:string, :symbol],
+            returns: :integer,
+            only: "a String or a Symbol state",
+          },
+          "size" => {
+            operation: "length",
+            kinds: [:string, :symbol],
+            returns: :integer,
+            only: "a String or a Symbol state",
+          },
+          "to_s" => {
+            operation: "to_s",
+            kinds: nil,
+            returns: :string,
+            only: "every state",
+          },
+        }.freeze #: Hash[String, Hash[Symbol, untyped]]
+
+        SPELLINGS = {
+          "length" => "length",
+          "to_s" => "to_s",
+        }.freeze #: Hash[String, String]
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/statics.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "annotation"
+
+module Herb
+  class Engine
+    module Slots
+      # Prints the markup a branch would render, with everything dynamic left out.
+      #
+      # It runs over a branch body after `Visitor` has marked it, so what comes out is the
+      # branch's static HTML with an empty marker pair everywhere a slot would go. That is what a
+      # client needs to build the branch itself: the parts that never change, and the positions of
+      # the parts that do.
+      #
+      # A node that is itself a slot prints as nothing, because its markers were inserted around
+      # it and stay. A conditional nested inside a branch is a slot, so it prints as its empty pair
+      # and parks its own branches separately, rather than having all of its alternatives written
+      # out inside its parent's.
+      #
+      # Anything it does not recognise raises. Parking nothing for a branch leaves it server
+      # rendered, which is correct but slower. Parking markup that is missing a piece would render
+      # the branch wrong, which is not recoverable.
+      #
+      class Statics
+        class Unprintable < StandardError
+        end
+
+        SKIPPED_PREFIXES = ["AST_ERB_", "AST_RUBY_", "AST_HERB_"].freeze #: Array[String]
+
+        #: (Hash[untyped, Annotation], ?Hash[untyped, Array[Annotation]]) -> void
+        def initialize(standing, anchored = {})
+          @standing = standing
+          @anchored = anchored
+          @out = +"" #: String
+          @signature = false
+          @found = [] #: Array[Annotation]
+        end
+
+        #: (Array[untyped]) -> String?
+        def markup(nodes)
+          @signature = false
+
+          run(nodes)
+        end
+
+        #: (Array[untyped]) -> [String, Array[Annotation]]?
+        def signature(nodes)
+          @signature = true
+
+          shape = run(nodes)
+
+          shape ? [shape, @found] : nil
+        end
+
+        private
+
+        #: (Array[untyped]) -> String?
+        def run(nodes)
+          @out = +""
+          @found = [] #: Array[Annotation]
+
+          write_all(nodes)
+
+          @out
+        rescue Unprintable
+          nil
+        end
+
+        #: (untyped) -> void
+        def write(node)
+          standing = @standing[node]
+
+          return write_placeholder(standing) if standing
+
+          return if !node.is_a?(Herb::AST::ERBOpenTagNode) && SKIPPED_PREFIXES.any? { |prefix| node.type.to_s.start_with?(prefix) }
+
+          case node
+          when Herb::AST::HTMLTextNode, Herb::AST::LiteralNode
+            emit(node.content)
+          when Herb::AST::WhitespaceNode
+            separate(node.value&.value)
+          when Herb::AST::HTMLElementNode
+            write(node.open_tag)
+            write_all(node.body)
+            write(node.close_tag) if node.close_tag
+          when Herb::AST::ERBOpenTagNode
+            raise Unprintable unless node.tag_name
+
+            emit("<")
+            emit(node.tag_name.value)
+
+            @anchored[node]&.each { |annotation| write_placeholder(annotation) }
+
+            write_all(node.children)
+            emit(">")
+          when Herb::AST::HTMLOpenTagNode
+            emit(node.tag_opening&.value || "<")
+            emit(node.tag_name&.value)
+
+            @anchored[node]&.each { |annotation| write_placeholder(annotation) }
+
+            write_all(node.children)
+            emit(node.tag_closing&.value || ">")
+          when Herb::AST::HTMLCloseTagNode
+            emit(node.tag_opening&.value)
+            emit(node.tag_name&.value)
+            emit(node.tag_closing&.value)
+          when Herb::AST::HTMLVirtualCloseTagNode
+            emit("</#{node.tag_name.value}>") if node.tag_name
+          when Herb::AST::HTMLOmittedCloseTagNode
+            nil
+          when Herb::AST::HTMLAttributeNode
+            write_attribute(node)
+          when Herb::AST::HTMLAttributeNameNode
+            write_all(node.children)
+          when Herb::AST::HTMLAttributeValueNode
+            write_attribute_value(node)
+          when Herb::AST::HTMLCommentNode
+            write_wrapped(node.comment_start, node.children, node.comment_end)
+          when Herb::AST::HTMLDoctypeNode, Herb::AST::XMLDeclarationNode, Herb::AST::CDATANode
+            write_wrapped(node.tag_opening, node.children, node.tag_closing)
+          else
+            raise Unprintable
+          end
+        end
+
+        #: (Annotation) -> void
+        def write_placeholder(annotation)
+          return unless @signature
+
+          @found << annotation
+
+          emit("\u0000#{annotation.type}\u0000")
+        end
+
+        #: (untyped) -> void
+        def write_all(nodes)
+          return unless nodes.is_a?(Array)
+
+          nodes.each { |node| write(node) }
+        end
+
+        #: (untyped, untyped, untyped) -> void
+        def write_wrapped(opening, children, closing)
+          emit(opening&.value)
+          write_all(children)
+          emit(closing&.value)
+        end
+
+        #: (untyped) -> void
+        def write_attribute(node)
+          separate(" ")
+          write(node.name)
+
+          return unless node.value
+
+          emit(node.equals&.value&.include?("=") ? node.equals.value : "=")
+          write(node.value)
+        end
+
+        #: (untyped) -> void
+        def write_attribute_value(node)
+          return write_all(node.children) unless node.quoted
+
+          emit(node.open_quote&.value || '"')
+          write_all(node.children)
+          emit(node.close_quote&.value || '"')
+        end
+
+        #: (untyped) -> void
+        def emit(text)
+          @out << text.to_s
+        end
+
+        #: (untyped) -> void
+        def separate(text)
+          return if @out.empty? || @out.end_with?(" ", "\t", "\n", "\r")
+
+          @out << text.to_s
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/subtree.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# typed: false
+
+require_relative "../../../herb"
+require_relative "../../engine"
+require_relative "visitor"
+require_relative "subtree_compiler"
+
+module Herb
+  class Engine
+    module Slots
+      # Compiles the markup behind one slot, for the cases a client cannot answer for itself.
+      #
+      #     subtree = Herb::Engine::Slots::Subtree.new(source, filename: "app/views/posts/index.html.erb")
+      #     view.instance_eval(subtree.source_for(0))
+      #     #=> "<li>one</li><li>two</li>"
+      #
+      # Values carry a page most of the way. What they cannot carry is markup the page never had:
+      # a conditional taking a branch that did not render, or a collection gaining its first item.
+      # Both come back from `SlotIndex#apply` as a deferred entry naming the slot, and this is what
+      # answers one.
+      #
+      # A slot is addressed by its index, which is what the payload and the deferred entry both use.
+      # `Visitor` records the `node_path` of each slot and `SubtreeCompiler` renders the node at
+      # a path, so the index is resolved through the schema.
+      #
+      # An attribute is not addressable. A path indexes an element's body and does not descend into
+      # its open tag, so the path of an attribute slot names the element holding it, and compiling
+      # that would return the whole element where the caller asked for one attribute. Those slots
+      # are values, and values is how they come back.
+      #
+      class Subtree
+        attr_reader :slots, :version #: Array[untyped]
+
+        #: (String, ?filename: String?) -> void
+        def initialize(source, filename: nil)
+          @source = source
+          @filename = filename
+
+          visitor = Herb::Engine::Slots::Visitor.new
+
+          Herb::Engine.new(source, visitors: [visitor], filename: filename)
+
+          @slots = visitor.slots
+          @version = visitor.version
+        end #: String
+
+        #: (Integer) -> Array[Integer]?
+        def node_path_for(index)
+          slot_for(index)&.node_path
+        end
+
+        #: (Integer) -> bool
+        def addressable?(index)
+          slot = slot_for(index)
+
+          return false unless slot
+
+          !slot.attribute?
+        end
+
+        #: (Integer) -> String?
+        def source_for(index)
+          return nil unless addressable?(index)
+
+          path = node_path_for(index)
+
+          return nil unless path
+
+          Herb::Engine::Slots::SubtreeCompiler.new(@source, node_path: path, filename: @filename).src
+        end
+
+        private
+
+        #: (Integer) -> untyped
+        def slot_for(index)
+          @slots.find { |slot| slot.index == index }
+        end
+      end
+    end
+  end
+end