syntax_tree 5.3.0 → 6.0.0

data/lib/syntax_tree/node.rb

@@ -126,18 +126,28 @@ module SyntaxTree
       raise NotImplementedError
     end
 
+    def start_char
+      location.start_char
+    end
+
+    def end_char
+      location.end_char
+    end
+
     def pretty_print(q)
-      visitor = Visitor::PrettyPrintVisitor.new(q)
-      visitor.visit(self)
+      accept(PrettyPrintVisitor.new(q))
     end
 
     def to_json(*opts)
-      visitor = Visitor::JSONVisitor.new
-      visitor.visit(self).to_json(*opts)
+      accept(JSONVisitor.new).to_json(*opts)
+    end
+
+    def to_mermaid
+      accept(MermaidVisitor.new)
     end
 
     def construct_keys
-      PrettierPrint.format(+"") { |q| Visitor::MatchVisitor.new(q).visit(self) }
+      PrettierPrint.format(+"") { |q| accept(MatchVisitor.new(q)) }
     end
   end
 
@@ -555,7 +565,7 @@ module SyntaxTree
   #     collection[]
   #
   class ARef < Node
-    # [untyped] the value being indexed
+    # [Node] the value being indexed
     attr_reader :collection
 
     # [nil | Args] the value being passed within the brackets
@@ -633,7 +643,7 @@ module SyntaxTree
   #     collection[index] = value
   #
   class ARefField < Node
-    # [untyped] the value being indexed
+    # [Node] the value being indexed
     attr_reader :collection
 
     # [nil | Args] the value being passed within the brackets
@@ -808,7 +818,7 @@ module SyntaxTree
   #     method(first, second, third)
   #
   class Args < Node
-    # [Array[ untyped ]] the arguments that this node wraps
+    # [Array[ Node ]] the arguments that this node wraps
     attr_reader :parts
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -874,7 +884,7 @@ module SyntaxTree
   #     method(&expression)
   #
   class ArgBlock < Node
-    # [nil | untyped] the expression being turned into a block
+    # [nil | Node] the expression being turned into a block
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -926,7 +936,7 @@ module SyntaxTree
   #     method(*arguments)
   #
   class ArgStar < Node
-    # [nil | untyped] the expression being splatted
+    # [nil | Node] the expression being splatted
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -1129,7 +1139,8 @@ module SyntaxTree
       end
     end
 
-    # [LBracket] the bracket that opens this array
+    # [nil | LBracket | QSymbolsBeg | QWordsBeg | SymbolsBeg | WordsBeg] the
+    # bracket that opens this array
     attr_reader :lbracket
 
     # [nil | Args] the contents of the array
@@ -1287,7 +1298,7 @@ module SyntaxTree
     # [nil | VarRef] the optional constant wrapper
     attr_reader :constant
 
-    # [Array[ untyped ]] the regular positional arguments that this array
+    # [Array[ Node ]] the regular positional arguments that this array
     # pattern is matching against
     attr_reader :requireds
 
@@ -1295,7 +1306,7 @@ module SyntaxTree
     # positional arguments
     attr_reader :rest
 
-    # [Array[ untyped ]] the list of positional arguments occurring after the
+    # [Array[ Node ]] the list of positional arguments occurring after the
     # optional star if there is one
     attr_reader :posts
 
@@ -1405,7 +1416,7 @@ module SyntaxTree
     # to assign the result of the expression to
     attr_reader :target
 
-    # [untyped] the expression to be assigned
+    # [Node] the expression to be assigned
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -1480,10 +1491,10 @@ module SyntaxTree
   #
   # In the above example, the would be two Assoc nodes.
   class Assoc < Node
-    # [untyped] the key of this pair
+    # [Node] the key of this pair
     attr_reader :key
 
-    # [untyped] the value of this pair
+    # [nil | Node] the value of this pair
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -1537,7 +1548,7 @@ module SyntaxTree
     private
 
     def format_contents(q)
-      q.parent.format_key(q, key)
+      (q.parent || HashKeyFormatter::Identity.new).format_key(q, key)
       return unless value
 
       if key.comments.empty? && AssignFormatting.skip_indent?(value)
@@ -1558,7 +1569,7 @@ module SyntaxTree
   #     { **pairs }
   #
   class AssocSplat < Node
-    # [nil | untyped] the expression that is being splatted
+    # [nil | Node] the expression that is being splatted
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -1754,6 +1765,20 @@ module SyntaxTree
       end
     end
 
+    # When formatting a single assoc node without the context of the parent
+    # hash, this formatter is used. It uses whatever is present in the node,
+    # because there is nothing to be consistent with.
+    class Identity
+      def format_key(q, key)
+        if key.is_a?(Label)
+          q.format(key)
+        else
+          q.format(key)
+          q.text(" =>")
+        end
+      end
+    end
+
     def self.for(container)
       labels =
         container.assocs.all? do |assoc|
@@ -1908,7 +1933,7 @@ module SyntaxTree
   #     end
   #
   class PinnedBegin < Node
-    # [untyped] the expression being pinned
+    # [Node] the expression being pinned
     attr_reader :statement
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -1989,13 +2014,13 @@ module SyntaxTree
             }
     end
 
-    # [untyped] the left-hand side of the expression
+    # [Node] the left-hand side of the expression
     attr_reader :left
 
     # [Symbol] the operator used between the two expressions
     attr_reader :operator
 
-    # [untyped] the right-hand side of the expression
+    # [Node] the right-hand side of the expression
     attr_reader :right
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -2149,6 +2174,14 @@ module SyntaxTree
       other.is_a?(BlockVar) && params === other.params &&
         ArrayMatch.call(locals, other.locals)
     end
+
+    # When a single required parameter is declared for a block, it gets
+    # automatically expanded if the values being yielded into it are an array.
+    def arg0?
+      params.requireds.length == 1 && params.optionals.empty? &&
+        params.rest.nil? && params.posts.empty? && params.keywords.empty? &&
+        params.keyword_rest.nil? && params.block.nil?
+    end
   end
 
   # BlockArg represents declaring a block parameter on a method definition.
@@ -2242,7 +2275,7 @@ module SyntaxTree
       @comments = []
     end
 
-    def bind(start_char, start_column, end_char, end_column)
+    def bind(parser, start_char, start_column, end_char, end_column)
       @location =
         Location.new(
           start_line: location.start_line,
@@ -2256,6 +2289,7 @@ module SyntaxTree
       # Here we're going to determine the bounds for the statements
       consequent = rescue_clause || else_clause || ensure_clause
       statements.bind(
+        parser,
         start_char,
         start_column,
         consequent ? consequent.location.start_char : end_char,
@@ -2646,7 +2680,7 @@ module SyntaxTree
   # Of course there are a lot of caveats to that, including trailing operators
   # when necessary, where comments are places, how blocks are aligned, etc.
   class CallChainFormatter
-    # [Call | MethodAddBlock] the top of the call chain
+    # [CallNode | MethodAddBlock] the top of the call chain
     attr_reader :node
 
     def initialize(node)
@@ -2867,7 +2901,7 @@ module SyntaxTree
   #     receiver.message
   #
   class CallNode < Node
-    # [nil | untyped] the receiver of the method call
+    # [nil | Node] the receiver of the method call
     attr_reader :receiver
 
     # [nil | :"::" | Op | Period] the operator being used to send the message
@@ -3043,7 +3077,7 @@ module SyntaxTree
     # [Kw] the keyword that opens this expression
     attr_reader :keyword
 
-    # [nil | untyped] optional value being switched on
+    # [nil | Node] optional value being switched on
     attr_reader :value
 
     # [In | When] the next clause in the chain
@@ -3122,14 +3156,14 @@ module SyntaxTree
   #     value => pattern
   #
   class RAssign < Node
-    # [untyped] the left-hand expression
+    # [Node] the left-hand expression
     attr_reader :value
 
     # [Kw | Op] the operator being used to match against the pattern, which is
     # either => or in
     attr_reader :operator
 
-    # [untyped] the pattern on the right-hand side of the expression
+    # [Node] the pattern on the right-hand side of the expression
     attr_reader :pattern
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -3240,7 +3274,7 @@ module SyntaxTree
     # defined
     attr_reader :constant
 
-    # [nil | untyped] the optional superclass declaration
+    # [nil | Node] the optional superclass declaration
     attr_reader :superclass
 
     # [BodyStmt] the expressions to execute within the context of the class
@@ -3378,7 +3412,7 @@ module SyntaxTree
     # [Args] the arguments being sent with the message
     attr_reader :arguments
 
-    # [nil | Block] the optional block being passed to the method
+    # [nil | BlockNode] the optional block being passed to the method
     attr_reader :block
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -3484,19 +3518,19 @@ module SyntaxTree
   #     object.method argument
   #
   class CommandCall < Node
-    # [untyped] the receiver of the message
+    # [nil | Node] the receiver of the message
     attr_reader :receiver
 
-    # [:"::" | Op | Period] the operator used to send the message
+    # [nil | :"::" | Op | Period] the operator used to send the message
     attr_reader :operator
 
-    # [Const | Ident | Op] the message being send
+    # [:call | Const | Ident | Op] the message being send
     attr_reader :message
 
-    # [nil | Args] the arguments going along with the message
+    # [nil | Args | ArgParen] the arguments going along with the message
     attr_reader :arguments
 
-    # [nil | Block] the block associated with this method call
+    # [nil | BlockNode] the block associated with this method call
     attr_reader :block
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -3782,7 +3816,7 @@ module SyntaxTree
   #     object::Const = value
   #
   class ConstPathField < Node
-    # [untyped] the source of the constant
+    # [Node] the source of the constant
     attr_reader :parent
 
     # [Const] the constant itself
@@ -3846,7 +3880,7 @@ module SyntaxTree
   #     object::Const
   #
   class ConstPathRef < Node
-    # [untyped] the source of the constant
+    # [Node] the source of the constant
     attr_reader :parent
 
     # [Const] the constant itself
@@ -4015,7 +4049,7 @@ module SyntaxTree
   #     def object.method(param) result end
   #
   class DefNode < Node
-    # [nil | untyped] the target where the method is being defined
+    # [nil | Node] the target where the method is being defined
     attr_reader :target
 
     # [nil | Op | Period] the operator being used to declare the method
@@ -4027,7 +4061,7 @@ module SyntaxTree
     # [nil | Params | Paren] the parameter declaration for the method
     attr_reader :params
 
-    # [BodyStmt | untyped] the expressions to be executed by the method
+    # [BodyStmt | Node] the expressions to be executed by the method
     attr_reader :bodystmt
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -4090,7 +4124,8 @@ module SyntaxTree
     def format(q)
       q.group do
         q.group do
-          q.text("def ")
+          q.text("def")
+          q.text(" ") if target || name.comments.empty?
 
           if target
             q.format(target)
@@ -4160,7 +4195,7 @@ module SyntaxTree
   #     defined?(variable)
   #
   class Defined < Node
-    # [untyped] the value being sent to the keyword
+    # [Node] the value being sent to the keyword
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -4317,7 +4352,7 @@ module SyntaxTree
       # are no parentheses around the arguments to that command, so we need to
       # break the block.
       case q.parent
-      when Command, CommandCall
+      when nil, Command, CommandCall
         q.break_parent
         format_break(q, break_opening, break_closing)
         return
@@ -4371,7 +4406,7 @@ module SyntaxTree
     # If we're a sibling of a control-flow keyword, then we're going to have to
     # use the do..end bounds.
     def forced_do_end_bounds?(q)
-      case q.parent.call
+      case q.parent&.call
       when Break, Next, ReturnNode, Super
         true
       else
@@ -4451,13 +4486,13 @@ module SyntaxTree
   #
   # One of the sides of the expression may be nil, but not both.
   class RangeNode < Node
-    # [nil | untyped] the left side of the expression
+    # [nil | Node] the left side of the expression
     attr_reader :left
 
     # [Op] the operator used for this range
     attr_reader :operator
 
-    # [nil | untyped] the right side of the expression
+    # [nil | Node] the right side of the expression
     attr_reader :right
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -4578,7 +4613,7 @@ module SyntaxTree
     # dynamic symbol
     attr_reader :parts
 
-    # [String] the quote used to delimit the dynamic symbol
+    # [nil | String] the quote used to delimit the dynamic symbol
     attr_reader :quote
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -4776,7 +4811,7 @@ module SyntaxTree
   #     end
   #
   class Elsif < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
     # [Statements] the expressions to be executed
@@ -4872,6 +4907,25 @@ module SyntaxTree
     def initialize(value:, location:)
       @value = value
       @location = location
+
+      @leading = false
+      @trailing = false
+    end
+
+    def leading!
+      @leading = true
+    end
+
+    def leading?
+      @leading
+    end
+
+    def trailing!
+      @trailing = true
+    end
+
+    def trailing?
+      @trailing
     end
 
     def inline?
@@ -4908,7 +4962,13 @@ module SyntaxTree
     end
 
     def format(q)
-      q.trim
+      if (q.parent.is_a?(DefNode) && q.parent.endless?) ||
+           q.parent.is_a?(Statements)
+        q.trim
+      else
+        q.breakable_return
+      end
+
       q.text(value)
     end
 
@@ -5177,7 +5237,7 @@ module SyntaxTree
   #     object.variable = value
   #
   class Field < Node
-    # [untyped] the parent object that owns the field being assigned
+    # [Node] the parent object that owns the field being assigned
     attr_reader :parent
 
     # [:"::" | Op | Period] the operator being used for the assignment
@@ -5303,13 +5363,13 @@ module SyntaxTree
   #     end
   #
   class FndPtn < Node
-    # [nil | untyped] the optional constant wrapper
+    # [nil | Node] the optional constant wrapper
     attr_reader :constant
 
     # [VarField] the splat on the left-hand side
     attr_reader :left
 
-    # [Array[ untyped ]] the list of positional expressions in the pattern that
+    # [Array[ Node ]] the list of positional expressions in the pattern that
     # are being matched
     attr_reader :values
 
@@ -5405,7 +5465,7 @@ module SyntaxTree
     # pull values out of the object being enumerated
     attr_reader :index
 
-    # [untyped] the object being enumerated in the loop
+    # [Node] the object being enumerated in the loop
     attr_reader :collection
 
     # [Statements] the statements to be executed
@@ -5884,7 +5944,7 @@ module SyntaxTree
       # [Label] the keyword being used
       attr_reader :key
 
-      # [untyped] the optional value for the keyword
+      # [Node] the optional value for the keyword
       attr_reader :value
 
       def initialize(key, value)
@@ -5897,7 +5957,7 @@ module SyntaxTree
       end
 
       def format(q)
-        q.format(key)
+        HashKeyFormatter::Labels.new.format_key(q, key)
 
         if value
           q.text(" ")
@@ -5925,11 +5985,11 @@ module SyntaxTree
       end
     end
 
-    # [nil | untyped] the optional constant wrapper
+    # [nil | Node] the optional constant wrapper
     attr_reader :constant
 
-    # [Array[ [Label, untyped] ]] the set of tuples representing the keywords
-    # that should be matched against in the pattern
+    # [Array[ [DynaSymbol | Label, nil | Node] ]] the set of tuples
+    # representing the keywords that should be matched against in the pattern
     attr_reader :keywords
 
     # [nil | VarField] an optional parameter to gather up all remaining keywords
@@ -6354,7 +6414,7 @@ module SyntaxTree
   #     end
   #
   class IfNode < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
     # [Statements] the expressions to be executed
@@ -6427,13 +6487,13 @@ module SyntaxTree
   #     predicate ? truthy : falsy
   #
   class IfOp < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
-    # [untyped] the expression to be executed if the predicate is truthy
+    # [Node] the expression to be executed if the predicate is truthy
     attr_reader :truthy
 
-    # [untyped] the expression to be executed if the predicate is falsy
+    # [Node] the expression to be executed if the predicate is falsy
     attr_reader :falsy
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -6617,7 +6677,7 @@ module SyntaxTree
   #     end
   #
   class In < Node
-    # [untyped] the pattern to check against
+    # [Node] the pattern to check against
     attr_reader :pattern
 
     # [Statements] the expressions to execute if the pattern matched
@@ -7400,7 +7460,7 @@ module SyntaxTree
     # [MLHS | MLHSParen] the target of the multiple assignment
     attr_reader :target
 
-    # [untyped] the value being assigned
+    # [Node] the value being assigned
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -7460,10 +7520,10 @@ module SyntaxTree
   #     method {}
   #
   class MethodAddBlock < Node
-    # [Call | Command | CommandCall] the method call
+    # [ARef | CallNode | Command | CommandCall | Super | ZSuper] the method call
     attr_reader :call
 
-    # [Block] the block being sent with the method call
+    # [BlockNode] the block being sent with the method call
     attr_reader :block
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -7535,8 +7595,12 @@ module SyntaxTree
   #     first, second, third = value
   #
   class MLHS < Node
-    # Array[ARefField | ArgStar | Field | Ident | MLHSParen | VarField] the
-    # parts of the left-hand side of a multiple assignment
+    # [
+    #   Array[
+    #     ARefField | ArgStar | ConstPathField | Field | Ident | MLHSParen |
+    #       TopConstField | VarField
+    #   ]
+    # ] the parts of the left-hand side of a multiple assignment
     attr_reader :parts
 
     # [boolean] whether or not there is a trailing comma at the end of this
@@ -7762,7 +7826,7 @@ module SyntaxTree
   #     values = first, second, third
   #
   class MRHS < Node
-    # Array[untyped] the parts that are being assigned
+    # [Array[Node]] the parts that are being assigned
     attr_reader :parts
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -7938,7 +8002,7 @@ module SyntaxTree
     # [Op] the operator being used for the assignment
     attr_reader :operator
 
-    # [untyped] the expression to be assigned
+    # [Node] the expression to be assigned
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -8095,7 +8159,7 @@ module SyntaxTree
       # [Ident] the name of the parameter
       attr_reader :name
 
-      # [untyped] the value of the parameter
+      # [Node] the value of the parameter
       attr_reader :value
 
       def initialize(name, value)
@@ -8120,7 +8184,7 @@ module SyntaxTree
       # [Ident] the name of the parameter
       attr_reader :name
 
-      # [nil | untyped] the value of the parameter
+      # [nil | Node] the value of the parameter
       attr_reader :value
 
       def initialize(name, value)
@@ -8161,10 +8225,10 @@ module SyntaxTree
       end
     end
 
-    # [Array[ Ident ]] any required parameters
+    # [Array[ Ident | MLHSParen ]] any required parameters
     attr_reader :requireds
 
-    # [Array[ [ Ident, untyped ] ]] any optional parameters and their default
+    # [Array[ [ Ident, Node ] ]] any optional parameters and their default
     # values
     attr_reader :optionals
 
@@ -8176,11 +8240,12 @@ module SyntaxTree
     # parameter
     attr_reader :posts
 
-    # [Array[ [ Ident, nil | untyped ] ]] any keyword parameters and their
+    # [Array[ [ Label, nil | Node ] ]] any keyword parameters and their
     # optional default values
     attr_reader :keywords
 
-    # [nil | :nil | KwRestParam] the optional keyword rest parameter
+    # [nil | :nil | ArgsForward | KwRestParam] the optional keyword rest
+    # parameter
     attr_reader :keyword_rest
 
     # [nil | BlockArg] the optional block parameter
@@ -8369,7 +8434,7 @@ module SyntaxTree
     # [LParen] the left parenthesis that opened this statement
     attr_reader :lparen
 
-    # [nil | untyped] the expression inside the parentheses
+    # [nil | Node] the expression inside the parentheses
     attr_reader :contents
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -9218,7 +9283,7 @@ module SyntaxTree
   #     end
   #
   class RescueEx < Node
-    # [untyped] the list of exceptions being rescued
+    # [nil | Node] the list of exceptions being rescued
     attr_reader :exceptions
 
     # [nil | Field | VarField] the expression being used to capture the raised
@@ -9296,7 +9361,7 @@ module SyntaxTree
     # [Kw] the rescue keyword
     attr_reader :keyword
 
-    # [RescueEx] the exceptions being rescued
+    # [nil | RescueEx] the exceptions being rescued
     attr_reader :exception
 
     # [Statements] the expressions to evaluate when an error is rescued
@@ -9416,10 +9481,10 @@ module SyntaxTree
   #     expression rescue value
   #
   class RescueMod < Node
-    # [untyped] the expression to execute
+    # [Node] the expression to execute
     attr_reader :statement
 
-    # [untyped] the value to use if the executed expression raises an error
+    # [Node] the value to use if the executed expression raises an error
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -9678,7 +9743,7 @@ module SyntaxTree
   #     end
   #
   class SClass < Node
-    # [untyped] the target of the singleton class to enter
+    # [Node] the target of the singleton class to enter
     attr_reader :target
 
     # [BodyStmt] the expressions to be executed
@@ -9752,23 +9817,19 @@ module SyntaxTree
   # propagate that onto void_stmt nodes inside the stmts in order to make sure
   # all comments get printed appropriately.
   class Statements < Node
-    # [SyntaxTree] the parser that is generating this node
-    attr_reader :parser
-
-    # [Array[ untyped ]] the list of expressions contained within this node
+    # [Array[ Node ]] the list of expressions contained within this node
     attr_reader :body
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
     attr_reader :comments
 
-    def initialize(parser, body:, location:)
-      @parser = parser
+    def initialize(body:, location:)
       @body = body
       @location = location
       @comments = []
     end
 
-    def bind(start_char, start_column, end_char, end_column)
+    def bind(parser, start_char, start_column, end_char, end_column)
       @location =
         Location.new(
           start_line: location.start_line,
@@ -9794,7 +9855,7 @@ module SyntaxTree
         body[0] = VoidStmt.new(location: location)
       end
 
-      attach_comments(start_char, end_char)
+      attach_comments(parser, start_char, end_char)
     end
 
     def bind_end(end_char, end_column)
@@ -9826,7 +9887,6 @@ module SyntaxTree
     def copy(body: nil, location: nil)
       node =
         Statements.new(
-          parser,
           body: body || self.body,
           location: location || self.location
         )
@@ -9838,7 +9898,7 @@ module SyntaxTree
     alias deconstruct child_nodes
 
     def deconstruct_keys(_keys)
-      { parser: parser, body: body, location: location, comments: comments }
+      { body: body, location: location, comments: comments }
     end
 
     def format(q)
@@ -9898,7 +9958,7 @@ module SyntaxTree
     # As efficiently as possible, gather up all of the comments that have been
     # found while this statements list was being parsed and add them into the
     # body.
-    def attach_comments(start_char, end_char)
+    def attach_comments(parser, start_char, end_char)
       parser_comments = parser.comments
 
       comment_index = 0
@@ -9945,9 +10005,13 @@ module SyntaxTree
     # string
     attr_reader :parts
 
+    # [Array[ Comment | EmbDoc ]] the comments attached to this node
+    attr_reader :comments
+
     def initialize(parts:, location:)
       @parts = parts
       @location = location
+      @comments = []
     end
 
     def accept(visitor)
@@ -9974,6 +10038,33 @@ module SyntaxTree
     def ===(other)
       other.is_a?(StringContent) && ArrayMatch.call(parts, other.parts)
     end
+
+    def format(q)
+      q.text(q.quote)
+      q.group do
+        parts.each do |part|
+          if part.is_a?(TStringContent)
+            value = Quotes.normalize(part.value, q.quote)
+            first = true
+
+            value.each_line(chomp: true) do |line|
+              if first
+                first = false
+              else
+                q.breakable_return
+              end
+
+              q.text(line)
+            end
+
+            q.breakable_return if value.end_with?("\n")
+          else
+            q.format(part)
+          end
+        end
+      end
+      q.text(q.quote)
+    end
   end
 
   # StringConcat represents concatenating two strings together using a backward
@@ -9983,7 +10074,8 @@ module SyntaxTree
   #       "second"
   #
   class StringConcat < Node
-    # [StringConcat | StringLiteral] the left side of the concatenation
+    # [Heredoc | StringConcat | StringLiteral] the left side of the
+    # concatenation
     attr_reader :left
 
     # [StringLiteral] the right side of the concatenation
@@ -10180,7 +10272,7 @@ module SyntaxTree
     # string literal
     attr_reader :parts
 
-    # [String] which quote was used by the string literal
+    # [nil | String] which quote was used by the string literal
     attr_reader :quote
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -10425,8 +10517,8 @@ module SyntaxTree
   #     :symbol
   #
   class SymbolLiteral < Node
-    # [Backtick | Const | CVar | GVar | Ident | IVar | Kw | Op] the value of the
-    # symbol
+    # [Backtick | Const | CVar | GVar | Ident | IVar | Kw | Op | TStringContent]
+    # the value of the symbol
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -10465,6 +10557,7 @@ module SyntaxTree
 
     def format(q)
       q.text(":")
+      q.text("\\") if value.comments.any?
       q.format(value)
     end
 
@@ -10934,7 +11027,7 @@ module SyntaxTree
   #     not value
   #
   class Not < Node
-    # [nil | untyped] the statement on which to operate
+    # [nil | Node] the statement on which to operate
     attr_reader :statement
 
     # [boolean] whether or not parentheses were used
@@ -11021,7 +11114,7 @@ module SyntaxTree
     # [String] the operator being used
     attr_reader :operator
 
-    # [untyped] the statement on which to operate
+    # [Node] the statement on which to operate
     attr_reader :statement
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -11165,7 +11258,7 @@ module SyntaxTree
   #     end
   #
   class UnlessNode < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
     # [Statements] the expressions to be executed
@@ -11311,7 +11404,7 @@ module SyntaxTree
   #     end
   #
   class UntilNode < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
     # [Statements] the expressions to be executed
@@ -11379,7 +11472,7 @@ module SyntaxTree
   #
   # In the example above, the VarField node represents the +variable+ token.
   class VarField < Node
-    # [nil | Const | CVar | GVar | Ident | IVar] the target of this node
+    # [nil | :nil | Const | CVar | GVar | Ident | IVar] the target of this node
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -11490,8 +11583,9 @@ module SyntaxTree
     #
     # To be clear, this method should just not exist. It's not good. It's a
     # place of shame. But it's necessary for now, so I'm keeping it.
-    def pin(parent)
-      replace = PinnedVarRef.new(value: value, location: location)
+    def pin(parent, pin)
+      replace =
+        PinnedVarRef.new(value: value, location: pin.location.to(location))
 
       parent
         .deconstruct_keys([])
@@ -11517,7 +11611,7 @@ module SyntaxTree
   # This can be a plain local variable like the example above. It can also be a
   # a class variable, a global variable, or an instance variable.
   class PinnedVarRef < Node
-    # [VarRef] the value of this node
+    # [Const | CVar | GVar | Ident | IVar] the value of this node
     attr_reader :value
 
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
@@ -11631,9 +11725,6 @@ module SyntaxTree
   #     ;;
   #
   class VoidStmt < Node
-    # [Location] the location of this node
-    attr_reader :location
-
     # [Array[ Comment | EmbDoc ]] the comments attached to this node
     attr_reader :comments
 
@@ -11794,7 +11885,7 @@ module SyntaxTree
   #     end
   #
   class WhileNode < Node
-    # [untyped] the expression to be checked
+    # [Node] the expression to be checked
     attr_reader :predicate
 
     # [Statements] the expressions to be executed