Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Improve documentation of the SqlQQ modules

  • Loading branch information...
commit 8f542539c814c1749155f789ba7cebe3b80ab3f4 1 parent 44f3cd5
@lpsmith authored
Showing with 30 additions and 6 deletions.
  1. +30 −6 src/Database/PostgreSQL/Simple/SqlQQ.hs
View
36 src/Database/PostgreSQL/Simple/SqlQQ.hs
@@ -15,12 +15,36 @@ import Language.Haskell.TH.Quote
import Data.Char
-- | 'sql' is a quasiquoter that eases the syntactic burden
--- of writing big sql statements in Haskell source code. It attempts
--- to minimize whitespace. Note that this implementation is incomplete
--- and can mess up your syntax; it only really understands standard
--- sql string literals (default in PostgreSQL 9) and not the extended
--- escape syntax or other situations where white space should be
--- preserved as is.
+-- of writing big sql statements in Haskell source code. For example:
+--
+-- > {-# LANGUAGE QuasiQuotes #-}
+-- >
+-- > query conn [sql| SELECT column_a, column_b
+-- > FROM table1 NATURAL JOIN table2
+-- > WHERE ? <= time AND time < ?
+-- > AND name LIKE ?
+-- > ORDER BY size DESC
+-- > LIMIT 100 |]
+-- > (beginTime,endTime,string)
+--
+-- This quasiquoter attempts to mimimize whitespace; otherwise the
+-- above query would consist of approximately half whitespace when sent
+-- to the database backend.
+--
+-- The implementation of the whitespace reducer is currently incomplete.
+-- Thus it can mess up your syntax in cases where whitespace should be
+-- preserved as-is. It does preserve whitespace inside standard SQL string
+-- literals. But it can get confused by the non-standard PostgreSQL string
+-- literal syntax (which is the default setting in PostgreSQL 8 and below),
+-- the extended escape string syntax, and other similar constructs.
+--
+-- Of course, this caveat only applies to text written inside the SQL
+-- quasiquoter; whitespace reduction is a compile-time computation and
+-- thus will not touch the @string@ parameter above, which is a run-time
+-- value.
+--
+-- Also note that this will not work if the substring @|]@ is contained
+-- in the query.
sql :: QuasiQuoter
sql = QuasiQuoter
Please sign in to comment.
Something went wrong with that request. Please try again.