    {-# OPTIONS_GHC -fno-warn-unused-imports #-}

    -- |
    -- Module:      Web.Twitter.Conduit
    -- Copyright:   (c) 2014 Takahiro Himura
    -- License:     BSD
    -- Maintainer:  Takahiro Himura <taka@himura.jp>
    -- Stability:   experimental
    -- Portability: portable
    --
    -- A client library for Twitter APIs (see <https://dev.twitter.com/>).
    module Web.Twitter.Conduit (
        -- * How to use this library
        -- $howto

        -- ** Authentication
        -- $auth

        -- ** How to call API
        -- $call

        -- *** How to specify API parameters
        -- $parameter

        -- *** Conduit API: Recursive API call with changing cursor parameter
        -- $conduit

        -- * Re-exports
        module Web.Twitter.Conduit.Api,
        module Web.Twitter.Conduit.Cursor,
        module Web.Twitter.Conduit.Request,
        module Web.Twitter.Conduit.Response,
        module Web.Twitter.Conduit.Stream,
        module Web.Twitter.Conduit.Types,

        -- * 'Web.Twitter.Conduit.Base'
        call,
        call',
        callWithResponse,
        callWithResponse',
        sourceWithMaxId,
        sourceWithMaxId',
        sourceWithCursor,
        sourceWithCursor',
        sourceWithSearchResult,
        sourceWithSearchResult',

        -- * 'Web.Twitter.Conduit.Parameters'
        ListParam (..),
        MediaData (..),
        UserListParam (..),
        UserParam (..),
        TweetMode (..),

        -- * re-exports
        OAuth (..),
        Credential (..),
        def,
        Manager,
        newManager,
        tlsManagerSettings,
    ) where

    import Web.Twitter.Conduit.Api
    import Web.Twitter.Conduit.Base
    import Web.Twitter.Conduit.Cursor
    import Web.Twitter.Conduit.Parameters
    import Web.Twitter.Conduit.Request
    import Web.Twitter.Conduit.Response
    import Web.Twitter.Conduit.Stream
    import Web.Twitter.Conduit.Types

    import Data.Default (def)
    import Network.HTTP.Conduit (Manager, newManager, tlsManagerSettings)
    import Web.Authenticate.OAuth

    -- for haddock

    import Control.Lens
    import Control.Monad.IO.Class
    import Data.Conduit
    import qualified Data.Conduit.List as CL
    import qualified Data.Text as T
    import qualified Data.Text.IO as T

    {-# ANN module "HLint: ignore Use import/export shortcut" #-}

    -- $howto
    --
    -- The main module of twitter-conduit is "Web.Twitter.Conduit".
    -- This library cooperate with <http://hackage.haskell.org/package/twitter-types twitter-types>,
    -- <http://hackage.haskell.org/package/authenticate-oauth authenticate-oauth>,
    -- and <http://hackage.haskell.org/package/conduit conduit>.
    -- All of following examples import modules as below:
    --
    -- @
    -- {\-# LANGUAGE OverloadedLabels #-\}
    -- {\-# LANGUAGE OverloadedStrings #-\}
    --
    -- import Web.Twitter.Conduit
    -- import Web.Twitter.Types.Lens
    -- import Data.Conduit
    -- import qualified Data.Conduit.List as CL
    -- import qualified Data.Text as T
    -- import qualified Data.Text.IO as T
    -- import Control.Monad.IO.Class
    -- import Control.Lens
    -- @

    -- $auth
    --
    -- First, you should obtain consumer token and secret from <https://apps.twitter.com/ Twitter>,
    -- and prepare 'OAuth' variables as follows:
    --
    -- @
    -- tokens :: 'OAuth'
    -- tokens = 'twitterOAuth'
    --     { 'oauthConsumerKey' = \"YOUR CONSUMER KEY\"
    --     , 'oauthConsumerSecret' = \"YOUR CONSUMER SECRET\"
    --     }
    -- @
    --
    -- Second, you should obtain access token and secret.
    -- You can find examples obtaining those tokens in
    -- <https://github.com/himura/twitter-conduit/blob/master/sample sample directry>,
    -- for instance,
    -- <https://github.com/himura/twitter-conduit/blob/master/sample/oauth_pin.hs oauth_pin.hs>, and
    -- <https://github.com/himura/twitter-conduit/blob/master/sample/oauth_callback.hs oauth_callback.hs>.
    -- If you need more information, see <https://dev.twitter.com/docs/auth/obtaining-access-tokens>.
    --
    -- You should set an access token to 'Credential' variable:
    --
    -- @
    -- credential :: 'Credential'
    -- credential = 'Credential'
    --     [ (\"oauth_token\", \"YOUR ACCESS TOKEN\")
    --     , (\"oauth_token_secret\", \"YOUR ACCESS TOKEN SECRET\")
    --     ]
    -- @
    --
    -- You should also set up the 'TWToken' and 'TWInfo' variables as below:
    --
    -- @
    -- twInfo :: 'TWInfo'
    -- twInfo = 'def'
    --     { 'twToken' = 'def' { 'twOAuth' = tokens, 'twCredential' = credential }
    --     , 'twProxy' = Nothing
    --     }
    -- @
    --
    -- Or, simply as follows:
    --
    -- @
    -- twInfo = 'setCredential' tokens credential 'def'
    -- @

    -- $call
    --
    -- Twitter API requests are performed by 'call' function.
    -- For example, <https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline GET statuses/home_timeline>
    -- could be obtained by:
    --
    -- @
    -- mgr \<- 'newManager' 'tlsManagerSettings'
    -- timeline \<- 'call' twInfo mgr 'statusesHomeTimeline'
    -- @
    --
    -- The response of 'call' function is wrapped by the suitable type of
    -- <http://hackage.haskell.org/package/twitter-types twitter-types>.
    -- In this case, /timeline/ has a type of ['Status'].
    -- If you need /raw/ JSON Value which is parsed by <http://hackage.haskell.org/package/aeson aeson>,
    -- use 'call'' to obtain it.
    --
    -- By default, the response of <https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline GET statuses/home_timeline>
    -- includes 20 tweets, and you can change the number of tweets by the /count/ parameter.
    --
    -- @
    -- timeline \<- 'call' twInfo mgr '$' 'statusesHomeTimeline' '&' #count '?~' 200
    -- @

    -- $parameter
    --
    -- The parameters which can be specified for this API, is able to be obtained from type parameters of APIRequest.
    -- For example,
    --
    -- @
    -- 'statusesHomeTimeline' ::
    --     'APIRequest' 'StatusesHomeTimeline' ['Web.Twitter.Types.Status']
    -- @
    --
    -- - The 2nd type parameter of 'APIRequest' represents acceptable parameters in this API request.
    -- - The 3nd type parameter of 'APIRequest' denotes a return type of this API request.
    --
    -- The 2nd type parameter of 'statusesHomeTimeline' is 'StatusesHomeTimeline' defined as below:
    --
    -- @
    -- type StatusesHomeTimeline =
    --     '[ "count" ':= Integer
    --      , "since_id" ':= Integer
    --      , "max_id" ':= Integer
    --      , "trim_user" ':= Bool
    --      , "exclude_replies" ':= Bool
    --      , "contributor_details" ':= Bool
    --      , "include_entities" ':= Bool
    --      , "tweet_mode" ':= TweetMode
    --      ]
    -- @
    --
    -- Each element of list represents the name and type of API parameters.
    -- You can specify those parameter with OverloadedLabels extension.
    -- In the above example, it shows that 'statusesHomeTimeline' API supports "tweet_mode" parameter with 'TweetMode' type, so
    -- you can specify "tweet_mode" parameter as:
    --
    -- @
    -- 'statusesHomeTimeline' & #tweet_mode ?~ 'Extended'
    -- @

    -- $conduit
    --
    -- If you need more statuses, you can obtain those with multiple API requests.
    -- This library provides the wrapper for multiple requests with conduit interfaces.
    -- For example, if you intend to fetch the all friends information,
    -- you may perform multiple API requests with changing cursor parameter,
    -- or use the conduit wrapper 'sourceWithCursor' as below:
    --
    -- @
    -- friends \<-
    --     'runConduit' $
    --         'sourceWithMaxId' twInfo mgr ('friendsList' ('ScreenNameParam' \"thimura\") '&' #count '?~' 200)
    --             '.|' 'CL.consume'
    -- @
    --
    -- Statuses APIs, for instance, 'homeTimeline', are also wrapped by 'sourceWithMaxId'.
    --
    -- For example, you can print 60 tweets from your home timeline, as below:
    --
    -- @
    -- main :: IO ()
    -- main = do
    --     mgr \<- 'newManager' 'tlsManagerSettings'
    --     'runConduit' $ 'sourceWithMaxId' twInfo mgr 'homeTimeline'
    --         '.|' CL.isolate 60
    --         '.|' CL.mapM_
    --             (\\status -> do
    --                  T.putStrLn $
    --                      T.concat
    --                          [ T.pack . show $ status ^. statusId
    --                          , \": \"
    --                          , status ^. statusUser . userScreenName
    --                          , \": \"
    --                          , status ^. statusText
    --                          ]
    --             )
    -- @