-- 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.2.0.0

module Text.Playlist

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

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

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

-- | 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

-- | 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.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