-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Toolkit for constructing Hasql statements dynamically
--   
--   This library introduces into the Hasql ecosystem a new abstraction
--   named Snippet, which makes it trivial to construct SQL, while
--   injecting values. It is intended to be used when the SQL of your
--   statement depends on the parameters, that you want to pass in.
@package hasql-dynamic-statements
@version 0.3.1.2

module Hasql.DynamicStatements.Snippet

-- | Composable SQL snippet with parameters injected. Abstracts over
--   placeholders and matching of encoders.
--   
--   It has an instance of <a>IsString</a>, so having the
--   <tt>OverloadedStrings</tt> extension enabled you can construct it
--   directly from string literals.
--   
--   Here's an example:
--   
--   <pre>
--   selectSubstring :: Text -&gt; Maybe Int32 -&gt; Maybe Int32 -&gt; <a>Snippet</a>
--   selectSubstring string from to =
--     "select substring(" &lt;&gt; <a>param</a> string &lt;&gt;
--     <a>foldMap</a> (\ x -&gt; " from " &lt;&gt; <a>param</a> x) from &lt;&gt;
--     <a>foldMap</a> (\ x -&gt; " for " &lt;&gt; <a>param</a> x) to &lt;&gt;
--     ")"
--   </pre>
--   
--   Having a decoder you can lift it into <a>Statement</a> using
--   <a>dynamicallyParameterized</a> or directly execute it in
--   <a>Session</a> using <a>dynamicallyParameterizedStatement</a>.
data Snippet

-- | Parameter encoded using an implicitly derived encoder from the type.
param :: DefaultParamEncoder param => param -> Snippet

-- | Parameter with an explicitly defined encoder.
encoderAndParam :: NullableOrNot Value param -> param -> Snippet

-- | SQL chunk in ASCII.
sql :: ByteString -> Snippet

module Hasql.DynamicStatements.Statement

-- | Construct a statement dynamically, specifying the parameters in-place
--   in the declaration of snippet and providing a result decoder and
--   specifying whether the statement should be prepared.
--   
--   The injection of the parameters is handled automatically, generating
--   parametric statements with binary encoders under the hood.
--   
--   This is useful when the SQL of your statement depends on the
--   parameters. Here's an example:
--   
--   <pre>
--   selectSubstring :: Text -&gt; Maybe Int32 -&gt; Maybe Int32 -&gt; <a>Statement</a> () Text
--   selectSubstring string from to = let
--     snippet =
--       "select substring(" &lt;&gt; Snippet.<a>param</a> string &lt;&gt;
--       foldMap (mappend " from " . Snippet.<a>param</a>) from &lt;&gt;
--       foldMap (mappend " for " . Snippet.<a>param</a>) to &lt;&gt;
--       ")"
--     decoder = Decoders.<a>singleRow</a> (Decoders.<a>column</a> (Decoders.<a>nonNullable</a> Decoders.<a>text</a>))
--     in <a>dynamicallyParameterized</a> snippet decoder True
--   </pre>
--   
--   Without the Snippet API you would have had to implement the same
--   functionality thus:
--   
--   <pre>
--   selectSubstring' :: Text -&gt; Maybe Int32 -&gt; Maybe Int32 -&gt; <a>Statement</a> () Text
--   selectSubstring' string from to = let
--     sql = case (from, to) of
--       (Just _, Just _) -&gt; "select substring($1 from $2 to $3)"
--       (Just _, Nothing) -&gt; "select substring($1 from $2)"
--       (Nothing, Just _) -&gt; "select substring($1 to $2)"
--       (Nothing, Nothing) -&gt; "select substring($1)"
--     encoder = 
--       Encoders.<a>param</a> (string <a>&gt;$</a> Encoders.<a>text</a>) &lt;&gt;
--       foldMap (\ x -&gt; Encoders.<a>param</a> (x <a>&gt;$</a> Encoders.<a>int8</a>)) from &lt;&gt;
--       foldMap (\ x -&gt; Encoders.<a>param</a> (x <a>&gt;$</a> Encoders.<a>int8</a>)) to
--     decoder = Decoders.<a>singleRow</a> (Decoders.<a>column</a> Decoders.<a>text</a>)
--     in Statement sql encoder decoder True
--   </pre>
--   
--   As you can see, the Snippet API abstracts over placeholders and
--   matching encoder generation, thus also protecting you from all sorts
--   of related bugs.
dynamicallyParameterized :: Snippet -> Result result -> Bool -> Statement () result

module Hasql.DynamicStatements.Session

-- | Execute a dynamically parameterized statement, providing a result
--   decoder.
--   
--   This is merely a shortcut, which immediately embeds
--   <tt>Hasql.DynamicStatements.Statement.<a>dynamicallyParameterized</a></tt>
--   in <tt>Session</tt>. For details see the docs on that function.
dynamicallyParameterizedStatement :: Snippet -> Result result -> Bool -> Session result
