@@ -15,12 +15,36 @@ import Language.Haskell.TH.Quote
1515import Data.Char
1616
1717-- | 'sql' is a quasiquoter that eases the syntactic burden
18−-- of writing big sql statements in Haskell source code. It attempts
19−-- to minimize whitespace. Note that this implementation is incomplete
20−-- and can mess up your syntax; it only really understands standard
21−-- sql string literals (default in PostgreSQL 9) and not the extended
22−-- escape syntax or other situations where white space should be
23−-- preserved as is.
18+-- of writing big sql statements in Haskell source code. For example:
19+--
20+-- > {-# LANGUAGE QuasiQuotes #-}
21+-- >
22+-- > query conn [sql| SELECT column_a, column_b
23+-- > FROM table1 NATURAL JOIN table2
24+-- > WHERE ? <= time AND time < ?
25+-- > AND name LIKE ?
26+-- > ORDER BY size DESC
27+-- > LIMIT 100 |]
28+-- > (beginTime,endTime,string)
29+--
30+-- This quasiquoter attempts to mimimize whitespace; otherwise the
31+-- above query would consist of approximately half whitespace when sent
32+-- to the database backend.
33+--
34+-- The implementation of the whitespace reducer is currently incomplete.
35+-- Thus it can mess up your syntax in cases where whitespace should be
36+-- preserved as-is. It does preserve whitespace inside standard SQL string
37+-- literals. But it can get confused by the non-standard PostgreSQL string
38+-- literal syntax (which is the default setting in PostgreSQL 8 and below),
39+-- the extended escape string syntax, and other similar constructs.
40+--
41+-- Of course, this caveat only applies to text written inside the SQL
42+-- quasiquoter; whitespace reduction is a compile-time computation and
43+-- thus will not touch the @string@ parameter above, which is a run-time
44+-- value.
45+--
46+-- Also note that this will not work if the substring @|]@ is contained
47+-- in the query.
2448
2549sql :: QuasiQuoter
2650sql = QuasiQuoter