Merge pull request groue#1764 from groue/dev/fts-pattern-initializers

Make it possible to create a raw FTS5Pattern without any database connection

Author: groue

GRDB/FTS/FTS5Pattern.swift

@@ -7,8 +7,9 @@
 ///
 /// ### Creating Raw FTS5 Patterns
 ///
+/// - ``init(rawPattern:allowedColumns:)``
 /// - ``Database/makeFTS5Pattern(rawPattern:forTable:)``
-/// 
+///
 /// ### Creating FTS5 Patterns from User Input
 ///
 /// - ``init(matchingAllPrefixesIn:)``
@@ -123,7 +124,25 @@ public struct FTS5Pattern: Sendable {
         try? self.init(rawPattern: "^\"" + tokens.joined(separator: " ") + "\"")
     }
 
-    init(rawPattern: String, allowedColumns: [String] = []) throws {
+    /// Creates a pattern from a raw pattern string.
+    ///
+    /// The pattern syntax is documented at <https://www.sqlite.org/fts5.html#full_text_query_syntax>
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// // OK
+    /// let pattern = try FTS5Pattern(rawPattern: "and")
+    ///
+    /// // Throws an error: malformed MATCH expression: [AND]
+    /// let pattern = try FTS5Pattern(rawPattern: "AND")
+    /// ```
+    ///
+    /// If the pattern tests for specific columns, you must pass those
+    /// columns in the `allowedColumns` parameter.
+    ///
+    /// - throws: A ``DatabaseError`` if the pattern has an invalid syntax.
+    public init(rawPattern: String, allowedColumns: [String] = []) throws {
         // Correctness above all: use SQLite to validate the pattern.
         //
         // Invalid patterns have SQLite return an error on the first

Tests/GRDBTests/FTS5PatternTests.swift

@@ -43,9 +43,16 @@ class FTS5PatternTests: GRDBTestCase {
                 ("title:brest", 1)
             ]
             for (rawPattern, expectedCount) in validRawPatterns {
-                let pattern = try db.makeFTS5Pattern(rawPattern: rawPattern, forTable: "books")
-                let count = try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM books WHERE books MATCH ?", arguments: [pattern])!
-                XCTAssertEqual(count, expectedCount, "Expected pattern \(String(reflecting: rawPattern)) to yield \(expectedCount) results")
+                do {
+                    let pattern = try FTS5Pattern(rawPattern: rawPattern, allowedColumns: ["title"])
+                    let count = try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM books WHERE books MATCH ?", arguments: [pattern])!
+                    XCTAssertEqual(count, expectedCount, "Expected pattern \(String(reflecting: rawPattern)) to yield \(expectedCount) results")
+                }
+                do {
+                    let pattern = try db.makeFTS5Pattern(rawPattern: rawPattern, forTable: "books")
+                    let count = try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM books WHERE books MATCH ?", arguments: [pattern])!
+                    XCTAssertEqual(count, expectedCount, "Expected pattern \(String(reflecting: rawPattern)) to yield \(expectedCount) results")
+                }
             }
         }
     }
@@ -55,6 +62,14 @@ class FTS5PatternTests: GRDBTestCase {
         dbQueue.inDatabase { db in
             let invalidRawPatterns = ["", "?!", "^", "NOT", "(", "AND", "OR", "\"", "missing:foo"]
             for rawPattern in invalidRawPatterns {
+                do {
+                    _ = try FTS5Pattern(rawPattern: rawPattern, allowedColumns: ["title"])
+                    XCTFail("Expected pattern to be invalid: \(String(reflecting: rawPattern))")
+                } catch is DatabaseError {
+                } catch {
+                    XCTFail("Expected DatabaseError, not \(error)")
+                }
+                
                 do {
                     _ = try db.makeFTS5Pattern(rawPattern: rawPattern, forTable: "books")
                     XCTFail("Expected pattern to be invalid: \(String(reflecting: rawPattern))")