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


-- | Implementation of named parameters for `postgresql-simple` library
--   
--   Implementation of named parameters for <tt>postgresql-simple</tt>
--   library.
--   
--   Here is an exaple of how it could be used in your code:
--   
--   <pre>
--   queryNamed [sql|
--       SELECT *
--       FROM table
--       WHERE foo = ?foo
--         AND bar = ?bar
--         AND baz = ?foo
--   |] [ "foo" =? "fooBar"
--      , "bar" =? "barVar"
--      ]
--   </pre>
@package postgresql-simple-named
@version 0.0.0.0


-- | Introduces named parameters for <tt>postgresql-simple</tt> library. It
--   uses <tt>?</tt> question mark symbol as the indicator of the named
--   parameter which is replaced with the standard syntax with question
--   marks.
--   
--   Check out the example of usage:
--   
--   <pre>
--   <a>queryNamed</a> [sql|
--       SELECT *
--       FROM users
--       WHERE foo = ?foo
--         AND bar = ?bar
--         AND baz = ?foo
--   |] [ "foo" <a>=?</a> "fooBar"
--      , "bar" <a>=?</a> "barVar"
--      ]
--   </pre>
module PgNamed

-- | Data type to represent each named parameter.
data NamedParam
NamedParam :: !Name -> !Action -> NamedParam
[namedParamName] :: NamedParam -> !Name
[namedParamParam] :: NamedParam -> !Action

-- | Wrapper over name of the argument.
newtype Name
Name :: Text -> Name
[unName] :: Name -> Text

-- | Operator to create <a>NamedParam</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; "foo" =? (1 :: Int)
--   NamedParam {namedParamName = "foo", namedParamParam = Plain "1"}
--   </pre>
--   
--   So it can be used in creating the list of the named arguments:
--   
--   <pre>
--   queryNamed [sql|
--     SELECT * FROM users WHERE foo = ?foo AND bar = ?bar AND baz = ?foo"
--   |] [ "foo" =? "fooBar"
--      , "bar" =? "barVar"
--      ]
--   </pre>
(=?) :: ToField a => Name -> a -> NamedParam
infix 1 =?

-- | <tt>PostgreSQL</tt> error type for named parameters.
data PgNamedError

-- | Named parameter is not specified.
PgNamedParam :: Name -> PgNamedError

-- | Query has no names inside but was called with named functions.
PgNoNames :: Query -> PgNamedError

-- | Query contains an empty name.
PgEmptyName :: Query -> PgNamedError

-- | Type alias for monads that can throw errors of the <a>PgNamedError</a>
--   type.
type WithNamedError = MonadError PgNamedError

-- | This function takes query with named parameters specified like this:
--   
--   <pre>
--   SELECT name, user FROM users WHERE id = ?id
--   </pre>
--   
--   and returns either the error or the query with all names replaced by
--   question marks <tt>?</tt> with the list of the names in the order of
--   their appearance.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; extractNames "SELECT * FROM users WHERE foo = ?foo AND bar = ?bar AND baz = ?foo"
--   Right ("SELECT * FROM users WHERE foo = ? AND bar = ? AND baz = ?","foo" :| ["bar","foo"])
--   </pre>
extractNames :: Query -> Either PgNamedError (Query, NonEmpty Name)

-- | Returns the list of values to use in query by given list of
--   <a>Name</a>s. Throws <a>PgNamedError</a> if any named parameter is not
--   specified.
namesToRow :: forall m. WithNamedError m => NonEmpty Name -> [NamedParam] -> m (NonEmpty Action)

-- | Queries the database with a given query and named parameters and
--   expects a list of rows in return.
--   
--   <pre>
--   queryNamed dbConnection [sql|
--       SELECT id FROM table
--       WHERE foo = ?foo
--   |] [ "foo" <a>=?</a> "bar" ]
--   </pre>
queryNamed :: (MonadIO m, WithNamedError m, FromRow res) => Connection -> Query -> [NamedParam] -> m [res]

-- | Modifies the database with a given query and named parameters and
--   expects a number of the rows affected.
--   
--   <pre>
--   executeNamed dbConnection [sql|
--       UPDATE table
--       SET foo = <tt>bar</tt>
--       WHERE id = ?id
--   |] [ "id" <a>=?</a> someId ]
--   </pre>
executeNamed :: (MonadIO m, WithNamedError m) => Connection -> Query -> [NamedParam] -> m Int64
instance GHC.Classes.Eq PgNamed.PgNamedError
instance GHC.Show.Show PgNamed.NamedParam
instance Data.String.IsString PgNamed.Name
instance GHC.Classes.Ord PgNamed.Name
instance GHC.Classes.Eq PgNamed.Name
instance GHC.Show.Show PgNamed.Name
instance GHC.Show.Show PgNamed.PgNamedError