Copyright	(c) 2014 Takahiro Himura
License	BSD
Maintainer	Takahiro Himura <taka@himura.jp>
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

Web.Twitter.Conduit

Contents

How to use this library
Re-exports
Base
Parameters
re-exports
deprecated

Description

A client library for Twitter APIs (see https://dev.twitter.com/).

Synopsis

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 mgr homeTimeline

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 mgr homeTimeline
        $= 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.Status

module Web.Twitter.Conduit.Stream

module Web.Twitter.Conduit.Types

`Base`

call Source #

Arguments

:: FromJSON 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.

call' Source #

Arguments

:: FromJSON 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.

callWithResponse Source #

Arguments

:: FromJSON 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
print $ responseStatus res
print $ responseHeaders res
print $ responseBody res

callWithResponse' :: FromJSON 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
print $ responseStatus res
print $ responseHeaders res
print $ responseBody (res :: Value)

sourceWithMaxId Source #

Arguments

:: (MonadIO m, FromJSON responseType, AsStatus responseType, HasMaxIdParam (APIRequest apiName [responseType]))
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName [responseType]
-> Source m responseType

A wrapper function to perform multiple API request with changing max_id parameter.

This function cooperate with instances of HasMaxIdParam.

sourceWithMaxId' Source #

Arguments

:: (MonadIO m, HasMaxIdParam (APIRequest apiName [responseType]))
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName [responseType]
-> Source m Value

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.

sourceWithCursor Source #

Arguments

:: (MonadIO m, FromJSON responseType, CursorKey ck, HasCursorParam (APIRequest apiName (WithCursor ck responseType)))
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName (WithCursor ck responseType)
-> Source m responseType

A wrapper function to perform multiple API request with changing cursor parameter.

This function cooperate with instances of HasCursorParam.

sourceWithCursor' Source #

Arguments

:: (MonadIO m, CursorKey ck, HasCursorParam (APIRequest apiName (WithCursor ck responseType)))
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName (WithCursor ck responseType)
-> Source m Value

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 #

Arguments

:: (MonadIO m, FromJSON responseType)
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName (SearchResult [responseType])
-> m (SearchResult (Source m responseType))

A wrapper function to perform multiple API request with SearchResult.

sourceWithSearchResult' Source #

Arguments

:: MonadIO m
=> TWInfo	Twitter Setting
-> Manager
-> APIRequest apiName (SearchResult [responseType])
-> m (SearchResult (Source m Value))

A wrapper function to perform multiple API request with SearchResult.

`Parameters`

data ListParam Source #

Constructors

ListIdParam Integer
ListNameParam String

Instances

Eq ListParam Source #
Methods (==) :: ListParam -> ListParam -> Bool # (/=) :: ListParam -> ListParam -> Bool #
Show ListParam Source #
Methods showsPrec :: Int -> ListParam -> ShowS # show :: ListParam -> String # showList :: [ListParam] -> ShowS #

data MediaData Source #

Constructors

MediaFromFile FilePath
MediaRequestBody FilePath RequestBody

data UserListParam Source #

Constructors

UserIdListParam [UserId]
ScreenNameListParam [String]

Instances

Eq UserListParam Source #
Methods (==) :: UserListParam -> UserListParam -> Bool # (/=) :: UserListParam -> UserListParam -> Bool #
Show UserListParam Source #
Methods showsPrec :: Int -> UserListParam -> ShowS # show :: UserListParam -> String # showList :: [UserListParam] -> ShowS #

data UserParam Source #

Constructors

UserIdParam UserId
ScreenNameParam String

Instances

Eq UserParam Source #
Methods (==) :: UserParam -> UserParam -> Bool # (/=) :: UserParam -> UserParam -> Bool #
Show UserParam Source #
Methods showsPrec :: Int -> UserParam -> ShowS # show :: UserParam -> String # showList :: [UserParam] -> ShowS #

re-exports

data OAuth :: * #

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
Methods (==) :: OAuth -> OAuth -> Bool # (/=) :: OAuth -> OAuth -> Bool #
Data OAuth
Methods 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 # toConstr :: OAuth -> Constr # 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 :: (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
Methods readsPrec :: Int -> ReadS OAuth # readList :: ReadS [OAuth] # readPrec :: ReadPrec OAuth # readListPrec :: ReadPrec [OAuth] #
Show OAuth
Methods showsPrec :: Int -> OAuth -> ShowS # show :: OAuth -> String # showList :: [OAuth] -> ShowS #
Default OAuth
Methods def :: OAuth #

newtype Credential :: * #

Data type for redential.

Constructors

Credential
Fields unCredential :: [(ByteString, ByteString)]

Instances

Eq Credential
Methods (==) :: Credential -> Credential -> Bool # (/=) :: Credential -> Credential -> Bool #
Data Credential
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Credential -> c Credential # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Credential # toConstr :: Credential -> Constr # dataTypeOf :: Credential -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c Credential) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Credential) # gmapT :: (forall b. Data b => b -> b) -> Credential -> Credential # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Credential -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Credential -> r # gmapQ :: (forall d. Data d => d -> u) -> Credential -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Credential -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Credential -> m Credential # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Credential -> m Credential # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Credential -> m Credential #
Ord Credential
Methods compare :: Credential -> Credential -> Ordering # (<) :: Credential -> Credential -> Bool # (<=) :: Credential -> Credential -> Bool # (>) :: Credential -> Credential -> Bool # (>=) :: Credential -> Credential -> Bool # max :: Credential -> Credential -> Credential # min :: Credential -> Credential -> Credential #
Read Credential
Methods readsPrec :: Int -> ReadS Credential # readList :: ReadS [Credential] # readPrec :: ReadPrec Credential # readListPrec :: ReadPrec [Credential] #
Show Credential
Methods showsPrec :: Int -> Credential -> ShowS # show :: Credential -> String # showList :: [Credential] -> ShowS #