Simlify config handling. Add documentation.

Author: MAJKFL

Sources/SwiftLexicalLookup/Configurations/FileScopeHandlingConfig.swift renamed to Sources/SwiftLexicalLookup/Configurations/FileScopeNameIntroductionStrategy.swift

@@ -13,7 +13,7 @@
 import SwiftSyntax
 
 /// Specifies how names should be introduced at the file scope.
-@_spi(Experimental) public enum FileScopeNameIntroductionStrategy: LookupConfig {
+@_spi(Experimental) public enum FileScopeHandlingConfig {
   /// Default behavior. Names introduced sequentially like in member block
   /// scope up to the first non-declaration after and including which,
   /// the declarations are treated like in code block scope.

Sources/SwiftLexicalLookup/Configurations/LookupConfig.swift

@@ -12,11 +12,12 @@
 
 import Foundation
 
-/// Used to customize lookup behavior.
-@_spi(Experimental) public protocol LookupConfig {}
+@_spi(Experimental) public struct LookupConfig {
+  /// Specifies behaviour of file scope.
+  /// `memberBlockUpToLastDecl` by default.
+  public var fileScopeHandling: FileScopeHandlingConfig = .memberBlockUpToLastDecl
 
-extension LookupConfig {
-  var identifier: ObjectIdentifier {
-    ObjectIdentifier(Self.self)
+  public init(fileScopeHandling: FileScopeHandlingConfig = .memberBlockUpToLastDecl) {
+    self.fileScopeHandling = fileScopeHandling
   }
 }

Sources/SwiftLexicalLookup/Configurations/LookupConfigDictionary.swift

@@ -33,6 +33,11 @@ extension ClosureShorthandParameterSyntax: IdentifiableSyntax {
 
 extension ClosureCaptureSyntax: IdentifiableSyntax {
   @_spi(Experimental) public var identifier: TokenSyntax {
+    /* Doesn't work with closures like:
+     _ = { [y=1+2] in
+       print(y)
+     }
+     */
     expression.as(DeclReferenceExprSyntax.self)!.baseName
   }
 }

Sources/SwiftLexicalLookup/IdentifiableSyntax.swift

@@ -44,9 +44,7 @@ import SwiftSyntax
   /// If set to `nil`, the name is available at any point in scope.
   var accessibleAfter: AbsolutePosition? {
     switch self {
-    case .identifier(_, let absolutePosition):
-      absolutePosition
-    case .declaration(_, let absolutePosition):
+    case .identifier(_, let absolutePosition), .declaration(_, let absolutePosition):
       absolutePosition
     }
   }

Sources/SwiftLexicalLookup/LookupName.swift

@@ -16,30 +16,23 @@ import SwiftSyntax
 @_spi(Experimental) public enum LookupResult {
   /// Scope and the names that matched lookup.
   case fromScope(ScopeSyntax, withNames: [LookupName])
-  /// File scope, names that matched lookup and name introduction
-  /// strategy used for the lookup.
-  case fromFileScope(
-    SourceFileSyntax,
-    withNames: [LookupName],
-    nameIntroductionStrategy: FileScopeNameIntroductionStrategy
-  )
+  /// File scope and names that matched lookup.
+  case fromFileScope(SourceFileSyntax, withNames: [LookupName])
 
   /// Associated scope.
   @_spi(Experimental) public var scope: ScopeSyntax? {
     switch self {
     case .fromScope(let scopeSyntax, _):
       scopeSyntax
-    case .fromFileScope(let fileScopeSyntax, withNames: _, nameIntroductionStrategy: _):
+    case .fromFileScope(let fileScopeSyntax, _):
       fileScopeSyntax
     }
   }
 
   /// Names that matched lookup.
   @_spi(Experimental) public var names: [LookupName] {
     switch self {
-    case .fromScope(_, let names):
-      names
-    case .fromFileScope(_, withNames: let names, nameIntroductionStrategy: _):
+    case .fromScope(_, let names), .fromFileScope(_, let names):
       names
     }
   }

Sources/SwiftLexicalLookup/LookupResult.swift

@@ -24,12 +24,34 @@ extension SyntaxProtocol {
 }
 
 @_spi(Experimental) extension SourceFileSyntax: ScopeSyntax {
+  /// All names introduced in the file scope
+  /// according to the default strategy: `memberBlockUpToLastDecl`.
   public var introducedNames: [LookupName] {
     introducedNames(using: .memberBlockUpToLastDecl)
   }
 
-  public func introducedNames(using nameIntroductionStrategy: FileScopeNameIntroductionStrategy) -> [LookupName] {
-    switch nameIntroductionStrategy {
+  /// All names introduced in the file scope
+  /// using the provided configuration.
+  ///
+  /// Example usage:
+  /// ```swift
+  /// class a {}
+  /// class b {
+  ///   // <--
+  /// }
+  /// let c = 0
+  /// class d {}
+  /// if true {}
+  /// class e {}
+  /// let f = 0
+  /// ```
+  /// During lookup, according to different configurations,
+  /// names available at the marked place are:
+  /// - for `fileScopeNameIntroductionStrategy` - a, b, c, d
+  /// - for `memberBlock` - a, b, c, d, e, f
+  /// - for `codeBlock` - a
+  public func introducedNames(using fileScopeHandling: FileScopeHandlingConfig) -> [LookupName] {
+    switch fileScopeHandling {
     case .memberBlockUpToLastDecl:
       var encounteredNonDeclaration = false
 
@@ -58,23 +80,43 @@ extension SyntaxProtocol {
     }
   }
 
+  /// Returns names matching lookup using provided file
+  /// scope handling configuration (by default: `memberBlockUpToLastDecl`).
+  ///
+  /// Example usage:
+  /// ```swift
+  /// class a {}
+  /// class b {
+  ///   // <--
+  /// }
+  /// let c = 0
+  /// class d {}
+  /// if true {}
+  /// class e {}
+  /// let f = 0
+  /// ```
+  /// According to different configurations,
+  /// names available at the marked place are:
+  /// - for `fileScopeNameIntroductionStrategy` - a, b, c, d
+  /// - for `memberBlock` - a, b, c, d, e, f
+  /// - for `codeBlock` - a
   public func lookup(
     for name: String?,
     at syntax: SyntaxProtocol,
-    with configDict: LookupConfigDictionary
+    with config: LookupConfig
   ) -> [LookupResult] {
-    let nameIntroductionStrategy = configDict[FileScopeNameIntroductionStrategy.self] ?? .memberBlockUpToLastDecl
-
-    let names = introducedNames(using: nameIntroductionStrategy)
+    let names = introducedNames(using: config.fileScopeHandling)
       .filter { introducedName in
         introducedName.isAccessible(at: syntax) && (name == nil || introducedName.refersTo(name!))
       }
 
-    return [.fromFileScope(self, withNames: names, nameIntroductionStrategy: nameIntroductionStrategy)]
+    return [.fromFileScope(self, withNames: names)]
   }
 }
 
 @_spi(Experimental) extension CodeBlockSyntax: ScopeSyntax {
+  /// Names introduced in the code block scope
+  /// accessible after their declaration.
   public var introducedNames: [LookupName] {
     statements.flatMap { codeBlockItem in
       LookupName.getNames(from: codeBlockItem.item, accessibleAfter: codeBlockItem.endPosition)
@@ -83,12 +125,24 @@ extension SyntaxProtocol {
 }
 
 @_spi(Experimental) extension ForStmtSyntax: ScopeSyntax {
+  /// Names introduced in the `for` body.
   public var introducedNames: [LookupName] {
     LookupName.getNames(from: pattern)
   }
 }
 
 @_spi(Experimental) extension ClosureExprSyntax: ScopeSyntax {
+  /// All names introduced by the closure signature.
+  /// Could be closure captures or (shorthand) parameters.
+  ///
+  /// Example:
+  /// ```swift
+  /// let x = { [weak self, a] b, _ in
+  ///   // <--
+  /// }
+  /// ```
+  /// During lookup, names available at the marked place are:
+  /// `self`, a, b.
   public var introducedNames: [LookupName] {
     let captureNames =
       signature?.capture?.children(viewMode: .sourceAccurate).flatMap { child in
@@ -117,6 +171,7 @@ extension SyntaxProtocol {
 }
 
 @_spi(Experimental) extension WhileStmtSyntax: ScopeSyntax {
+  /// Names introduced by the `while` loop by its conditions.
   public var introducedNames: [LookupName] {
     conditions.flatMap { element in
       LookupName.getNames(from: element.condition)
@@ -125,11 +180,28 @@ extension SyntaxProtocol {
 }
 
 @_spi(Experimental) extension IfExprSyntax: ScopeSyntax {
+  /// Parent scope, omitting ancestor `if` statements if part of their `else if` clause.
   public var parentScope: ScopeSyntax? {
     getParent(for: self.parent, previousIfElse: self.elseKeyword == nil)
   }
 
-  /// Finds the parent scope, omitting parent `if` statements if part of their `else if` clause.
+  /// Finds parent scope, omitting ancestor `if` statements if part of their `else if` clause.
+  ///
+  /// Example:
+  /// ```swift
+  /// func foo() {
+  ///   if let a = x {
+  ///     // <--
+  ///   } else if let b {
+  ///     // <--
+  ///   } else if y == 1 {
+  ///     // <--
+  ///   }
+  /// }
+  /// ```
+  /// For each of the marked scopes, resulting parent
+  /// is the enclosing code block scope associated with
+  /// the function body.
   private func getParent(for syntax: Syntax?, previousIfElse: Bool) -> ScopeSyntax? {
     guard let syntax else { return nil }
 
@@ -144,26 +216,40 @@ extension SyntaxProtocol {
     }
   }
 
+  /// Names introduced by the `if` optional binding conditions.
   public var introducedNames: [LookupName] {
     conditions.flatMap { element in
       LookupName.getNames(from: element.condition, accessibleAfter: element.endPosition)
     }
   }
 
+  /// Returns names matching lookup.
+  /// Lookup triggered from inside of `else`
+  /// clause is immediately forwarded to parent scope.
+  ///
+  /// Example:
+  /// ```swift
+  /// if let a = x {
+  ///   // <-- a is visible here
+  /// } else {
+  ///   // <-- a is not visible here
+  /// }
+  /// ```
   public func lookup(
     for name: String?,
     at syntax: SyntaxProtocol,
-    with configDict: LookupConfigDictionary
+    with config: LookupConfig
   ) -> [LookupResult] {
     if let elseBody, elseBody.position <= syntax.position, elseBody.endPosition >= syntax.position {
-      lookupInParent(for: name, at: syntax, with: configDict)
+      lookupInParent(for: name, at: syntax, with: config)
     } else {
-      defaultLookupImplementation(for: name, at: syntax, with: configDict)
+      defaultLookupImplementation(for: name, at: syntax, with: config)
     }
   }
 }
 
 @_spi(Experimental) extension MemberBlockSyntax: ScopeSyntax {
+  /// All names introduced by members of this member scope.
   public var introducedNames: [LookupName] {
     members.flatMap { member in
       LookupName.getNames(from: member.decl)
@@ -172,19 +258,32 @@ extension SyntaxProtocol {
 }
 
 @_spi(Experimental) extension GuardStmtSyntax: ScopeSyntax {
+  /// Guard doesn't introduce any names to its children.
+  /// It's always empty.
   public var introducedNames: [LookupName] {
     []
   }
 
+  /// Returns names matching lookup.
+  /// Lookup triggered from inside of `else`
+  /// clause is immediately forwarded to parent scope.
+  ///
+  /// Example:
+  /// ```swift
+  /// guard let a = x else {
+  ///   return // a is not visible here
+  /// }
+  /// // a is visible here
+  /// ```
   public func lookup(
     for name: String?,
     at syntax: SyntaxProtocol,
-    with configDict: LookupConfigDictionary
+    with config: LookupConfig
   ) -> [LookupResult] {
     if body.position <= syntax.position && body.endPosition >= syntax.position {
-      lookupInParent(for: name, at: self, with: configDict)
+      lookupInParent(for: name, at: self, with: config)
     } else {
-      defaultLookupImplementation(for: name, at: syntax, with: configDict)
+      defaultLookupImplementation(for: name, at: syntax, with: config)
     }
   }
 }