[Syntax] Rename the as conversion functions that incur existential conversions to asProtocol

The intention is to make it clear in the API usage where existential conversion overhead exists,
allowing performance critical clients to eliminate use of existentials where possible.

Also add a note in README file to clarify that the API is designed with performance in mind.

Author: akyrtzi

Changelog.md

@@ -88,7 +88,7 @@ For increased performance, the modelling of the syntax node hierarchy has been s
 
   stays the same. `ExprSyntax` is now a struct and not a protocol. See below on how to create an `ExprSyntax`.
 
-  **Extening a type**
+  **Extending a type**
 
   ```swift
   // Before
@@ -118,8 +118,8 @@ For increased performance, the modelling of the syntax node hierarchy has been s
   ```swift
   let identifierExprSyntax: IdentifierExprSyntax = /* ... */
   let node = Syntax(identifierExprSyntax)
-  node.as(SyntaxProtocol.self) // returns a IdentifierExprSyntax with static type SyntaxProtocol
-  node.as(ExprSyntaxProtocol.self) // returns a IdentifierExprSyntax with static type ExprSyntaxProtocol?
+  node.asProtocol(SyntaxProtocol.self) // returns a IdentifierExprSyntax with static type SyntaxProtocol
+  node.asProtocol(ExprSyntaxProtocol.self) // returns a IdentifierExprSyntax with static type ExprSyntaxProtocol?
   ```
 
 

README.md

@@ -5,6 +5,8 @@ SwiftSyntax is a set of Swift bindings for the
 allows for Swift tools to parse, inspect, generate, and transform Swift source
 code.
 
+Its API is designed for performance critical applications. It uses value types almost exclusively and aims to avoid existential conversions where possible.
+
 > Note: SwiftSyntax is still in development, and the API is not guaranteed to
 > be stable. It's subject to change without warning.
 

Sources/SwiftSyntax/Misc.swift.gyb

@@ -42,13 +42,15 @@ extension SyntaxNode {
 extension Syntax {
   /// Syntax nodes always conform to SyntaxProtocol. This API is just added
   /// for consistency.
+  /// Note that this will incur an existential conversion.
   @available(*, deprecated, message: "Expression always evaluates to true")
-  public func `is`(_: SyntaxProtocol.Protocol) -> Bool {
+  public func isProtocol(_: SyntaxProtocol.Protocol) -> Bool {
     return true
   }
 
   /// Return the non-type erased version of this syntax node.
-  public func `as`(_: SyntaxProtocol.Protocol) -> SyntaxProtocol {
+  /// Note that this will incur an existential conversion.
+  public func asProtocol(_: SyntaxProtocol.Protocol) -> SyntaxProtocol {
     switch self.as(SyntaxEnum.self) {
     case .token(let node):
       return node

Sources/SwiftSyntax/Syntax.swift

@@ -26,7 +26,7 @@ public struct Syntax: SyntaxProtocol, SyntaxHashable {
 
   public func _validateLayout() {
     // Check the layout of the concrete type
-    return self.as(SyntaxProtocol.self)._validateLayout()
+    return self.asProtocol(SyntaxProtocol.self)._validateLayout()
   }
 
   /// Create a `Syntax` node from a specialized syntax node.
@@ -64,7 +64,7 @@ extension Syntax: CustomReflectable {
   /// Reconstructs the real syntax type for this type from the node's kind and
   /// provides a mirror that reflects this type.
   public var customMirror: Mirror {
-    return Mirror(reflecting: self.as(SyntaxProtocol.self))
+    return Mirror(reflecting: self.asProtocol(SyntaxProtocol.self))
   }
 }
 

Sources/SwiftSyntax/SyntaxBaseNodes.swift.gyb

@@ -32,14 +32,16 @@ public protocol ${node.name}Protocol: ${base_type}Protocol {}
 public extension Syntax {
   /// Check whether the non-type erased version of this syntax node conforms to 
   /// ${node.name}Protocol. 
-  func `is`(_: ${node.name}Protocol.Protocol) -> Bool {
-    return self.as(${node.name}Protocol.self) != nil
+  /// Note that this will incur an existential conversion.
+  func isProtocol(_: ${node.name}Protocol.Protocol) -> Bool {
+    return self.asProtocol(${node.name}Protocol.self) != nil
   }
 
   /// Return the non-type erased version of this syntax node if it conforms to 
   /// ${node.name}Protocol. Otherwise return nil.
-  func `as`(_: ${node.name}Protocol.Protocol) -> ${node.name}Protocol? {
-    return self.as(SyntaxProtocol.self) as? ${node.name}Protocol
+  /// Note that this will incur an existential conversion.
+  func asProtocol(_: ${node.name}Protocol.Protocol) -> ${node.name}Protocol? {
+    return self.asProtocol(SyntaxProtocol.self) as? ${node.name}Protocol
   }
 }
 
@@ -105,22 +107,24 @@ public struct ${node.name}: ${node.name}Protocol, SyntaxHashable {
 
   /// Syntax nodes always conform to `${node.name}Protocol`. This API is just
   /// added for consistency.
+  /// Note that this will incur an existential conversion.
   @available(*, deprecated, message: "Expression always evaluates to true")
-  public func `is`(_: ${node.name}Protocol.Protocol) -> Bool {
+  public func isProtocol(_: ${node.name}Protocol.Protocol) -> Bool {
     return true
   }
 
   /// Return the non-type erased version of this syntax node.
-  public func `as`(_: ${node.name}Protocol.Protocol) -> ${node.name}Protocol {
-    return Syntax(self).as(${node.name}Protocol.self)!
+  /// Note that this will incur an existential conversion.
+  public func asProtocol(_: ${node.name}Protocol.Protocol) -> ${node.name}Protocol {
+    return Syntax(self).asProtocol(${node.name}Protocol.self)!
   }
 }
 
 extension ${node.name}: CustomReflectable {
   /// Reconstructs the real syntax type for this type from the node's kind and
   /// provides a mirror that reflects this type.
   public var customMirror: Mirror {
-    return Mirror(reflecting: Syntax(self).as(SyntaxProtocol.self))
+    return Mirror(reflecting: Syntax(self).asProtocol(SyntaxProtocol.self))
   }
 }
 

Sources/SwiftSyntax/SyntaxNodes.swift.gyb.template

@@ -189,9 +189,9 @@ extension ${node.name}: CustomReflectable {
     return Mirror(self, children: [
 %     for child in node.children:
 %       if child.is_optional:
-      "${child.swift_name}": ${child.swift_name}.map(Syntax.init)?.as(SyntaxProtocol.self) as Any,
+      "${child.swift_name}": ${child.swift_name}.map(Syntax.init)?.asProtocol(SyntaxProtocol.self) as Any,
 %       else:
-      "${child.swift_name}": Syntax(${child.swift_name}).as(SyntaxProtocol.self),
+      "${child.swift_name}": Syntax(${child.swift_name}).asProtocol(SyntaxProtocol.self),
 %       end
 %     end
     ])

Sources/SwiftSyntax/SyntaxTraits.swift.gyb

@@ -36,14 +36,16 @@ public protocol ${trait.trait_name}Syntax: SyntaxProtocol {
 public extension SyntaxProtocol {
   /// Check whether the non-type erased version of this syntax node conforms to 
   /// `${trait.trait_name}Syntax`. 
-  func `is`(_: ${trait.trait_name}Syntax.Protocol) -> Bool {
-    return self.as(${trait.trait_name}Syntax.self) != nil
+  /// Note that this will incur an existential conversion.
+  func isProtocol(_: ${trait.trait_name}Syntax.Protocol) -> Bool {
+    return self.asProtocol(${trait.trait_name}Syntax.self) != nil
   }
 
   /// Return the non-type erased version of this syntax node if it conforms to 
   /// `${trait.trait_name}Syntax`. Otherwise return `nil`.
-  func `as`(_: ${trait.trait_name}Syntax.Protocol) -> ${trait.trait_name}Syntax? {
-    return Syntax(self).as(SyntaxProtocol.self) as? ${trait.trait_name}Syntax
+  /// Note that this will incur an existential conversion.
+  func asProtocol(_: ${trait.trait_name}Syntax.Protocol) -> ${trait.trait_name}Syntax? {
+    return Syntax(self).asProtocol(SyntaxProtocol.self) as? ${trait.trait_name}Syntax
   }
 }
 

Sources/SwiftSyntax/gyb_generated/Misc.swift

@@ -1393,13 +1393,15 @@ extension SyntaxNode {
 extension Syntax {
   /// Syntax nodes always conform to SyntaxProtocol. This API is just added
   /// for consistency.
+  /// Note that this will incur an existential conversion.
   @available(*, deprecated, message: "Expression always evaluates to true")
-  public func `is`(_: SyntaxProtocol.Protocol) -> Bool {
+  public func isProtocol(_: SyntaxProtocol.Protocol) -> Bool {
     return true
   }
 
   /// Return the non-type erased version of this syntax node.
-  public func `as`(_: SyntaxProtocol.Protocol) -> SyntaxProtocol {
+  /// Note that this will incur an existential conversion.
+  public func asProtocol(_: SyntaxProtocol.Protocol) -> SyntaxProtocol {
     switch self.as(SyntaxEnum.self) {
     case .token(let node):
       return node