SwiftSyntax: add a mechanism to define traits of syntax nodes to allow abstract access to popular child kinds. NFC (#14668)

Swift syntax APIs lack an abstract way of accessing children. The client has to
down-cast a syntax node to the leaf type to access any of its children. However,
some children are common among different syntax kinds, e.g.
DeclAttributeSyntax and DeclMembers. We should allow an abstract way to
access and modify them, so that clients can avoid logic duplication.

This patch adds a mechanism to define new traits and specify satisfied
traits in specific syntax nodes. A trait is a set of common children
and implemented in Swift as a protocol for syntax nodes to conform to.
As a proof-of-concept, we added two traits for now including DeclGroupSyntax
and BracedSyntax.

Resolves: SR-6931 and SR-6916

Author: nkcsgexi

tools/SwiftSyntax/SyntaxNodes.swift.gyb

@@ -1,6 +1,7 @@
 %{
   # -*- mode: Swift -*-
   from gyb_syntax_support import *
+  from gyb_syntax_support.Traits import TRAITS
   NODE_MAP = create_node_map()
   # Ignore the following admonition it applies to the resulting .swift file only
 }%
@@ -53,6 +54,19 @@ public struct UnknownSyntax: _SyntaxBase {
   }
 }
 
+% for trait in TRAITS:
+public protocol ${trait.trait_name} {
+% for child in trait.children:
+%   ret_type = child.type_name
+%   if child.is_optional:
+%       ret_type += '?'
+%    end
+  var ${child.swift_name}: ${ret_type} { get }
+  func with${child.name}(_ newChild: ${child.type_name}?) -> Self
+% end
+}
+% end
+
 % for node in SYNTAX_NODES:
 %   base_type = node.base_type
 %   if node.is_base():
@@ -61,7 +75,12 @@ public protocol ${node.name}: Syntax {}
 %   elif node.collection_element:
 %     pass
 %   else:
-public struct ${node.name}: ${base_type}, _SyntaxBase, Hashable {
+%     traits_list = ""
+%     if node.traits:
+%       traits_list = ", ".join(node.traits)
+%       traits_list = traits_list + ", "
+%     end
+public struct ${node.name}: ${traits_list} ${base_type}, _SyntaxBase, Hashable {
 %     if node.children:
   enum Cursor: Int {
 %       for child in node.children:

utils/gyb_syntax_support/CommonNodes.py

@@ -32,9 +32,10 @@
 
     # code-block -> '{' stmt-list '}'
     Node('CodeBlock', kind='Syntax',
+         traits=['BracedSyntax'],
          children=[
-             Child('OpenBrace', kind='LeftBraceToken'),
+             Child('LeftBrace', kind='LeftBraceToken'),
              Child('Statements', kind='CodeBlockItemList'),
-             Child('CloseBrace', kind='RightBraceToken'),
+             Child('RightBrace', kind='RightBraceToken'),
          ]),
 ]

utils/gyb_syntax_support/DeclNodes.py

@@ -157,7 +157,7 @@
     #                      generic-where-clause?
     #                     '{' class-members '}'
     # class-name -> identifier
-    Node('ClassDecl', kind='Decl',
+    Node('ClassDecl', kind='Decl', traits=['DeclGroupSyntax'],
          children=[
              Child('Attributes', kind='AttributeList',
                    is_optional=True),
@@ -181,7 +181,7 @@
     #                         generic-where-clause?
     #                         '{' struct-members '}'
     # struct-name -> identifier
-    Node('StructDecl', kind='Decl',
+    Node('StructDecl', kind='Decl', traits=['DeclGroupSyntax'],
          children=[
              Child('Attributes', kind='AttributeList',
                    is_optional=True),
@@ -198,7 +198,7 @@
              Child('Members', kind='MemberDeclBlock'),
          ]),
 
-    Node('ProtocolDecl', kind='Decl',
+    Node('ProtocolDecl', kind='Decl', traits=['DeclGroupSyntax'],
          children=[
              Child('Attributes', kind='AttributeList',
                    is_optional=True),
@@ -219,7 +219,7 @@
     #                            generic-where-clause?
     #                            '{' extension-members '}'
     # extension-name -> identifier
-    Node('ExtensionDecl', kind='Decl',
+    Node('ExtensionDecl', kind='Decl', traits=['DeclGroupSyntax'],
          children=[
              Child('Attributes', kind='AttributeList',
                    is_optional=True),
@@ -234,7 +234,7 @@
              Child('Members', kind='MemberDeclBlock'),
          ]),
 
-    Node('MemberDeclBlock', kind='Syntax',
+    Node('MemberDeclBlock', kind='Syntax', traits=['BracedSyntax'],
          children=[
              Child('LeftBrace', kind='LeftBraceToken'),
              Child('Members', kind='DeclList'),
@@ -464,7 +464,7 @@
 
     Node('AccessorList', kind="SyntaxCollection", element='AccessorDecl'),
 
-    Node('AccessorBlock', kind="Syntax",
+    Node('AccessorBlock', kind="Syntax", traits=['BracedSyntax'],
          children=[
              Child('LeftBrace', kind='LeftBraceToken'),
              Child('AccessorListOrStmtList', kind='Syntax',

utils/gyb_syntax_support/ExprNodes.py

@@ -384,6 +384,7 @@
          ]),
 
     Node('ClosureExpr', kind='Expr',
+         traits=['BracedSyntax'],
          children=[
              Child('LeftBrace', kind='LeftBraceToken'),
              Child('Signature', kind='ClosureSignature', is_optional=True),

utils/gyb_syntax_support/Node.py

@@ -16,12 +16,13 @@ class Node(object):
     subclass.
     """
 
-    def __init__(self, name, kind=None, children=None,
+    def __init__(self, name, kind=None, traits=None, children=None,
                  element=None, element_name=None, element_choices=None):
         self.syntax_kind = name
         self.swift_syntax_kind = lowercase_first_word(name)
         self.name = kind_to_type(self.syntax_kind)
 
+        self.traits = traits or []
         self.children = children or []
         self.base_kind = kind
         self.base_type = kind_to_type(self.base_kind)

utils/gyb_syntax_support/StmtNodes.py

@@ -91,16 +91,17 @@
     # switch-stmt -> identifier? ':'? 'switch' expr '{'
     #   switch-case-list '}' ';'?
     Node('SwitchStmt', kind='Stmt',
+         traits=['BracedSyntax'],
          children=[
              Child('LabelName', kind='IdentifierToken',
                    is_optional=True),
              Child('LabelColon', kind='ColonToken',
                    is_optional=True),
              Child('SwitchKeyword', kind='SwitchToken'),
              Child('Expression', kind='Expr'),
-             Child('OpenBrace', kind='LeftBraceToken'),
+             Child('LeftBrace', kind='LeftBraceToken'),
              Child('Cases', kind='SwitchCaseList'),
-             Child('CloseBrace', kind='RightBraceToken'),
+             Child('RightBrace', kind='RightBraceToken'),
          ]),
 
     # catch-clause-list -> catch-clause catch-clause-list?

utils/gyb_syntax_support/Traits.py

@@ -0,0 +1,24 @@
+from Child import Child
+
+
+class Trait(object):
+    def __init__(self, trait_name, children):
+        self.trait_name = trait_name
+        self.children = children
+
+
+TRAITS = [
+    Trait('DeclGroupSyntax',
+          children=[
+              Child('Attributes', kind='AttributeList', is_optional=True),
+              Child('AccessLevelModifier', kind='DeclModifier',
+                    is_optional=True),
+              Child('Members', kind='MemberDeclBlock'),
+          ]),
+
+    Trait('BracedSyntax',
+          children=[
+              Child('LeftBrace', kind='LeftBraceToken'),
+              Child('RightBrace', kind='RightBraceToken'),
+          ]),
+]