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


-- | Library and executable for working with playlist files.
--   
--   Playlists is a library for working with media playlist files. The
--   original motivation for the library was extracting URLs for streaming
--   radio stations that use PLS and M3U playlist files.
--   
--   The package also includes an executable that can dump the URLs from a
--   playlist file and convert between playlist file formats.
--   
--   <i>Example:</i>
--   
--   <pre>
--   import qualified Data.ByteString as BS
--   import Text.Playlist
--   
--   readPlaylist :: Format -&gt; IO Playlist
--   readPlaylist fmt = do
--     content &lt;- BS.getContents
--     case parsePlaylist fmt content of
--       Left err -&gt; fail $ "failed to parse playlist on stdin: " ++ err
--       Right x  -&gt; return x
--   </pre>
--   
--   <i>Playlist Executable Examples:</i>
--   
--   <pre>
--   $ playlist urls --format PLS &lt; somefile.pls
--   
--   $ playlist convert --from PLS --to M3U &lt; somefile.pls
--   </pre>
@package playlists
@version 0.5.2

module Text.Playlist

-- | A single music file or streaming URL.
data Track
Track :: Text -> Maybe Text -> Maybe Float -> Track

-- | URL for a file or streaming resource.
[trackURL] :: Track -> Text

-- | Optional title.
[trackTitle] :: Track -> Maybe Text

-- | Optional duration in seconds.
[trackDuration] :: Track -> Maybe Float

-- | A list of <a>Track</a>s.
type Playlist = [Track]

-- | Playlist formats.
data Format

-- | <a>http://en.wikipedia.org/wiki/PLS_(file_format)</a>
PLS :: Format

-- | M3U and M3U8. <a>http://en.wikipedia.org/wiki/M3U</a>
M3U :: Format

-- | Parse a playlist from a <tt>ByteString</tt>. Parsing may fail in which
--   case an error message is returned in <tt>Left</tt>.
--   
--   <pre>
--   content &lt;- BS.getContents
--   case parsePlaylist M3U content of
--    Left err -&gt; fail $ "failed to parse playlist: " ++ err
--    Right x  -&gt; return x
--   </pre>
parsePlaylist :: Format -> ByteString -> Either String Playlist

-- | Return the appropriate attoparsec parser for the given playlist
--   format.
parserForFormat :: Format -> Parser Playlist

-- | Generate a lazy <tt>ByteString</tt> containing playlist data from the
--   given playlist and in the given format.
--   
--   <pre>
--   BL.putStr $ generatePlaylist M3U somePlaylist
--   </pre>
generatePlaylist :: Format -> Playlist -> ByteString

-- | Try to figure out a file's format from it's file extension.
--   
--   <pre>
--   &gt;&gt;&gt; fileNameToFormat "foo.m3u"
--   Just M3U
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fileNameToFormat "foo.M3U"
--   Just M3U
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fileNameToFormat "foo.txt"
--   Nothing
--   </pre>
fileNameToFormat :: FilePath -> Maybe Format

-- | Given a file name that does not have a file extension, return a file
--   name with the appropriate extension included based on the given
--   format.
--   
--   <pre>
--   &gt;&gt;&gt; appendExtension M3U "foo"
--   "foo.m3u"
--   </pre>
appendExtension :: Format -> FilePath -> FilePath

-- | If the given <a>Playlist</a> contains tracks that reference remote
--   playlists, this function will recursively download and process these
--   playlists. Returns a flattened playlist that should not contain any
--   references to other playlists.
--   
--   You supply the downloading function as the second argument. Use
--   whichever HTTP library that makes you happy.
--   
--   There are two error conditions that are ignored by this function:
--   
--   <ol>
--   <li>The nesting of playlists exceeds a (hard-coded) limit. In this
--   case no playlists beyond the limit are processed. Open a pull request
--   if you'd like to have a resolveN function that allows you to specific
--   the depth limit or one that returns an error.</li>
--   <li>A downloaded playlist contains a syntax error. In this case the
--   playlist is consider to have no tracks and is ignored. Open a pull
--   request if you want a version of this function that returns some sort
--   of an error instead of ignoring bad playlists.</li>
--   </ol>
resolve :: forall m. Monad m => Playlist -> (Text -> m Playlist) -> m Playlist