-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Send posts from a feed to Twitter
--   
--   Reads feeds and tweets each post to a Twitter account. This is both a
--   library and a simple executable build on top of it.
--   
--   The feed is read only once. To keep updating, call this
--   program/library every few minutes. A local cache of earlier tweets is
--   kept in a file to make sure no duplicates are sent.
--   
--   To build your own program on top of this library use the
--   <a>atom2twitter</a> or <a>rss2twitter</a> functions. If you need
--   access to the complete feed instead of just individual individual
--   items, use the <a>feed2twitter</a> function.
--   
--   See the <a>hackage2twitter</a> program for an example of how to use
--   this library.
--   
--   The executable can be used as such:
--   
--   <pre>
--   $ feed2twitter http://example.com/feed.rss username password cache-file 50 [--debug-mode]
--   </pre>
@package feed2twitter
@version 0.2.0


-- | This module exposes several functions and data types to send feeds to
--   Twitter.
module Web.Feed2Twitter

-- | Configuration data for the <a>feed2twitter</a> function.
data Config
Config :: String -> String -> String -> FilePath -> Int -> Bool -> Config
feedUrl :: Config -> String
username :: Config -> String
password :: Config -> String
cacheFile :: Config -> FilePath
cacheSize :: Config -> Int
debugMode :: Config -> Bool

-- | Represents a single tweet. In principle this should be &lt;= 140
--   characters, however, because Twitter uses a url-shortener, a tweet
--   containing a url may exeed this limit.
type Tweet = String

-- | A unique identifier for a Tweet. Values of this type are stored in the
--   cache file to make sure no duplicate messages are sent to Twitter.
type GUID = String

-- | Sends an Atom feed to Twitter by using user-provided mapping function
--   for individual entries.
--   
--   This is a specialized version of <a>item2twitter</a>.
atom2twitter :: Config -> (Entry -> Tweet) -> IO ()

-- | Sends a RSS feed to Twitter by using user-provided mapping function
--   for individual items.
--   
--   This is a specialized version of <a>item2twitter</a>.
rss2twitter :: Config -> (RSSItem -> Tweet) -> IO ()

-- | Sends feed items to Twitter by using user-provided mapping function
--   for individual items.
--   
--   Defined in terms of <a>feed2twitter</a>.
item2twitter :: Config -> (Either Entry RSSItem -> Tweet) -> IO ()

-- | Function that does all the heavy lifting:
--   
--   <ul>
--   <li>Downloads the feed provided in the config value.</li>
--   <li>Calls the provided user-function to map feed to a list of guids
--   and tweets.</li>
--   <li>Filters out already posted tweets using guid cache.</li>
--   <li>Sends each tweet to Twitter and writes its guid to cache
--   file.</li>
--   <li>Truncate cache file to size provided in config value.</li>
--   </ul>
--   
--   User-function is responsible for generating guids for tweets and the
--   order of tweets.
feed2twitter :: Config -> (Feed -> [(GUID, Tweet)]) -> IO ()

-- | Truncates a string to 140 characters for a tweet.
--   
--   When input is longer than 140 characters, puts an ellipsis at the end.
trunc4tweet :: String -> String

-- | Truncates a string to 120 characters, leaving room for a space and a
--   url. Due to Twitter using a url-shortener, urls are assumed to max 20
--   characters.
--   
--   When input is shorter than 120 characters, returns it with a space,
--   otherwise truncates and puts an ellipsis and space at the end.
trunc4url :: String -> String
instance Show Config