Copyright | (c) 2014 Takahiro Himura |
---|---|
License | BSD |
Maintainer | Takahiro Himura <taka@himura.jp> |
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
A client library for Twitter APIs (see https://dev.twitter.com/).
Synopsis
- 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
- call :: ResponseBodyType responseType => TWInfo -> Manager -> APIRequest apiName responseType -> IO responseType
- call' :: ResponseBodyType value => TWInfo -> Manager -> APIRequest apiName responseType -> IO value
- callWithResponse :: ResponseBodyType responseType => TWInfo -> Manager -> APIRequest apiName responseType -> IO (Response responseType)
- callWithResponse' :: ResponseBodyType value => TWInfo -> Manager -> APIRequest apiName responseType -> IO (Response value)
- sourceWithMaxId :: (MonadIO m, FromJSON responseType, AsStatus responseType, HasParam "max_id" Integer supports) => TWInfo -> Manager -> APIRequest supports [responseType] -> ConduitT () responseType m ()
- sourceWithMaxId' :: (MonadIO m, HasParam "max_id" Integer supports) => TWInfo -> Manager -> APIRequest supports [responseType] -> ConduitT () Value m ()
- sourceWithCursor :: (MonadIO m, FromJSON responseType, CursorKey ck, HasParam "cursor" Integer supports) => TWInfo -> Manager -> APIRequest supports (WithCursor Integer ck responseType) -> ConduitT () responseType m ()
- sourceWithCursor' :: (MonadIO m, CursorKey ck, HasParam "cursor" Integer supports) => TWInfo -> Manager -> APIRequest supports (WithCursor Integer ck responseType) -> ConduitT () Value m ()
- sourceWithSearchResult :: (MonadIO m, FromJSON responseType) => TWInfo -> Manager -> APIRequest supports (SearchResult [responseType]) -> m (SearchResult (ConduitT () responseType m ()))
- sourceWithSearchResult' :: MonadIO m => TWInfo -> Manager -> APIRequest supports (SearchResult [responseType]) -> m (SearchResult (ConduitT () Value m ()))
- data ListParam
- data MediaData
- data UserListParam
- data UserParam
- data OAuth
- newtype Credential = Credential {
- unCredential :: [(ByteString, ByteString)]
- def :: Default a => a
- data Manager
- newManager :: ManagerSettings -> IO Manager
- tlsManagerSettings :: ManagerSettings
How to use this library
The main module of twitter-conduit is Web.Twitter.Conduit. This library cooperate with twitter-types, authenticate-oauth, and conduit. All of following examples import modules as below:
{\-# 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
First, you should obtain consumer token and secret from 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 sample directry, for instance, oauth_pin.hs, and 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
Twitter API requests are performed by call
function.
For example, GET statuses/home_timeline
could be obtained by:
mgr <-newManager
tlsManagerSettings
timeline <-call
twInfo mgrhomeTimeline
The response of call
function is wrapped by the suitable type of
twitter-types.
In this case, timeline has a type of [Status
].
If you need raw JSON Value which is parsed by aeson,
use call'
to obtain it.
By default, the response of GET statuses/home_timeline includes 20 tweets, and you can change the number of tweets by the count parameter.
timeline <-call
twInfo mgr$
homeTimeline
&
#count?~
200
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 <-sourceWithCursor
twInfo mgr (friendsList
(ScreenNameParam
"thimura")&
#count?~
200)$$
consume
Statuses APIs, for instance, homeTimeline
, are also wrapped by sourceWithMaxId
.
For example, you can print 1000 tweets from your home timeline, as below:
main :: IO () main = do mgr <-newManager
tlsManagerSettings
sourceWithMaxId
twInfo mgrhomeTimeline
$= CL.isolate 60 $$ CL.mapM_ $ \status -> liftIO $ do T.putStrLn $ T.concat [ T.pack . show $ status ^. statusId , ": " , status ^. statusUser . userScreenName , ": " , status ^. statusText ]
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
Base
:: ResponseBodyType responseType | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest apiName responseType | |
-> IO responseType |
Perform an APIRequest
and then provide the response which is mapped to a suitable type of
twitter-types.
Example:
user <-call
twInfo mgr $accountVerifyCredentials
print user
If you need raw JSON value which is parsed by aeson,
use call'
to obtain it.
:: ResponseBodyType value | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest apiName responseType | |
-> IO value |
Perform an APIRequest
and then provide the response.
The response of this function is not restrict to responseType
,
so you can choose an arbitrarily type of FromJSON instances.
:: ResponseBodyType responseType | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest apiName responseType | |
-> IO (Response responseType) |
Perform an APIRequest
and then provide the Response
.
Example:
res <-callWithResponse
twInfo mgr $accountVerifyCredentials
responseStatus
resresponseHeaders
resresponseBody
res
callWithResponse' :: ResponseBodyType value => TWInfo -> Manager -> APIRequest apiName responseType -> IO (Response value) Source #
Perform an APIRequest
and then provide the Response
.
The response of this function is not restrict to responseType
,
so you can choose an arbitrarily type of FromJSON instances.
Example:
res <-callWithResponse'
twInfo mgr $accountVerifyCredentials
responseStatus
resresponseHeaders
resresponseBody
(res :: Value)
:: (MonadIO m, FromJSON responseType, AsStatus responseType, HasParam "max_id" Integer supports) | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports [responseType] | |
-> ConduitT () responseType m () |
A wrapper function to perform multiple API request with changing max_id
parameter.
This function cooperate with instances of HasMaxIdParam
.
:: (MonadIO m, HasParam "max_id" Integer supports) | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports [responseType] | |
-> ConduitT () Value m () |
A wrapper function to perform multiple API request with changing max_id
parameter.
The response of this function is not restrict to responseType
,
so you can choose an arbitrarily type of FromJSON instances.
This function cooperate with instances of HasMaxIdParam
.
:: (MonadIO m, FromJSON responseType, CursorKey ck, HasParam "cursor" Integer supports) | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports (WithCursor Integer ck responseType) | |
-> ConduitT () responseType m () |
A wrapper function to perform multiple API request with changing cursor
parameter.
This function cooperate with instances of HasCursorParam
.
:: (MonadIO m, CursorKey ck, HasParam "cursor" Integer supports) | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports (WithCursor Integer ck responseType) | |
-> ConduitT () Value m () |
A wrapper function to perform multiple API request with changing cursor
parameter.
The response of this function is not restrict to responseType
,
so you can choose an arbitrarily type of FromJSON instances.
This function cooperate with instances of HasCursorParam
.
sourceWithSearchResult Source #
:: (MonadIO m, FromJSON responseType) | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports (SearchResult [responseType]) | |
-> m (SearchResult (ConduitT () responseType m ())) |
A wrapper function to perform multiple API request with SearchResult
.
sourceWithSearchResult' Source #
:: MonadIO m | |
=> TWInfo | Twitter Setting |
-> Manager | |
-> APIRequest supports (SearchResult [responseType]) | |
-> m (SearchResult (ConduitT () Value m ())) |
A wrapper function to perform multiple API request with SearchResult
.
Parameters
data UserListParam Source #
Instances
Eq UserListParam Source # | |
Defined in Web.Twitter.Conduit.Parameters (==) :: UserListParam -> UserListParam -> Bool # (/=) :: UserListParam -> UserListParam -> Bool # | |
Show UserListParam Source # | |
Defined in Web.Twitter.Conduit.Parameters showsPrec :: Int -> UserListParam -> ShowS # show :: UserListParam -> String # showList :: [UserListParam] -> ShowS # |
re-exports
Data type for OAuth client (consumer).
The constructor for this data type is not exposed.
Instead, you should use the def
method or newOAuth
function to retrieve a default instance,
and then use the records below to make modifications.
This approach allows us to add configuration options without breaking backwards compatibility.
Instances
Eq OAuth | |
Data OAuth | |
Defined in Web.Authenticate.OAuth gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> OAuth -> c OAuth # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c OAuth # dataTypeOf :: OAuth -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c OAuth) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c OAuth) # gmapT :: (forall b. Data b => b -> b) -> OAuth -> OAuth # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> OAuth -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> OAuth -> r # gmapQ :: (forall d. Data d => d -> u) -> OAuth -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> OAuth -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> OAuth -> m OAuth # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> OAuth -> m OAuth # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> OAuth -> m OAuth # | |
Read OAuth | |
Show OAuth | |
Default OAuth | |
Defined in Web.Authenticate.OAuth |
newtype Credential #
Data type for credential.
Credential | |
|
Instances
Keeps track of open connections for keep-alive.
If possible, you should share a single Manager
between multiple threads and requests.
Since 0.1.0
Instances
HasHttpManager Manager | |
Defined in Network.HTTP.Client.Types getHttpManager :: Manager -> Manager # |
newManager :: ManagerSettings -> IO Manager #
Create a Manager
. The Manager
will be shut down automatically via
garbage collection.
Creating a new Manager
is a relatively expensive operation, you are
advised to share a single Manager
between requests instead.
The first argument to this function is often defaultManagerSettings
,
though add-on libraries may provide a recommended replacement.
Since 0.1.0
tlsManagerSettings :: ManagerSettings #
Default TLS-enabled manager settings