Enhance SQLLiteral and SQL interpolation again

CHANGELOG.md

@@ -6,9 +6,7 @@ All notable changes to this project will be documented in this file.
 GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception: APIs flagged [**:fire: EXPERIMENTAL**](README.md#what-are-experimental-features). Those are unstable, and may break between any two minor releases of the library.
 
 
-<!--
 [Next Release](#next-release)
--->
 
 
 #### 4.x Releases
@@ -63,9 +61,11 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 - [0.110.0](#01100), ...
 
 
-<!--
 ## Next Release
--->
+
+**New**
+
+- [#706](https://github.com/groue/GRDB.swift/pull/706): Enhance SQLLiteral and SQL interpolation again
 
 
 ## 4.10.0

Documentation/SQLInterpolation.md

@@ -152,7 +152,7 @@ Such literal expressions can be returned by Swift functions:
 
 ```swift
 func date(_ value: SQLExpressible) -> SQLExpression {
-    SQLLiteral("DATE(\(lhs.sqlExpression))").sqlExpression
+    SQLLiteral("DATE(\(value))").sqlExpression
 }
 
 // SELECT * FROM "player" WHERE DATE("createdAt") = '2020-01-23'

GRDB/QueryInterface/SQLInterpolation+QueryInterface.swift

@@ -57,7 +57,16 @@ extension SQLInterpolation {
     ///     let request: SQLRequest<Int> = """
     ///         SELECT score + \(bonus) FROM player
     ///         """
-    public mutating func appendInterpolation<T: SQLExpressible>(_ expressible: T?) {
+    ///
+    /// You can also derive literal expressions from other expressions:
+    ///
+    ///     func date(_ value: SQLExpressible) -> SQLExpression {
+    ///         SQLLiteral("DATE(\(value))").sqlExpression
+    ///     }
+    ///
+    ///     // SELECT * FROM player WHERE DATE(createdAt) = '2020-02-25'
+    ///     let request = Player.filter(date(Column("createdAt")) == "2020-02-25")
+    public mutating func appendInterpolation(_ expressible: SQLExpressible?) {
         if let expressible = expressible {
             elements.append(.expression(expressible.sqlExpression))
         } else {

Tests/GRDBTests/SQLLiteralTests.swift

@@ -473,6 +473,33 @@ extension SQLLiteralTests {
                     SELECT * FROM "player" WHERE (DATE("createdAt")) = '2020-01-23'
                     """)
             }
+
+            do {
+                // Here we test that users can define functions that return
+                // literal expressions.
+                func date(_ value: SQLExpressible) -> SQLExpression {
+                    return SQLLiteral("DATE(\(value))").sqlExpression
+                }
+                let createdAt = Column("createdAt")
+                let request = Player.filter(date(createdAt) == "2020-01-23")
+                try assertEqualSQL(db, request, """
+                    SELECT * FROM "player" WHERE (DATE("createdAt")) = '2020-01-23'
+                    """)
+            }
+
+            do {
+                // Here we test that users can still define functions that
+                // return literal expressions with the previously
+                // supported technique.
+                func date(_ value: SQLExpressible) -> SQLExpression {
+                    return SQLLiteral("DATE(\(value.sqlExpression))").sqlExpression
+                }
+                let createdAt = Column("createdAt")
+                let request = Player.filter(date(createdAt) == "2020-01-23")
+                try assertEqualSQL(db, request, """
+                    SELECT * FROM "player" WHERE (DATE("createdAt")) = '2020-01-23'
+                    """)
+            }
         }
     }
 }