Merge pull request #183 from akyrtzi/asprotocol-for-existentials

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

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