syntax_tree 5.3.0 → 6.0.0

data/lib/syntax_tree/mermaid.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "stringio"
+
+module SyntaxTree
+  # This module is responsible for rendering mermaid (https://mermaid.js.org/)
+  # flow charts.
+  module Mermaid
+    # This is the main class that handles rendering a flowchart. It keeps track
+    # of its nodes and links and renders them according to the mermaid syntax.
+    class FlowChart
+      attr_reader :output, :prefix, :nodes, :links
+
+      def initialize
+        @output = StringIO.new
+        @output.puts("flowchart TD")
+        @prefix = "  "
+
+        @nodes = {}
+        @links = []
+      end
+
+      # Retrieve a node that has already been added to the flowchart by its id.
+      def fetch(id)
+        nodes.fetch(id)
+      end
+
+      # Add a link to the flowchart between two nodes with an optional label.
+      def link(from, to, label = nil, type: :directed, color: nil)
+        link = Link.new(from, to, label, type, color)
+        links << link
+
+        output.puts("#{prefix}#{link.render}")
+        link
+      end
+
+      # Add a node to the flowchart with an optional label.
+      def node(id, label = " ", shape: :rectangle)
+        node = Node.new(id, label, shape)
+        nodes[id] = node
+
+        output.puts("#{prefix}#{nodes[id].render}")
+        node
+      end
+
+      # Add a subgraph to the flowchart. Within the given block, all of the
+      # nodes will be rendered within the subgraph.
+      def subgraph(label)
+        output.puts("#{prefix}subgraph #{Mermaid.escape(label)}")
+
+        previous = prefix
+        @prefix = "#{prefix}  "
+
+        begin
+          yield
+        ensure
+          @prefix = previous
+          output.puts("#{prefix}end")
+        end
+      end
+
+      # Return the rendered flowchart.
+      def render
+        links.each_with_index do |link, index|
+          if link.color
+            output.puts("#{prefix}linkStyle #{index} stroke:#{link.color}")
+          end
+        end
+
+        output.string
+      end
+    end
+
+    # This class represents a link between two nodes in a flowchart. It is not
+    # meant to be interacted with directly, but rather used as a data structure
+    # by the FlowChart class.
+    class Link
+      TYPES = %i[directed dotted].freeze
+      COLORS = %i[green red].freeze
+
+      attr_reader :from, :to, :label, :type, :color
+
+      def initialize(from, to, label, type, color)
+        raise unless TYPES.include?(type)
+        raise if color && !COLORS.include?(color)
+
+        @from = from
+        @to = to
+        @label = label
+        @type = type
+        @color = color
+      end
+
+      def render
+        left_side, right_side, full_side = sides
+
+        if label
+          escaped = Mermaid.escape(label)
+          "#{from.id} #{left_side} #{escaped} #{right_side} #{to.id}"
+        else
+          "#{from.id} #{full_side} #{to.id}"
+        end
+      end
+
+      private
+
+      def sides
+        case type
+        when :directed
+          %w[-- --> -->]
+        when :dotted
+          %w[-. .-> -.->]
+        end
+      end
+    end
+
+    # This class represents a node in a flowchart. Unlike the Link class, it can
+    # be used directly. It is the return value of the #node method, and is meant
+    # to be passed around to #link methods to create links between nodes.
+    class Node
+      SHAPES = %i[circle rectangle rounded stadium].freeze
+
+      attr_reader :id, :label, :shape
+
+      def initialize(id, label, shape)
+        raise unless SHAPES.include?(shape)
+
+        @id = id
+        @label = label
+        @shape = shape
+      end
+
+      def render
+        left_bound, right_bound = bounds
+        "#{id}#{left_bound}#{Mermaid.escape(label)}#{right_bound}"
+      end
+
+      private
+
+      def bounds
+        case shape
+        when :circle
+          %w[(( ))]
+        when :rectangle
+          ["[", "]"]
+        when :rounded
+          %w[( )]
+        when :stadium
+          ["([", "])"]
+        end
+      end
+    end
+
+    class << self
+      # Escape a label to be used in the mermaid syntax. This is used to escape
+      # HTML entities such that they render properly within the quotes.
+      def escape(label)
+        "\"#{CGI.escapeHTML(label)}\""
+      end
+
+      # Create a new flowchart. If a block is given, it will be yielded to and
+      # the flowchart will be rendered. Otherwise, the flowchart will be
+      # returned.
+      def flowchart
+        flowchart = FlowChart.new
+
+        if block_given?
+          yield flowchart
+          flowchart.render
+        else
+          flowchart
+        end
+      end
+    end
+  end
+end

data/lib/syntax_tree/mermaid_visitor.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  # This visitor transforms the AST into a mermaid flow chart.
+  class MermaidVisitor < FieldVisitor
+    attr_reader :flowchart, :target
+
+    def initialize
+      @flowchart = Mermaid.flowchart
+      @target = nil
+    end
+
+    def visit_program(node)
+      super
+      flowchart.render
+    end
+
+    private
+
+    def comments(node)
+      # Ignore
+    end
+
+    def field(name, value)
+      case value
+      when nil
+        # skip
+      when Node
+        flowchart.link(target, visit(value), name)
+      else
+        to =
+          flowchart.node("#{target.id}_#{name}", value.inspect, shape: :stadium)
+        flowchart.link(target, to, name)
+      end
+    end
+
+    def list(name, values)
+      values.each_with_index do |value, index|
+        field("#{name}[#{index}]", value)
+      end
+    end
+
+    def node(node, type)
+      previous_target = target
+
+      begin
+        @target = flowchart.node("node_#{node.object_id}", type)
+        yield
+        @target
+      ensure
+        @target = previous_target
+      end
+    end
+
+    def pairs(name, values)
+      values.each_with_index do |(key, value), index|
+        to = flowchart.node("#{target.id}_#{name}_#{index}", shape: :circle)
+
+        flowchart.link(target, to, "#{name}[#{index}]")
+        flowchart.link(to, visit(key), "[0]")
+        flowchart.link(to, visit(value), "[1]") if value
+      end
+    end
+
+    def text(name, value)
+      field(name, value)
+    end
+  end
+end

data/lib/syntax_tree/{visitor/mutation_visitor.rb → mutation_visitor.rb}

@@ -1,39 +1,39 @@
 # frozen_string_literal: true
 
 module SyntaxTree
-  class Visitor
-    # This visitor walks through the tree and copies each node as it is being
-    # visited. This is useful for mutating the tree before it is formatted.
-    class MutationVisitor < BasicVisitor
-      attr_reader :mutations
+  # This visitor walks through the tree and copies each node as it is being
+  # visited. This is useful for mutating the tree before it is formatted.
+  class MutationVisitor < BasicVisitor
+    attr_reader :mutations
 
-      def initialize
-        @mutations = []
-      end
-
-      # Create a new mutation based on the given query that will mutate the node
-      # using the given block. The block should return a new node that will take
-      # the place of the given node in the tree. These blocks frequently make
-      # use of the `copy` method on nodes to create a new node with the same
-      # properties as the original node.
-      def mutate(query, &block)
-        mutations << [Pattern.new(query).compile, block]
-      end
+    def initialize
+      @mutations = []
+    end
 
-      # This is the base visit method for each node in the tree. It first
-      # creates a copy of the node using the visit_* methods defined below. Then
-      # it checks each mutation in sequence and calls it if it finds a match.
-      def visit(node)
-        return unless node
-        result = node.accept(self)
+    # Create a new mutation based on the given query that will mutate the node
+    # using the given block. The block should return a new node that will take
+    # the place of the given node in the tree. These blocks frequently make use
+    # of the `copy` method on nodes to create a new node with the same
+    # properties as the original node.
+    def mutate(query, &block)
+      mutations << [Pattern.new(query).compile, block]
+    end
 
-        mutations.each do |(pattern, mutation)|
-          result = mutation.call(result) if pattern.call(result)
-        end
+    # This is the base visit method for each node in the tree. It first creates
+    # a copy of the node using the visit_* methods defined below. Then it checks
+    # each mutation in sequence and calls it if it finds a match.
+    def visit(node)
+      return unless node
+      result = node.accept(self)
 
-        result
+      mutations.each do |(pattern, mutation)|
+        result = mutation.call(result) if pattern.call(result)
       end
 
+      result
+    end
+
+    visit_methods do
       # Visit a BEGINBlock node.
       def visit_BEGIN(node)
         node.copy(