Introduce SyntaxTreeStructure

Author: ahoppen

Sources/SwiftSyntax/Misc.swift.gyb

@@ -43,6 +43,20 @@ extension Syntax {
     }
   }
 
+  public static var structure: SyntaxNodeStructure {
+    return .choices([
+      .node(UnknownSyntax.self),
+      .node(TokenSyntax.self),
+% for node in NON_BASE_SYNTAX_NODES:
+%   if node.is_base():
+      .node(Unknown${node.name}.self),
+%   else:
+      .node(${node.name}.self),
+%   end
+% end
+    ])
+  }
+
   public func childNameForDiagnostics(_ index: SyntaxChildrenIndex) -> String? {
     switch self.as(SyntaxEnum.self) {
     case .token(let node):

Sources/SwiftSyntax/Syntax.swift

@@ -10,6 +10,44 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Describes the statically allowed structure of a syntax tree node.
+public enum SyntaxNodeStructure {
+  public enum SyntaxChoice {
+    case node(SyntaxProtocol.Type)
+    case token(TokenKind)
+  }
+
+  /// The node contains a fixed number of children which can be accessed by these key paths.
+  case layout([AnyKeyPath])
+
+  /// The node is a `SyntaxCollection` of the given type.
+  case collection(SyntaxProtocol.Type)
+
+  /// The node can contain a single node with one of the listed types.
+  case choices([SyntaxChoice])
+
+  public var isLayout: Bool {
+    switch self {
+    case .layout: return true
+    default: return false
+    }
+  }
+
+  public var isCollection: Bool {
+    switch self {
+    case .collection: return true
+    default: return false
+    }
+  }
+
+  public var isChoices: Bool {
+    switch self {
+    case .choices: return true
+    default: return false
+    }
+  }
+}
+
 /// A Syntax node represents a tree of nodes with tokens at the leaves.
 /// Each node has accessors for its known children, and allows efficient
 /// iteration over the children through its `children` property.
@@ -136,6 +174,9 @@ public protocol SyntaxProtocol: CustomStringConvertible,
   /// conversion is not possible.
   init?(_ syntaxNode: Syntax)
 
+  /// The statically allowed structure of the syntax node.
+  static var structure: SyntaxNodeStructure { get }
+
   /// Return a name with which the child at the given `index` can be referred to
   /// in diagnostics.
   /// Typically, you want to use `childNameInParent` on the child instead of

Sources/SwiftSyntax/SyntaxBaseNodes.swift.gyb

@@ -138,6 +138,14 @@ public struct ${node.name}: ${node.name}Protocol, SyntaxHashable {
     return Syntax(self).asProtocol(${node.name}Protocol.self)!
   }
 
+  public static var structure: SyntaxNodeStructure {
+    return .choices([
+%     for child_node in [child_node for child_node in SYNTAX_NODES if child_node.base_kind == node.syntax_kind]:
+      .node(${child_node.name}.self),
+%     end
+    ])
+  }
+
   public func childNameForDiagnostics(_ index: SyntaxChildrenIndex) -> String? {
     return Syntax(self).childNameForDiagnostics(index)
   }

Sources/SwiftSyntax/SyntaxCollections.swift.gyb

@@ -18,11 +18,17 @@
 //
 //===----------------------------------------------------------------------===//
 
-public protocol SyntaxCollection: SyntaxProtocol, Sequence {
+public protocol SyntaxCollection: SyntaxProtocol, Sequence where Element: SyntaxProtocol {
   /// The number of elements, `present` or `missing`, in this collection.
   var count: Int { get }
 }
 
+public extension SyntaxCollection {
+  static var structure: SyntaxNodeStructure {
+    return .collection(Element.self)
+  }
+}
+
 % for node in SYNTAX_NODES:
 %   if node.collection_element:
 %     element_node = NODE_MAP.get(node.collection_element)
@@ -75,6 +81,15 @@ public struct ${node.name}: SyntaxCollection, SyntaxHashable {
 %   end
       return nil
     }
+
+    public static var structure: SyntaxNodeStructure {
+      return .choices([
+%         for choice_name in node.collection_element_choices:
+%           choice = NODE_MAP[choice_name]
+        .node(${choice.name}.self),
+%         end
+      ])
+    }
   }
 % else:
   public typealias Element = ${node.collection_element_type}

Sources/SwiftSyntax/SyntaxNodes.swift.gyb.template

@@ -107,6 +107,20 @@ public struct ${node.name}: ${base_type}Protocol, SyntaxHashable {
 %         end
       return nil
     }
+
+    public static var structure: SyntaxNodeStructure {
+      return .choices([
+%         for choice in child.node_choices:
+%           if choice.is_token() and choice.token.text:
+        .token(.${choice.token.swift_kind()}),
+%           elif choice.is_token() and not choice.token.text:
+        .token(.${choice.token.swift_kind()}("")),
+%           else:
+        .node(${choice.type_name}.self),
+%           end
+%         end
+      ])
+    }
   }
 
 %       end
@@ -236,6 +250,14 @@ public struct ${node.name}: ${base_type}Protocol, SyntaxHashable {
   }
 %     end
 
+  public static var structure: SyntaxNodeStructure {
+    return .layout([
+%     for (index, child) in enumerate(node.children):
+      \Self.${child.swift_name},
+%     end
+    ])
+  }
+
   public func childNameForDiagnostics(_ index: SyntaxChildrenIndex) -> String? {
     switch index.data?.indexInParent {
 %     for (index, child) in enumerate(node.children):

Sources/SwiftSyntax/SyntaxOtherNodes.swift

@@ -38,6 +38,10 @@ public struct UnknownSyntax: SyntaxProtocol, SyntaxHashable {
     self.init(data)
   }
 
+  public static var structure: SyntaxNodeStructure {
+    return .layout([])
+  }
+
   public func childNameForDiagnostics(_ index: SyntaxChildrenIndex) -> String? {
     return nil
   }
@@ -200,6 +204,10 @@ public struct TokenSyntax: SyntaxProtocol, SyntaxHashable {
     return raw.totalLength
   }
 
+  public static var structure: SyntaxNodeStructure {
+    return .layout([])
+  }
+
   public func childNameForDiagnostics(_ index: SyntaxChildrenIndex) -> String? {
     return nil
   }