herb 0.7.2 → 0.7.3

data/vendor/prism/templates/lib/prism/compiler.rb.erb

@@ -0,0 +1,43 @@
+module Prism
+  # A compiler is a visitor that returns the value of each node as it visits.
+  # This is as opposed to a visitor which will only walk the tree. This can be
+  # useful when you are trying to compile a tree into a different format.
+  #
+  # For example, to build a representation of the tree as s-expressions, you
+  # could write:
+  #
+  #     class SExpressions < Prism::Compiler
+  #       def visit_arguments_node(node) = [:arguments, super]
+  #       def visit_call_node(node) = [:call, super]
+  #       def visit_integer_node(node) = [:integer]
+  #       def visit_program_node(node) = [:program, super]
+  #     end
+  #
+  #     Prism.parse("1 + 2").value.accept(SExpressions.new)
+  #     # => [:program, [[[:call, [[:integer], [:arguments, [[:integer]]]]]]]]
+  #
+  class Compiler < Visitor
+    # Visit an individual node.
+    def visit(node)
+      node&.accept(self)
+    end
+
+    # Visit a list of nodes.
+    def visit_all(nodes)
+      nodes.map { |node| node&.accept(self) }
+    end
+
+    # Visit the child nodes of the given node.
+    def visit_child_nodes(node)
+      node.compact_child_nodes.map { |node| node.accept(self) }
+    end
+
+    <%- nodes.each_with_index do |node, index| -%>
+<%= "\n" if index != 0 -%>
+    # Compile a <%= node.name %> node
+    def visit_<%= node.human %>(node)
+      node.compact_child_nodes.map { |node| node.accept(self) }
+    end
+    <%- end -%>
+  end
+end

data/vendor/prism/templates/lib/prism/dispatcher.rb.erb

@@ -0,0 +1,103 @@
+module Prism
+  # The dispatcher class fires events for nodes that are found while walking an
+  # AST to all registered listeners. It's useful for performing different types
+  # of analysis on the AST while only having to walk the tree once.
+  #
+  # To use the dispatcher, you would first instantiate it and register listeners
+  # for the events you're interested in:
+  #
+  #     class OctalListener
+  #       def on_integer_node_enter(node)
+  #         if node.octal? && !node.slice.start_with?("0o")
+  #           warn("Octal integers should be written with the 0o prefix")
+  #         end
+  #       end
+  #     end
+  #
+  #     listener = OctalListener.new
+  #     dispatcher = Prism::Dispatcher.new
+  #     dispatcher.register(listener, :on_integer_node_enter)
+  #
+  # Then, you can walk any number of trees and dispatch events to the listeners:
+  #
+  #     result = Prism.parse("001 + 002 + 003")
+  #     dispatcher.dispatch(result.value)
+  #
+  # Optionally, you can also use `#dispatch_once` to dispatch enter and leave
+  # events for a single node without recursing further down the tree. This can
+  # be useful in circumstances where you want to reuse the listeners you already
+  # have registers but want to stop walking the tree at a certain point.
+  #
+  #     integer = result.value.statements.body.first.receiver.receiver
+  #     dispatcher.dispatch_once(integer)
+  #
+  class Dispatcher < Visitor
+    # attr_reader listeners: Hash[Symbol, Array[Listener]]
+    attr_reader :listeners
+
+    # Initialize a new dispatcher.
+    def initialize
+      @listeners = {}
+    end
+
+    # Register a listener for one or more events.
+    #
+    # def register: (Listener, *Symbol) -> void
+    def register(listener, *events)
+      register_events(listener, events)
+    end
+
+    # Register all public methods of a listener that match the pattern
+    # `on_<node_name>_(enter|leave)`.
+    #
+    # def register_public_methods: (Listener) -> void
+    def register_public_methods(listener)
+      register_events(listener, listener.public_methods(false).grep(/\Aon_.+_(?:enter|leave)\z/))
+    end
+
+    # Register a listener for the given events.
+    private def register_events(listener, events)
+      events.each { |event| (listeners[event] ||= []) << listener }
+    end
+
+    # Walks `root` dispatching events to all registered listeners.
+    #
+    # def dispatch: (Node) -> void
+    alias dispatch visit
+
+    # Dispatches a single event for `node` to all registered listeners.
+    #
+    # def dispatch_once: (Node) -> void
+    def dispatch_once(node)
+      node.accept(DispatchOnce.new(listeners))
+    end
+    <%- nodes.each do |node| -%>
+
+    # Dispatch enter and leave events for <%= node.name %> nodes and continue
+    # walking the tree.
+    def visit_<%= node.human %>(node)
+      listeners[:on_<%= node.human %>_enter]&.each { |listener| listener.on_<%= node.human %>_enter(node) }
+      super
+      listeners[:on_<%= node.human %>_leave]&.each { |listener| listener.on_<%= node.human %>_leave(node) }
+    end
+    <%- end -%>
+
+    class DispatchOnce < Visitor # :nodoc:
+      attr_reader :listeners
+
+      def initialize(listeners)
+        @listeners = listeners
+      end
+      <%- nodes.each do |node| -%>
+
+      # Dispatch enter and leave events for <%= node.name %> nodes.
+      def visit_<%= node.human %>(node)
+        listeners[:on_<%= node.human %>_enter]&.each { |listener| listener.on_<%= node.human %>_enter(node) }
+        listeners[:on_<%= node.human %>_leave]&.each { |listener| listener.on_<%= node.human %>_leave(node) }
+      end
+      <%- end -%>
+    end
+
+    private_constant :DispatchOnce
+  end
+end

data/vendor/prism/templates/lib/prism/dot_visitor.rb.erb

@@ -0,0 +1,189 @@
+require "cgi/escape"
+require "cgi/util" unless defined?(CGI::EscapeExt)
+
+module Prism
+  # This visitor provides the ability to call Node#to_dot, which converts a
+  # subtree into a graphviz dot graph.
+  class DotVisitor < Visitor
+    class Field # :nodoc:
+      attr_reader :name, :value, :port
+
+      def initialize(name, value, port)
+        @name = name
+        @value = value
+        @port = port
+      end
+
+      def to_dot
+        if port
+          "<tr><td align=\"left\" colspan=\"2\" port=\"#{name}\">#{name}</td></tr>"
+        else
+          "<tr><td align=\"left\">#{name}</td><td>#{CGI.escapeHTML(value || raise)}</td></tr>"
+        end
+      end
+    end
+
+    class Table # :nodoc:
+      attr_reader :name, :fields
+
+      def initialize(name)
+        @name = name
+        @fields = []
+      end
+
+      def field(name, value = nil, port: false)
+        fields << Field.new(name, value, port)
+      end
+
+      def to_dot
+        dot = <<~DOT
+          <table border="0" cellborder="1" cellspacing="0" cellpadding="4">
+            <tr><td colspan="2"><b>#{name}</b></td></tr>
+        DOT
+
+        if fields.any?
+          "#{dot}  #{fields.map(&:to_dot).join("\n  ")}\n</table>"
+        else
+          "#{dot}</table>"
+        end
+      end
+    end
+
+    class Digraph # :nodoc:
+      attr_reader :nodes, :waypoints, :edges
+
+      def initialize
+        @nodes = []
+        @waypoints = []
+        @edges = []
+      end
+
+      def node(value)
+        nodes << value
+      end
+
+      def waypoint(value)
+        waypoints << value
+      end
+
+      def edge(value)
+        edges << value
+      end
+
+      def to_dot
+        <<~DOT
+          digraph "Prism" {
+            node [
+              fontname=\"Courier New\"
+              shape=plain
+              style=filled
+              fillcolor=gray95
+            ];
+
+            #{nodes.map { |node| node.gsub(/\n/, "\n  ") }.join("\n  ")}
+            node [shape=point];
+            #{waypoints.join("\n  ")}
+
+            #{edges.join("\n  ")}
+          }
+        DOT
+      end
+    end
+
+    private_constant :Field, :Table, :Digraph
+
+    # The digraph that is being built.
+    attr_reader :digraph
+
+    # Initialize a new dot visitor.
+    def initialize
+      @digraph = Digraph.new
+    end
+
+    # Convert this visitor into a graphviz dot graph string.
+    def to_dot
+      digraph.to_dot
+    end
+    <%- nodes.each do |node| -%>
+
+    # Visit a <%= node.name %> node.
+    def visit_<%= node.human %>(node)
+      table = Table.new("<%= node.name %>")
+      id = node_id(node)
+      <%- if (node_flags = node.flags) -%>
+
+      # flags
+      table.field("flags", <%= node_flags.human %>_inspect(node))
+      <%- end -%>
+      <%- node.fields.each do |field| -%>
+
+      # <%= field.name %>
+      <%- case field -%>
+      <%- when Prism::Template::NodeField -%>
+      table.field("<%= field.name %>", port: true)
+      digraph.edge("#{id}:<%= field.name %> -> #{node_id(node.<%= field.name %>)};")
+      <%- when Prism::Template::OptionalNodeField -%>
+      unless (<%= field.name %> = node.<%= field.name %>).nil?
+        table.field("<%= field.name %>", port: true)
+        digraph.edge("#{id}:<%= field.name %> -> #{node_id(<%= field.name %>)};")
+      end
+      <%- when Prism::Template::NodeListField -%>
+      if node.<%= field.name %>.any?
+        table.field("<%= field.name %>", port: true)
+
+        waypoint = "#{id}_<%= field.name %>"
+        digraph.waypoint("#{waypoint};")
+
+        digraph.edge("#{id}:<%= field.name %> -> #{waypoint};")
+        node.<%= field.name %>.each { |child| digraph.edge("#{waypoint} -> #{node_id(child)};") }
+      else
+        table.field("<%= field.name %>", "[]")
+      end
+      <%- when Prism::Template::StringField, Prism::Template::ConstantField, Prism::Template::OptionalConstantField, Prism::Template::UInt8Field, Prism::Template::UInt32Field, Prism::Template::ConstantListField, Prism::Template::IntegerField, Prism::Template::DoubleField -%>
+      table.field("<%= field.name %>", node.<%= field.name %>.inspect)
+      <%- when Prism::Template::LocationField -%>
+      table.field("<%= field.name %>", location_inspect(node.<%= field.name %>))
+      <%- when Prism::Template::OptionalLocationField -%>
+      unless (<%= field.name %> = node.<%= field.name %>).nil?
+        table.field("<%= field.name %>", location_inspect(<%= field.name %>))
+      end
+      <%- else -%>
+      <%- raise -%>
+      <%- end -%>
+      <%- end -%>
+
+      digraph.nodes << <<~DOT
+        #{id} [
+          label=<#{table.to_dot.gsub(/\n/, "\n  ")}>
+        ];
+      DOT
+
+      super
+    end
+    <%- end -%>
+
+    private
+
+    # Generate a unique node ID for a node throughout the digraph.
+    def node_id(node)
+      "Node_#{node.object_id}"
+    end
+
+    # Inspect a location to display the start and end line and column numbers.
+    def location_inspect(location)
+      "(#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column})"
+    end
+    <%- flags.each do |flag| -%>
+
+    # Inspect a node that has <%= flag.human %> flags to display the flags as a
+    # comma-separated list.
+    def <%= flag.human %>_inspect(node)
+      flags = [] #: Array[String]
+      <%- flag.values.each do |value| -%>
+      flags << "<%= value.name.downcase %>" if node.<%= value.name.downcase %>?
+      <%- end -%>
+      flags.join(", ")
+    end
+    <%- end -%>
+  end
+end

data/vendor/prism/templates/lib/prism/dsl.rb.erb

@@ -0,0 +1,133 @@
+module Prism
+  # The DSL module provides a set of methods that can be used to create prism
+  # nodes in a more concise manner. For example, instead of writing:
+  #
+  #     source = Prism::Source.for("[1]")
+  #
+  #     Prism::ArrayNode.new(
+  #       source,
+  #       0,
+  #       Prism::Location.new(source, 0, 3),
+  #       0,
+  #       [
+  #         Prism::IntegerNode.new(
+  #           source,
+  #           0,
+  #           Prism::Location.new(source, 1, 1),
+  #           Prism::IntegerBaseFlags::DECIMAL,
+  #           1
+  #         )
+  #       ],
+  #       Prism::Location.new(source, 0, 1),
+  #       Prism::Location.new(source, 2, 1)
+  #     )
+  #
+  # you could instead write:
+  #
+  #     class Builder
+  #       include Prism::DSL
+  #
+  #       attr_reader :default_source
+  #
+  #       def initialize
+  #         @default_source = source("[1]")
+  #       end
+  #
+  #       def build
+  #         array_node(
+  #           location: location(start_offset: 0, length: 3),
+  #           elements: [
+  #             integer_node(
+  #               location: location(start_offset: 1, length: 1),
+  #               flags: integer_base_flag(:decimal),
+  #               value: 1
+  #             )
+  #           ],
+  #           opening_loc: location(start_offset: 0, length: 1),
+  #           closing_loc: location(start_offset: 2, length: 1)
+  #         )
+  #       end
+  #     end
+  #
+  # This is mostly helpful in the context of generating trees programmatically.
+  module DSL
+    # Provide all of these methods as module methods as well, to allow for
+    # building nodes like Prism::DSL.nil_node.
+    extend self
+
+    # Create a new Source object.
+    def source(string)
+      Source.for(string)
+    end
+
+    # Create a new Location object.
+    def location(source: default_source, start_offset: 0, length: 0)
+      Location.new(source, start_offset, length)
+    end
+    <%- nodes.each do |node| -%>
+
+    # Create a new <%= node.name %> node.
+    def <%= node.human %>(<%= ["source: default_source", "node_id: 0", "location: default_location", "flags: 0", *node.fields.map { |field|
+      case field
+      when Prism::Template::NodeField
+        kind = field.specific_kind || field.union_kind&.first
+        if kind.nil?
+          "#{field.name}: default_node(source, location)"
+        else
+          "#{field.name}: #{kind.gsub(/(?<=.)[A-Z]/, "_\\0").downcase}(source: source)"
+        end
+      when Prism::Template::ConstantField
+        "#{field.name}: :\"\""
+      when Prism::Template::OptionalNodeField, Prism::Template::OptionalConstantField, Prism::Template::OptionalLocationField
+        "#{field.name}: nil"
+      when Prism::Template::NodeListField, Prism::Template::ConstantListField
+        "#{field.name}: []"
+      when Prism::Template::StringField
+        "#{field.name}: \"\""
+      when Prism::Template::LocationField
+        "#{field.name}: location"
+      when Prism::Template::UInt8Field, Prism::Template::UInt32Field, Prism::Template::IntegerField
+        "#{field.name}: 0"
+      when Prism::Template::DoubleField
+        "#{field.name}: 0.0"
+      else
+        raise
+      end
+    }].join(", ") %>)
+      <%= node.name %>.new(<%= ["source", "node_id", "location", "flags", *node.fields.map(&:name)].join(", ") %>)
+    end
+    <%- end -%>
+    <%- flags.each do |flag| -%>
+
+    # Retrieve the value of one of the <%= flag.name %> flags.
+    def <%= flag.human.chomp("s") %>(name)
+      case name
+      <%- flag.values.each do |value| -%>
+      when :<%= value.name.downcase %> then <%= flag.name %>::<%= value.name %>
+      <%- end -%>
+      else Kernel.raise ArgumentError, "invalid <%= flag.name %> flag: #{name.inspect}"
+      end
+    end
+    <%- end -%>
+
+    private
+
+    # The default source object that gets attached to nodes and locations if no
+    # source is specified.
+    def default_source
+      Source.for("")
+    end
+
+    # The default location object that gets attached to nodes if no location is
+    # specified, which uses the given source.
+    def default_location
+      Location.new(default_source, 0, 0)
+    end
+
+    # The default node that gets attached to nodes if no node is specified for a
+    # required node field.
+    def default_node(source, location)
+      MissingNode.new(source, -1, location, 0)
+    end
+  end
+end

data/vendor/prism/templates/lib/prism/inspect_visitor.rb.erb

@@ -0,0 +1,131 @@
+module Prism
+  # This visitor is responsible for composing the strings that get returned by
+  # the various #inspect methods defined on each of the nodes.
+  class InspectVisitor < Visitor
+    # Most of the time, we can simply pass down the indent to the next node.
+    # However, when we are inside a list we want some extra special formatting
+    # when we hit an element in that list. In this case, we have a special
+    # command that replaces the subsequent indent with the given value.
+    class Replace # :nodoc:
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+    end
+
+    private_constant :Replace
+
+    # The current prefix string.
+    attr_reader :indent
+
+    # The list of commands that we need to execute in order to compose the
+    # final string.
+    attr_reader :commands
+
+    # Initializes a new instance of the InspectVisitor.
+    def initialize(indent = +"")
+      @indent = indent
+      @commands = []
+    end
+
+    # Compose an inspect string for the given node.
+    def self.compose(node)
+      visitor = new
+      node.accept(visitor)
+      visitor.compose
+    end
+
+    # Compose the final string.
+    def compose
+      buffer = +""
+      replace = nil
+
+      until commands.empty?
+        # @type var command: String | node | Replace
+        # @type var indent: String
+        command, indent = *commands.shift
+
+        case command
+        when String
+          buffer << (replace || indent)
+          buffer << command
+          replace = nil
+        when Node
+          visitor = InspectVisitor.new(indent)
+          command.accept(visitor)
+          @commands = [*visitor.commands, *@commands]
+        when Replace
+          replace = command.value
+        else
+          raise "Unknown command: #{command.inspect}"
+        end
+      end
+
+      buffer
+    end
+    <%- nodes.each do |node| -%>
+
+    # Inspect a <%= node.name %> node.
+    def visit_<%= node.human %>(node)
+      commands << [inspect_node(<%= node.name.inspect %>, node), indent]
+      <%- (fields = [node.flags || Prism::Template::Flags.empty, *node.fields]).each_with_index do |field, index| -%>
+      <%- pointer = index == fields.length - 1 ? "└── " : "├── " -%>
+      <%- preadd = index == fields.length - 1 ? "    " : "│   " -%>
+      <%- case field -%>
+      <%- when Prism::Template::Flags -%>
+      flags = [("newline" if node.newline?), ("static_literal" if node.static_literal?), <%= field.values.map { |value| "(\"#{value.name.downcase}\" if node.#{value.name.downcase}?)" }.join(", ") %>].compact
+      commands << ["<%= pointer %>flags: #{flags.empty? ? "∅" : flags.join(", ")}\n", indent]
+      <%- when Prism::Template::NodeListField -%>
+      commands << ["<%= pointer %><%= field.name %>: (length: #{(<%= field.name %> = node.<%= field.name %>).length})\n", indent]
+      if <%= field.name %>.any?
+        <%= field.name %>[0...-1].each do |child|
+          commands << [Replace.new("#{indent}<%= preadd %>├── "), indent]
+          commands << [child, "#{indent}<%= preadd %>│   "]
+        end
+        commands << [Replace.new("#{indent}<%= preadd %>└── "), indent]
+        commands << [<%= field.name %>[-1], "#{indent}<%= preadd %>    "]
+      end
+      <%- when Prism::Template::NodeField -%>
+      commands << ["<%= pointer %><%= field.name %>:\n", indent]
+      commands << [node.<%= field.name %>, "#{indent}<%= preadd %>"]
+      <%- when Prism::Template::OptionalNodeField -%>
+      if (<%= field.name %> = node.<%= field.name %>).nil?
+        commands << ["<%= pointer %><%= field.name %>: ∅\n", indent]
+      else
+        commands << ["<%= pointer %><%= field.name %>:\n", indent]
+        commands << [<%= field.name %>, "#{indent}<%= preadd %>"]
+      end
+      <%- when Prism::Template::ConstantField, Prism::Template::ConstantListField, Prism::Template::StringField, Prism::Template::UInt8Field, Prism::Template::UInt32Field, Prism::Template::IntegerField, Prism::Template::DoubleField -%>
+      commands << ["<%= pointer %><%= field.name %>: #{node.<%= field.name %>.inspect}\n", indent]
+      <%- when Prism::Template::OptionalConstantField -%>
+      if (<%= field.name %> = node.<%= field.name %>).nil?
+        commands << ["<%= pointer %><%= field.name %>: ∅\n", indent]
+      else
+        commands << ["<%= pointer %><%= field.name %>: #{<%= field.name %>.inspect}\n", indent]
+      end
+      <%- when Prism::Template::LocationField, Prism::Template::OptionalLocationField -%>
+      commands << ["<%= pointer %><%= field.name %>: #{inspect_location(node.<%= field.name %>)}\n", indent]
+      <%- end -%>
+      <%- end -%>
+    end
+    <%- end -%>
+
+    private
+
+    # Compose a header for the given node.
+    def inspect_node(name, node)
+      location = node.location
+      "@ #{name} (location: (#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column}))\n"
+    end
+
+    # Compose a string representing the given inner location field.
+    def inspect_location(location)
+      if location
+        "(#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column}) = #{location.slice.inspect}"
+      else
+        "∅"
+      end
+    end
+  end
+end

data/vendor/prism/templates/lib/prism/mutation_compiler.rb.erb

@@ -0,0 +1,19 @@
+module Prism
+  # This visitor walks through the tree and copies each node as it is being
+  # visited. This is useful for consumers that want to mutate the tree, as you
+  # can change subtrees in place without effecting the rest of the tree.
+  class MutationCompiler < Compiler
+    <%- nodes.each_with_index do |node, index| -%>
+<%= "\n" if index != 0 -%>
+    # Copy a <%= node.name %> node
+    def visit_<%= node.human %>(node)
+      <%- fields = node.fields.select { |field| [Prism::Template::NodeField, Prism::Template::OptionalNodeField, Prism::Template::NodeListField].include?(field.class) } -%>
+      <%- if fields.any? -%>
+      node.copy(<%= fields.map { |field| "#{field.name}: #{field.is_a?(Prism::Template::NodeListField) ? "visit_all" : "visit"}(node.#{field.name})" }.join(", ") %>)
+      <%- else -%>
+      node.copy
+      <%- end -%>
+    end
+    <%- end -%>
+  end
+end