{-# LANGUAGE CPP #-} {-# 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 -- * Re-exports module Web.Twitter.Conduit.Base , module Web.Twitter.Conduit.Api , module Web.Twitter.Conduit.Status , module Web.Twitter.Conduit.Monad , module Web.Twitter.Conduit.Stream , module Web.Twitter.Conduit.Request , module Web.Twitter.Conduit.Parameters , module Web.Twitter.Types.Lens , MediaData (..) , UploadedMedia , mediaId , mediaSize , mediaImage , ImageSizeType , imageWidth , imageHeight , imageType ) where import Web.Twitter.Conduit.Types import Web.Twitter.Conduit.Base import Web.Twitter.Conduit.Api import Web.Twitter.Conduit.Status import Web.Twitter.Conduit.Monad import Web.Twitter.Conduit.Stream import Web.Twitter.Conduit.Request import Web.Twitter.Conduit.Parameters import Web.Twitter.Types.Lens -- for haddock import Web.Authenticate.OAuth 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.Logger import Control.Monad.IO.Class import Control.Lens #ifdef HLINT {-# ANN module "HLint: ignore Use import/export shortcut" #-} #endif -- $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 OverloadedStrings #-} -- > -- > import Web.Twitter.Conduit -- > import Web.Authenticate.OAuth -- > 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.Logger -- > import Control.Monad.IO.Class -- > import Control.Lens -- -- 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 -- -- Every twitter API functions are run in the 'TW' monad. -- By using 'runTW' function, you can perform computation in 'TW' monad. -- -- 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: -- -- @ -- timeline <- 'call' 'homeTimeline' -- @ -- -- 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' '$' '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' ('friendsList' ('ScreenNameParam' \"thimura\") '&' 'count' '?~' 200) '$$' 'CL.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 = runNoLoggingT . runTW twInfo $ do -- 'sourceWithMaxId' 'homeTimeline' -- $= CL.isolate 60 -- $$ CL.mapM_ $ \status -> liftIO $ do -- T.putStrLn $ T.concat [ T.pack . show $ status ^. statusId -- , \": \" -- , status ^. statusUser . userScreenName -- , \": \" -- , status ^. statusText -- ] -- @