diff --git a/.spi.yml b/.spi.yml index 7572213ba27..5b4aaf55d5b 100644 --- a/.spi.yml +++ b/.spi.yml @@ -12,6 +12,7 @@ builder: - SwiftCompilerPlugin - SwiftDiagnostics - SwiftIDEUtils + - SwiftLexicalLookup - SwiftOperators - SwiftParser - SwiftParserDiagnostics diff --git a/Package.swift b/Package.swift index 799657019aa..99a11c22bfa 100644 --- a/Package.swift +++ b/Package.swift @@ -17,6 +17,7 @@ let package = Package( .library(name: "SwiftCompilerPlugin", targets: ["SwiftCompilerPlugin"]), .library(name: "SwiftDiagnostics", targets: ["SwiftDiagnostics"]), .library(name: "SwiftIDEUtils", targets: ["SwiftIDEUtils"]), + .library(name: "SwiftLexicalLookup", targets: ["SwiftLexicalLookup"]), .library(name: "SwiftOperators", targets: ["SwiftOperators"]), .library(name: "SwiftParser", targets: ["SwiftParser"]), .library(name: "SwiftParserDiagnostics", targets: ["SwiftParserDiagnostics"]), @@ -137,6 +138,18 @@ let package = Package( dependencies: ["_SwiftSyntaxTestSupport", "SwiftIDEUtils", "SwiftParser", "SwiftSyntax"] ), + // MARK: SwiftLexicalLookup + + .target( + name: "SwiftLexicalLookup", + dependencies: ["SwiftSyntax"] + ), + + .testTarget( + name: "SwiftLexicalLookupTest", + dependencies: ["_SwiftSyntaxTestSupport", "SwiftLexicalLookup"] + ), + // MARK: SwiftLibraryPluginProvider .target( diff --git a/Release Notes/601.md b/Release Notes/601.md index 5586443e05d..26499144348 100644 --- a/Release Notes/601.md +++ b/Release Notes/601.md @@ -6,6 +6,10 @@ - Description: Allows retrieving the represented literal value when valid. - Issue: https://github.com/apple/swift-syntax/issues/405 - Pull Request: https://github.com/apple/swift-syntax/pull/2605 + +- `SyntaxProtocol` now has a method `ancestorOrSelf`. + - Description: Returns the node or the first ancestor that satisfies `condition`. + - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2696 ## API Behavior Changes diff --git a/Sources/SwiftBasicFormat/BasicFormat.swift b/Sources/SwiftBasicFormat/BasicFormat.swift index 2e50a4e9c82..67029ca41d3 100644 --- a/Sources/SwiftBasicFormat/BasicFormat.swift +++ b/Sources/SwiftBasicFormat/BasicFormat.swift @@ -676,17 +676,3 @@ fileprivate extension TokenSyntax { } } } - -fileprivate extension SyntaxProtocol { - /// Returns this node or the first ancestor that satisfies `condition`. - func ancestorOrSelf(mapping map: (Syntax) -> T?) -> T? { - var walk: Syntax? = Syntax(self) - while let unwrappedParent = walk { - if let mapped = map(unwrappedParent) { - return mapped - } - walk = unwrappedParent.parent - } - return nil - } -} diff --git a/Sources/SwiftLexicalLookup/SimpleLookupQueries.swift b/Sources/SwiftLexicalLookup/SimpleLookupQueries.swift new file mode 100644 index 00000000000..f530c87856e --- /dev/null +++ b/Sources/SwiftLexicalLookup/SimpleLookupQueries.swift @@ -0,0 +1,213 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +import Foundation +import SwiftSyntax + +extension SyntaxProtocol { + /// Returns all labeled statements available at a particular syntax node. + /// + /// - Returns: Available labeled statements at a particular syntax node + /// in the exact order they appear in the source code, starting with the innermost statement. + /// + /// Example usage: + /// ```swift + /// one: while cond1 { + /// func foo() { + /// two: while cond2 { + /// three: while cond3 { + /// break // 1 + /// } + /// break // 2 + /// } + /// } + /// break // 3 + /// } + /// ``` + /// When calling this function at the first `break`, it returns `three` and `two` in this exact order. + /// For the second `break`, it returns only `two`. + /// The results don't include `one`, which is unavailable at both locations due to the encapsulating function body. + /// For `break` numbered 3, the result is `one`, as it's outside the function body and within the labeled statement. + /// The function returns an empty array when there are no available labeled statements. + @_spi(Experimental) public func lookupLabeledStmts() -> [LabeledStmtSyntax] { + collectNodesOfTypeUpToFunctionBoundary(LabeledStmtSyntax.self) + } + + /// Returns the catch node responsible for handling an error thrown at a particular syntax node. + /// + /// - Returns: The catch node responsible for handling an error thrown at the lookup source node. + /// This could be a `do` statement, `try?`, `try!`, `init`, `deinit`, accessors, closures, or function declarations. + /// + /// Example usage: + /// ```swift + /// func x() { + /// do { + /// try foo() + /// try? bar() + /// } catch { + /// throw error + /// } + /// } + /// ``` + /// When calling this function on `foo`, it returns the `do` statement. + /// Calling the function on `bar` results in `try?`. + /// When used on `error`, the function returns the function declaration `x`. + /// The function returns `nil` when there's no available catch node. + @_spi(Experimental) public func lookupCatchNode() -> Syntax? { + lookupCatchNodeHelper(traversedCatchClause: false) + } + + // MARK: - lookupCatchNode + + /// Given syntax node location, finds where an error could be caught. If `traverseCatchClause` is set to `true` lookup will skip the next do statement. + private func lookupCatchNodeHelper(traversedCatchClause: Bool) -> Syntax? { + guard let parent else { return nil } + + switch parent.as(SyntaxEnum.self) { + case .doStmt: + if traversedCatchClause { + return parent.lookupCatchNodeHelper(traversedCatchClause: false) + } else { + return parent + } + case .catchClause: + return parent.lookupCatchNodeHelper(traversedCatchClause: true) + case .tryExpr(let tryExpr): + if tryExpr.questionOrExclamationMark != nil { + return parent + } else { + return parent.lookupCatchNodeHelper(traversedCatchClause: traversedCatchClause) + } + case .functionDecl, .accessorDecl, .initializerDecl, .deinitializerDecl, .closureExpr: + return parent + case .exprList(let exprList): + if let tryExpr = exprList.first?.as(TryExprSyntax.self), tryExpr.questionOrExclamationMark != nil { + return Syntax(tryExpr) + } + return parent.lookupCatchNodeHelper(traversedCatchClause: traversedCatchClause) + default: + return parent.lookupCatchNodeHelper(traversedCatchClause: traversedCatchClause) + } + } + + // MARK: - walkParentTree helper methods + + /// Returns the innermost node of the specified type up to a function boundary. + fileprivate func innermostNodeOfTypeUpToFunctionBoundary( + _ type: T.Type + ) -> T? { + collectNodesOfTypeUpToFunctionBoundary(type, stopWithFirstMatch: true).first + } + + /// Collect syntax nodes matching the collection type up until encountering one of the specified syntax nodes. The nodes in the array are inside out, with the innermost node being the first. + fileprivate func collectNodesOfTypeUpToFunctionBoundary( + _ type: T.Type, + stopWithFirstMatch: Bool = false + ) -> [T] { + collectNodes( + ofType: type, + upTo: [ + MemberBlockSyntax.self, + FunctionDeclSyntax.self, + InitializerDeclSyntax.self, + DeinitializerDeclSyntax.self, + AccessorDeclSyntax.self, + ClosureExprSyntax.self, + SubscriptDeclSyntax.self, + ], + stopWithFirstMatch: stopWithFirstMatch + ) + } + + /// Callect syntax nodes matching the collection type up until encountering one of the specified syntax nodes. + private func collectNodes( + ofType type: T.Type, + upTo stopAt: [SyntaxProtocol.Type], + stopWithFirstMatch: Bool = false + ) -> [T] { + var matches: [T] = [] + var nextSyntax: Syntax? = Syntax(self) + while let currentSyntax = nextSyntax { + if stopAt.contains(where: { currentSyntax.is($0) }) { + break + } + + if let matchedSyntax = currentSyntax.as(T.self) { + matches.append(matchedSyntax) + if stopWithFirstMatch { + break + } + } + + nextSyntax = currentSyntax.parent + } + + return matches + } +} + +extension FallThroughStmtSyntax { + /// Returns the source and destination of a `fallthrough`. + /// + /// - Returns: `source` as the switch case that encapsulates the `fallthrough` keyword and + /// `destination` as the switch case that the `fallthrough` directs to. + /// + /// Example usage: + /// ```swift + /// switch value { + /// case 2: + /// doSomething() + /// fallthrough + /// case 1: + /// doSomethingElse() + /// default: + /// break + /// } + /// ``` + /// When calling this function at the `fallthrough`, it returns `case 2` and `case 1` in this exact order. + /// The `nil` results handle ill-formed code: there's no `source` if the `fallthrough` is outside of a case. + /// There's no `destination` if there is no case or `default` after the source case. + @_spi(Experimental) public func lookupFallthroughSourceAndDestintation() + -> (source: SwitchCaseSyntax?, destination: SwitchCaseSyntax?) + { + guard + let originalSwitchCase = innermostNodeOfTypeUpToFunctionBoundary( + SwitchCaseSyntax.self + ) + else { + return (nil, nil) + } + + let nextSwitchCase = lookupNextSwitchCase(at: originalSwitchCase) + + return (originalSwitchCase, nextSwitchCase) + } + + /// Given a switch case, returns the case that follows according to the parent. + private func lookupNextSwitchCase(at switchCaseSyntax: SwitchCaseSyntax) -> SwitchCaseSyntax? { + guard let switchCaseListSyntax = switchCaseSyntax.parent?.as(SwitchCaseListSyntax.self) else { return nil } + + var visitedOriginalCase = false + + for child in switchCaseListSyntax.children(viewMode: .sourceAccurate) { + if let thisCase = child.as(SwitchCaseSyntax.self) { + if thisCase.id == switchCaseSyntax.id { + visitedOriginalCase = true + } else if visitedOriginalCase { + return thisCase + } + } + } + + return nil + } +} diff --git a/Sources/SwiftParserDiagnostics/SyntaxExtensions.swift b/Sources/SwiftParserDiagnostics/SyntaxExtensions.swift index 38ee98bbe30..505c90e0a3f 100644 --- a/Sources/SwiftParserDiagnostics/SyntaxExtensions.swift +++ b/Sources/SwiftParserDiagnostics/SyntaxExtensions.swift @@ -119,18 +119,6 @@ extension SyntaxProtocol { } } - /// Returns this node or the first ancestor that satisfies `condition`. - func ancestorOrSelf(mapping map: (Syntax) -> T?) -> T? { - var walk: Syntax? = Syntax(self) - while let unwrappedParent = walk { - if let mapped = map(unwrappedParent) { - return mapped - } - walk = unwrappedParent.parent - } - return nil - } - /// Returns `true` if the next token's leading trivia should be made leading trivia /// of this mode, when it is switched from being missing to present. var shouldBeInsertedAfterNextTokenTrivia: Bool { diff --git a/Sources/SwiftSyntax/SyntaxProtocol.swift b/Sources/SwiftSyntax/SyntaxProtocol.swift index dcdb3be4b30..d2cc8d58129 100644 --- a/Sources/SwiftSyntax/SyntaxProtocol.swift +++ b/Sources/SwiftSyntax/SyntaxProtocol.swift @@ -186,7 +186,7 @@ extension SyntaxProtocol { } } -// MARK: Children / parent +// MARK: Children / parent / ancestor extension SyntaxProtocol { /// A sequence over the children of this node. @@ -238,6 +238,18 @@ extension SyntaxProtocol { public var previousToken: TokenSyntax? { return self.previousToken(viewMode: .sourceAccurate) } + + /// Returns this node or the first ancestor that satisfies `condition`. + public func ancestorOrSelf(mapping map: (Syntax) -> T?) -> T? { + var walk: Syntax? = Syntax(self) + while let unwrappedParent = walk { + if let mapped = map(unwrappedParent) { + return mapped + } + walk = unwrappedParent.parent + } + return nil + } } // MARK: Accessing tokens diff --git a/Tests/SwiftLexicalLookupTest/Assertions.swift b/Tests/SwiftLexicalLookupTest/Assertions.swift new file mode 100644 index 00000000000..d4126c02a1d --- /dev/null +++ b/Tests/SwiftLexicalLookupTest/Assertions.swift @@ -0,0 +1,83 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +import Foundation +@_spi(Experimental) import SwiftLexicalLookup +import SwiftParser +import SwiftSyntax +import XCTest +import _SwiftSyntaxTestSupport + +/// `methodUnderTest` is called with the token at every position marker in the keys of `expected`. It then asserts that the positions of the syntax nodes returned by `methodUnderTest` are the values in `expected`. +func assertLexicalScopeQuery( + source: String, + methodUnderTest: (TokenSyntax) -> ([SyntaxProtocol?]), + expected: [String: [String?]] +) { + // Extract markers + let (markerDict, textWithoutMarkers) = extractMarkers(source) + + // Parse the test source + var parser = Parser(textWithoutMarkers) + let sourceFileSyntax = SourceFileSyntax.parse(from: &parser) + + // Iterate through the expected results + for (marker, expectedMarkers) in expected { + // Extract a test argument + guard let position = markerDict[marker], + let testArgument = sourceFileSyntax.token(at: AbsolutePosition(utf8Offset: position)) + else { + XCTFail("Could not find token at location \(marker)") + continue + } + + // Execute the tested method + let result = methodUnderTest(testArgument) + + // Extract the expected results for the test argument + let expectedValues: [AbsolutePosition?] = expectedMarkers.map { expectedMarker in + guard let expectedMarker else { return nil } + + guard let expectedPosition = markerDict[expectedMarker] + else { + XCTFail("Could not find token at location \(marker)") + return nil + } + + return AbsolutePosition(utf8Offset: expectedPosition) + } + + // Compare number of actual results to the number of expected results + if result.count != expectedValues.count { + XCTFail( + "For marker \(marker), actual number of elements: \(result.count) doesn't match the expected: \(expectedValues.count)" + ) + } + + // Assert validity of the output + for (actual, expected) in zip(result, expectedValues) { + if actual == nil && expected == nil { continue } + + guard let actual, let expected else { + XCTFail( + "For marker \(marker), actual result: \(actual?.description ?? "nil"), expected position: \(expected.debugDescription)" + ) + continue + } + + XCTAssert( + actual.positionAfterSkippingLeadingTrivia == expected, + "For marker \(marker), actual result: \(actual.description) doesn't match expected value: \(sourceFileSyntax.token(at: expected) ?? "nil")" + ) + } + } +} diff --git a/Tests/SwiftLexicalLookupTest/SimpleQueryTests.swift b/Tests/SwiftLexicalLookupTest/SimpleQueryTests.swift new file mode 100644 index 00000000000..a72269e9bbb --- /dev/null +++ b/Tests/SwiftLexicalLookupTest/SimpleQueryTests.swift @@ -0,0 +1,200 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +import Foundation +@_spi(Experimental) import SwiftLexicalLookup +import SwiftSyntax +import XCTest + +final class testSimpleQueries: XCTestCase { + func testLabeledStmtLookupThreeNested() { + assertLexicalScopeQuery( + source: """ + 1️⃣one: for i in 1..<10 { + while true { + 2️⃣two: do { + 3️⃣break one + } while true + } + 4️⃣break + } + """, + methodUnderTest: { argument in + argument.lookupLabeledStmts() + }, + expected: ["3️⃣": ["2️⃣", "1️⃣"], "4️⃣": ["1️⃣"]] + ) + } + + func testNoLabeledStatements() { + assertLexicalScopeQuery( + source: """ + while true { + 1️⃣break + } + """, + methodUnderTest: { argument in + argument.lookupLabeledStmts() + }, + expected: ["1️⃣": []] + ) + } + + func testLabeledStmtLookupClassNestedWithinLoop() { + assertLexicalScopeQuery( + source: """ + 1️⃣one: while true { + class a { + func foo() { + 2️⃣two: while true { + 3️⃣break + } + } + } + 4️⃣break + } + """, + methodUnderTest: { argument in + argument.lookupLabeledStmts() + }, + expected: ["3️⃣": ["2️⃣"], "4️⃣": ["1️⃣"]] + ) + } + + func testLabeledStmtLookupClosureNestedWithinLoop() { + assertLexicalScopeQuery( + source: """ + 1️⃣one: while true { + var a = { + 2️⃣two: while true { + 3️⃣break + } + } + 4️⃣break + } + """, + methodUnderTest: { argument in + argument.lookupLabeledStmts() + }, + expected: ["3️⃣": ["2️⃣"], "4️⃣": ["1️⃣"]] + ) + } + + func testLabeledStmtLookupFunctionNestedWithinLoop() { + assertLexicalScopeQuery( + source: """ + 1️⃣one: while true { + func foo() { + 2️⃣two: while true { + 3️⃣break + } + } + 4️⃣break + } + """, + methodUnderTest: { argument in + argument.lookupLabeledStmts() + }, + expected: ["3️⃣": ["2️⃣"], "4️⃣": ["1️⃣"]] + ) + } + + func testLookupFallthroughDestination() { + assertLexicalScopeQuery( + source: """ + func foo() { + 7️⃣fallthrough + } + + switch a { + 1️⃣case 1: + 2️⃣fallthrough + 3️⃣case 2: + 4️⃣fallthrough + 5️⃣default: + 6️⃣fallthrough + } + """, + methodUnderTest: { argument in + guard let fallthroughStmt = argument.ancestorOrSelf(mapping: { $0.as(FallThroughStmtSyntax.self) }) else { + return [] + } + let result = fallthroughStmt.lookupFallthroughSourceAndDestintation() + return [result.source, result.destination] + }, + expected: ["2️⃣": ["1️⃣", "3️⃣"], "4️⃣": ["3️⃣", "5️⃣"], "6️⃣": ["5️⃣", nil], "7️⃣": [nil, nil]] + ) + } + + func testLookupCatchNode() { + assertLexicalScopeQuery( + source: """ + 1️⃣func foo() throws { + 2️⃣do { + try 3️⃣f() + 4️⃣try? 5️⃣f() + } catch { + throw 6️⃣error + } + } + + 8️⃣func bar() { + throw 7️⃣f() + } + """, + methodUnderTest: { argument in + return [argument.lookupCatchNode()] + }, + expected: ["3️⃣": ["2️⃣"], "5️⃣": ["4️⃣"], "6️⃣": ["1️⃣"], "7️⃣": ["8️⃣"]] + ) + } + + func testLookupCatchNodeWithNestedDoCatch() { + assertLexicalScopeQuery( + source: """ + 1️⃣func foo() rethrows { + 2️⃣do { + 3️⃣do { + try 4️⃣f() + } catch { + try 5️⃣f() + } + } catch { + 6️⃣try! 7️⃣f() + throw 8️⃣f() + } + } + """, + methodUnderTest: { argument in + [argument.lookupCatchNode()] + }, + expected: ["4️⃣": ["3️⃣"], "5️⃣": ["2️⃣"], "7️⃣": ["6️⃣"], "8️⃣": ["1️⃣"]] + ) + } + + func testCatchBlockLookupFromWithinExpressionList() { + assertLexicalScopeQuery( + source: """ + 1️⃣do { + try 2️⃣x + 3️⃣y + 4️⃣z + 5️⃣try! 6️⃣x + 7️⃣y + 8️⃣z + } catch { + print(error) + } + """, + methodUnderTest: { argument in + [argument.lookupCatchNode()] + }, + expected: ["2️⃣": ["1️⃣"], "3️⃣": ["1️⃣"], "4️⃣": ["1️⃣"], "6️⃣": ["5️⃣"], "7️⃣": ["5️⃣"], "8️⃣": ["5️⃣"]] + ) + } +}