herb 0.10.4 → 0.11.0

data/sig/herb/engine/slots/statics.rbs

@@ -0,0 +1,67 @@
+# Generated from lib/herb/engine/slots/statics.rb with RBS::Inline
+
+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: Array[String]
+
+        # : (Hash[untyped, Annotation], ?Hash[untyped, Array[Annotation]]) -> void
+        def initialize: (Hash[untyped, Annotation], ?Hash[untyped, Array[Annotation]]) -> void
+
+        # : (Array[untyped]) -> String?
+        def markup: (Array[untyped]) -> String?
+
+        # : (Array[untyped]) -> [String, Array[Annotation]]?
+        def signature: (Array[untyped]) -> [ String, Array[Annotation] ]?
+
+        private
+
+        # : (Array[untyped]) -> String?
+        def run: (Array[untyped]) -> String?
+
+        # : (untyped) -> void
+        def write: (untyped) -> void
+
+        # : (Annotation) -> void
+        def write_placeholder: (Annotation) -> void
+
+        # : (untyped) -> void
+        def write_all: (untyped) -> void
+
+        # : (untyped, untyped, untyped) -> void
+        def write_wrapped: (untyped, untyped, untyped) -> void
+
+        # : (untyped) -> void
+        def write_attribute: (untyped) -> void
+
+        # : (untyped) -> void
+        def write_attribute_value: (untyped) -> void
+
+        # : (untyped) -> void
+        def emit: (untyped) -> void
+
+        # : (untyped) -> void
+        def separate: (untyped) -> void
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/subtree.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/herb/engine/slots/subtree.rb with RBS::Inline
+
+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: Array[untyped]
+
+        attr_reader version: Array[untyped]
+
+        # : (String, ?filename: String?) -> void
+        def initialize: (String, ?filename: String?) -> void
+
+        # : (Integer) -> Array[Integer]?
+        def node_path_for: (Integer) -> Array[Integer]?
+
+        # : (Integer) -> bool
+        def addressable?: (Integer) -> bool
+
+        # : (Integer) -> String?
+        def source_for: (Integer) -> String?
+
+        private
+
+        # : (Integer) -> untyped
+        def slot_for: (Integer) -> untyped
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/subtree_compiler.rbs

@@ -0,0 +1,130 @@
+# Generated from lib/herb/engine/slots/subtree_compiler.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # Compiles a template into Ruby that renders one part of it rather than all of it.
+      #
+      # Re-rendering a region means running the template again and keeping only the piece that
+      # changed. The piece cannot be compiled on its own, because what it renders depends on
+      # everything the template did before reaching it:
+      #
+      #     require "herb/engine/slots/subtree_compiler"
+      #
+      #     source = Herb::Engine::Slots::SubtreeCompiler.new(template, node_path: [0, 1]).src
+      #     view.instance_eval(source)
+      #     #=> "<ul><li>Marco</li></ul>"
+      #
+      # ## Everything runs, only the target is kept
+      #
+      # A local assigned earlier, a helper called for its side effect, the loop the target sits
+      # inside: all of it has to run for the target to render the same as it would have. So nothing
+      # is skipped. What changes is where the output goes.
+      #
+      # The engine writes every append through one buffer variable, so the target's output is
+      # collected by pointing that variable at the buffer being returned while the target renders and
+      # at a sink the rest of the time. Escaping, blocks, and control flow then need no special
+      # handling, because none of them know which buffer they are writing to.
+      #
+      # Pruning the work that only fed discarded output is a separate question, and answering it
+      # needs to know which expressions the target actually depends on. Running everything is the
+      # answer that is correct without that analysis.
+      #
+      # ## Addressing
+      #
+      # The target is named by `node_path`, the same path `Visitor` records for a slot and
+      # `Herb::ActionView::TemplateDependencies` reports for a node, so a caller that has one from
+      # either has one that works here.
+      #
+      # The path indexes a document's children, an element's body, and the bodies of the ERB nodes
+      # that branch or repeat. It does not descend into an open tag, so an attribute is not
+      # addressable, and the body of an `else` or a `when` is indexed as part of the node it hangs
+      # off rather than on its own. Both match `Visitor`, and both are worth changing in the two
+      # places at once rather than in either alone.
+      class SubtreeCompiler < Herb::Engine
+        BUFFER: String
+
+        SINK: String
+
+        INDEXED_PROPERTIES: Array[Symbol]
+
+        class TargetNotFound < Herb::Engine::CompilationError
+          # : (Array[Integer]) -> void
+          def initialize: (Array[Integer]) -> void
+        end
+
+        class Compiler < Herb::Engine::Compiler
+          # : (untyped, ?Hash[Symbol, untyped]) -> void
+          def initialize: (untyped, ?Hash[Symbol, untyped]) -> void
+
+          # : () -> bool
+          def found?: () -> bool
+
+          # : (untyped) -> void
+          def visit_document_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_html_element_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_html_conditional_element_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_if_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_unless_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_case_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_block_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_iteration_block_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_while_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_until_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_for_node: (untyped) -> void
+
+          # : (Array[untyped]) -> void
+          def visit_all: (Array[untyped]) -> void
+
+          # : () -> void
+          def generate_output: () -> void
+
+          private
+
+          # : (*untyped) { () -> void } -> void
+          def indexing: (*untyped) { () -> void } -> void
+
+          # : (untyped) { () -> void } -> void
+          def branching: (untyped) { () -> void } -> void
+        end
+
+        attr_reader node_path: Array[Integer]
+
+        # : (String, ?Hash[Symbol, untyped]) -> void
+        def initialize: (String, ?Hash[Symbol, untyped]) -> void
+
+        # : () -> untyped
+        def compiler_class: () -> untyped
+
+        # : () -> String
+        def inspect: () -> String
+
+        # : (Symbol) -> void
+        def add_subtree_boundary: (Symbol) -> void
+
+        # : (String) -> void
+        def add_postamble: (String) -> void
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/types.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/herb/engine/slots/types.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # What kinds of slot there are, and which of them behave the same way.
+      #
+      # Everything that asks a slot what it can do asks here, so the marker writer, the dependency
+      # map, the state compiler and the subtree compiler all draw the same lines.
+      module Types
+        STRUCTURAL: Array[Symbol]
+
+        ATTRIBUTE_VALUES: Array[Symbol]
+
+        ELEMENT_ANCHORED: Array[Symbol]
+
+        NAMEABLE: Array[Symbol]
+
+        VALUED: Array[Symbol]
+
+        INTERPOLATED: Array[Symbol]
+
+        # : (Symbol) -> bool
+        def self.structural?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.attribute_value?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.attribute?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.element_anchored?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.nameable?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.valued?: (Symbol) -> bool
+
+        # : (Symbol) -> bool
+        def self.interpolated?: (Symbol) -> bool
+      end
+    end
+  end
+end