diff --git a/src/Web/Twitter/Feed.hs b/src/Web/Twitter/Feed.hs --- a/src/Web/Twitter/Feed.hs +++ b/src/Web/Twitter/Feed.hs @@ -1,5 +1,15 @@ {-# LANGUAGE OverloadedStrings, DeriveGeneric #-} +----------------------------------------------------------------------------- +-- | +-- Module : Web.Twitter.Feed +-- License : MIT (see the file LICENSE) +-- Maintainer : Justin Leitgeb +-- +-- Functions for fetching (and linkifying) timelines of Twitter users. +-- +----------------------------------------------------------------------------- + module Web.Twitter.Feed ( timeline , addLink @@ -16,8 +26,14 @@ import Data.Char (toLower) import Web.Twitter.Types -timeline :: OAuth -> Credential -> Int -> Bool -> String -> - IO (Either String [SimpleTweet]) +-- | Get and decode a user timeline. +timeline :: OAuth -- ^ OAuth client (consumer) + -> Credential -- ^ OAuth credential + -> Int -- ^ Count + -> Bool -- ^ Exclude replies? + -> String -- ^ Screen name + -> IO (Either String [SimpleTweet]) -- ^ Either an error or + -- the list of tweets timeline oauth credential count excludeReplies username = do req <- createRequest username count excludeReplies res <- getResponse oauth credential req @@ -38,7 +54,11 @@ decodeTweets :: Response BS.ByteString -> Either String [Tweet] decodeTweets = eitherDecode . responseBody -timelineUrl :: String -> Int -> Bool -> String +-- | Returns the URL for requesting a user timeline. +timelineUrl :: String -- ^ Screen name + -> Int -- ^ Count + -> Bool -- ^ Exclude replies? + -> String -- ^ The URL for requesting the user timeline timelineUrl user count excludeReplies = "https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=" ++ user ++ "&count=" ++ show count ++ "&exclude_replies=" ++ @@ -57,7 +77,11 @@ processText message users urls medias = foldr addLink message sortedLinks where sortedLinks = sortLinks urls users medias -sortLinks :: [URLEntity] -> [UserEntity] -> [MediaEntity] -> [Link] +-- | Sort lists of URL, user mention, and media entities. +sortLinks :: [URLEntity] -- ^ A list of URL entities + -> [UserEntity] -- ^ A list of user mention entities + -> [MediaEntity] -- ^ A list of media entities + -> [Link] -- ^ The sorted list of links sortLinks urls users medias = sort (map makeURLLink urls ++ map makeUserLink users ++ map makeMediaLink medias) @@ -91,7 +115,10 @@ , tweetId = idStr tweet , created_at = createdAt tweet } -addLink :: Link -> String -> String +-- | Add a link to the text of a tweet. +addLink :: Link -- ^ A link + -> String -- ^ The text of a tweet without the link + -> String -- ^ The text of the tweet with the link addLink (Link 139 140 link) tweet = before ++ " " ++ link ++ after where before = fst (splitAt (lastBlank tweet) tweet) after = snd (splitAt 140 tweet) diff --git a/src/Web/Twitter/Types.hs b/src/Web/Twitter/Types.hs --- a/src/Web/Twitter/Types.hs +++ b/src/Web/Twitter/Types.hs @@ -1,6 +1,14 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE DeriveGeneric #-} +--------------------------------------------------------- +-- | +-- Module : Web.Twitter.Types +-- License : MIT (see the file LICENSE) +-- Maintainer : Justin Leitgeb +-- +-- Types for working with the twitter API. +--------------------------------------------------------- module Web.Twitter.Types ( Tweet(..) , SimpleTweet(..) @@ -17,48 +25,56 @@ import Data.Ord (comparing) import GHC.Generics (Generic) +-- | Represents tweet start and end index type BoundingIndices = (Int, Int) +-- | Represents a tweet as HTML data SimpleTweet = SimpleTweet - { body :: String - , tweetId :: String - , created_at :: String + { body :: String -- ^ Tweet content as HTML + , tweetId :: String -- ^ Tweet id + , created_at :: String -- ^ Tweet created at date } deriving (Show, Generic) +-- | Represent a tweet as plain text data Tweet = Tweet - { text :: String - , createdAt :: String - , idStr :: String - , entities :: Entities + { text :: String -- ^ Tweet content as plain text + , createdAt :: String -- ^ Tweet created at date + , idStr :: String -- ^ Tweet id + , entities :: Entities -- ^ All references mentioned on the tweet } deriving (Show, Generic) +-- | Represent a list of all tweet references data Entities = Entities - { userEntities :: [UserEntity] - , urlEntities :: [URLEntity] - , mediaEntities :: [MediaEntity] + { userEntities :: [UserEntity] -- ^ List of all user references mentioned on the tweet + , urlEntities :: [URLEntity] -- ^ List of all urls references mentioned on the tweet + , mediaEntities :: [MediaEntity] -- ^ List of all media references mentioned on the tweet } deriving (Show, Generic) +-- | Represent a user reference data UserEntity = UserEntity - { screenName :: String - , userIndices :: BoundingIndices + { screenName :: String -- ^ User twitter name + , userIndices :: BoundingIndices -- ^ Tweet start and end index } deriving (Show, Generic) +-- | Represent a url reference data URLEntity = URLEntity - { urlMessage :: String - , urlIndices :: BoundingIndices - , displayUrl :: String + { urlMessage :: String -- ^ Reference title + , urlIndices :: BoundingIndices -- ^ Tweet start and end index + , displayUrl :: String -- ^ Reference url } deriving (Show, Generic) +-- | Represent a media reference data MediaEntity = MediaEntity - { mediaUrl :: String - , mediaIndices :: BoundingIndices - , displayMediaUrl :: String + { mediaUrl :: String -- ^ Reference url + , mediaIndices :: BoundingIndices -- ^ Tweet start and end index + , displayMediaUrl :: String -- ^ Reference title } deriving (Show, Generic) +-- | Represent a link as HTML data Link = Link - { startIndex :: Int - , endIndex :: Int - , newHtml :: String + { startIndex :: Int -- ^ Tweet start index + , endIndex :: Int -- ^ Tweet end index + , newHtml :: String -- ^ Link as HTML } deriving (Show, Eq) instance ToJSON SimpleTweet diff --git a/twitter-feed.cabal b/twitter-feed.cabal --- a/twitter-feed.cabal +++ b/twitter-feed.cabal @@ -1,5 +1,5 @@ name: twitter-feed -version: 0.1.1.2 +version: 0.1.1.3 synopsis: Client for fetching Twitter timeline via Oauth description: Fetches a user timeline from Twitter, and optionally linkifies the results using the Twitter entity API. homepage: https://github.com/stackbuilders/twitter-feed