diff --git a/README.md b/README.md index aa5058b..132bad2 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,6 @@ This is an conduit based Twitter API library for Haskell, including Streaming AP Documentation is available in [hackage](http://hackage.haskell.org/package/twitter-conduit). -## Usage ## - - $ cabal update - $ cabal install twitter-conduit - ## Quick Start ## For a runnable example, see [sample/simple.hs](https://github.com/himura/twitter-conduit/blob/master/sample/simple.hs). @@ -24,19 +19,32 @@ You can find other various examples in [sample](https://github.com/himura/twitte ### Build ### -If you would like to use cabal sandbox, prepare sandbox as below: +#### Building with Cabal #### ~~~~ -$ cabal sandbox init +$ cabal v2-build all ~~~~ -and then, +#### Building with Stack #### -~~~~ -$ cabal install --only-dependencies -fbuild-samples -$ cabal configure -fbuild-samples -$ cabal build -~~~~ +To build with Stack, you should create top-level `stack.yaml` file first. +An example of `stack.yaml` is like below: + +```.yaml +resolver: lts-18.12 +packages: +- . +- sample +extra-deps: +- twitter-types-0.11.0 +- twitter-types-lens-0.11.0 +``` + +then, run stack. + +``` +$ stack build +``` ### Run ### diff --git a/Web/Twitter/Conduit.hs b/Web/Twitter/Conduit.hs index 2ebd06a..18070b1 100644 --- a/Web/Twitter/Conduit.hs +++ b/Web/Twitter/Conduit.hs @@ -13,6 +13,18 @@ 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, @@ -80,16 +92,21 @@ import qualified Data.Text.IO as T -- and . -- 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 +-- @ +-- {\-# 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 , -- and prepare 'OAuth' variables as follows: @@ -132,7 +149,11 @@ import qualified Data.Text.IO as T -- -- Or, simply as follows: -- --- > twInfo = setCredential tokens credential def +-- @ +-- twInfo = 'setCredential' tokens credential 'def' +-- @ + +-- $call -- -- Twitter API requests are performed by 'call' function. -- For example, @@ -140,7 +161,7 @@ import qualified Data.Text.IO as T -- -- @ -- mgr \<- 'newManager' 'tlsManagerSettings' --- timeline \<- 'call' twInfo mgr 'homeTimeline' +-- timeline \<- 'call' twInfo mgr 'statusesHomeTimeline' -- @ -- -- The response of 'call' function is wrapped by the suitable type of @@ -153,8 +174,47 @@ import qualified Data.Text.IO as T -- includes 20 tweets, and you can change the number of tweets by the /count/ parameter. -- -- @ --- timeline \<- 'call' twInfo mgr '$' 'homeTimeline' '&' #count '?~' 200 +-- 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. @@ -163,24 +223,31 @@ import qualified Data.Text.IO as T -- or use the conduit wrapper 'sourceWithCursor' as below: -- -- @ --- friends \<- 'sourceWithCursor' twInfo mgr ('friendsList' ('ScreenNameParam' \"thimura\") '&' #count '?~' 200) '$$' 'CL.consume' +-- 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 1000 tweets from your home timeline, as below: +-- For example, you can print 60 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 --- ] +-- '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 +-- ] +-- ) -- @