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


-- | An FFI layer over TagLib's C bindings
--   
--   Provides functions for reading and writing metadata for a variety of
--   common audio formats. Currently supports both ID3v1 and ID3v2 for MP3
--   files, Ogg Vorbis comments and ID3 tags and Vorbis comments in FLAC,
--   MPC, Speex, WavPack TrueAudio, WAV, AIFF, MP4 and ASF files. It also
--   handles management of taglib files and strings, automatically freeing
--   allocations when computation is finished.
@package taglib-api
@version 0.1.1.2

module Audio.TagLib.Internal

-- | Monad for performing TagLib operations
newtype TagLib a
TagLib :: StateT TagLibEnv IO a -> TagLib a
unTagLib :: TagLib a -> StateT TagLibEnv IO a

-- | Internal representation of an open file
data TagLibFile
TagLibFile :: Ptr File -> Ptr Tag -> Ptr AudioProperties -> TagLibFile
filePtr :: TagLibFile -> Ptr File
tagPtr :: TagLibFile -> Ptr Tag
audioPropPtr :: TagLibFile -> Ptr AudioProperties

-- | A handle for an open file
newtype FileId
FileId :: Integer -> FileId

-- | Abstract C Types
data File
data Tag
data AudioProperties

-- | A collection of open files, and a generator for unique file ID's
data TagLibEnv
TagLibEnv :: Map FileId TagLibFile -> Integer -> TagLibEnv
taglibFilesOpen :: TagLibEnv -> Map FileId TagLibFile
taglibNextId :: TagLibEnv -> Integer

-- | A fresh Env
initialEnv :: TagLibEnv

-- | Record modify for taglibFilesOpen
onFilesOpen :: (Map FileId TagLibFile -> Map FileId TagLibFile) -> TagLibEnv -> TagLibEnv

-- | Record modify for taglibNextId
onNextId :: (Integer -> Integer) -> TagLibEnv -> TagLibEnv

-- | Exceptions that might be thrown
data TagLibException
NoSuchFileId :: TagLibException
InvalidFile :: FilePath -> TagLibException
UnableToOpen :: FilePath -> TagLibException
FileClosed :: TagLibException

-- | Put a new file into the Env
addNewFile :: FileId -> TagLibFile -> TagLib ()

-- | Get a fresh FileId, maintaining the internal generator
nextId :: TagLib FileId

-- | Get the list of currently opened files.
openFilePtrs :: TagLib [Ptr File]

-- | Call a function requiring the Env
fromEnv :: (TagLibEnv -> a) -> TagLib a

-- | Call a function requiring a file. Throws an exception should the
--   FileId not point to a currently open file.
fromFile :: (TagLibFile -> a) -> FileId -> TagLib a

-- | Embed an IO action in the TagLib context.
io :: IO a -> TagLib a
c_taglib_file_new :: CString -> IO (Ptr File)
c_taglib_file_free :: Ptr File -> IO ()
c_taglib_file_save :: Ptr File -> IO ()
c_taglib_file_is_valid :: Ptr File -> IO CInt
c_taglib_file_tag :: Ptr File -> IO (Ptr Tag)
c_taglib_file_audioproperties :: Ptr File -> IO (Ptr AudioProperties)
c_taglib_free_strings :: IO ()

-- | Free all the strings that TagLib has allocated. Use only when handling
--   your own memory. Otherwise, <tt>taglib</tt> will take care of this for
--   you.
freeTagLibStrings :: IO ()

-- | Remove a file from the Env
removeFile :: FileId -> TagLib ()

-- | Run a <tt>TagLib</tt> action without managing allocated resources.
--   Reading tags from a file will work regardless of whether
--   <a>cleanupFile</a> is used, but writing tags will not. TagLib's
--   strings must still be freed if a memory leak is to be avoided.
runTagLib :: TagLibEnv -> TagLib a -> IO (a, TagLibEnv)

-- | Run an unmanaged <tt>TagLib</tt> action, discarding the final Env.
evalTagLib :: TagLibEnv -> TagLib a -> IO a

-- | Save and close a file, in case you want to manage your own memory.
--   TagLib's strings are still freed by <tt>taglib</tt>.
closeFile :: FileId -> TagLib ()

-- | The base IO action necessary to deallocate all resources associated
--   with a single file.
cleanupFile :: Ptr File -> IO ()
instance Typeable TagLibException
instance Eq FileId
instance Ord FileId
instance Show TagLibException
instance Exception TagLibException
instance Applicative TagLib
instance Monad TagLib
instance Functor TagLib

module Audio.TagLib

-- | Run a <tt>TagLib</tt> block. Save and free any files left open when
--   the block is finished, and free all strings produced by taglib.
taglib :: TagLib a -> IO a

-- | Open a file and return a corresponding <tt>FileId</tt>. Internally,
--   this grabs the Tag and AudioProperties pointers to the TagLib_File.
openFile :: FilePath -> TagLib FileId

-- | Given a <tt>IO</tt> action which expects a <tt>Tag</tt> pointer and
--   <tt>CString</tt>, lifts it into an <tt>TagLib</tt> action, expecting
--   <tt>Text</tt>.
packStringTag :: SetStringTag -> FileId -> Text -> TagLib ()

-- | Given a <tt>IO</tt> action which expects a <tt>Tag</tt> pointer and
--   <tt>CInt</tt>, lifts it into an <tt>TagLib</tt> action, expecting a
--   <tt>Int</tt>.
packIntTag :: SetIntTag -> FileId -> Int -> TagLib ()

-- | Given a <tt>IO</tt> action which expects a <tt>Tag</tt> pointer and
--   results in a <tt>CString</tt>, lifts it into a <tt>TagLib</tt> action,
--   resulting in <tt>Text</tt>.
unpackStringTag :: GetStringTag -> FileId -> TagLib Text

-- | Given a <tt>IO</tt> action which expects a <tt>Tag</tt> pointer and
--   results in a <tt>CInt</tt>, lifts it into a <tt>TagLib</tt> action,
--   resulting in <tt>Int</tt>.
unpackIntTag :: GetIntTag -> FileId -> TagLib Int

-- | Given a <tt>IO</tt> action which expects a <tt>AudioProperties</tt>
--   pointer and results in a <tt>CInt</tt>, lifts it into a
--   <tt>TagLib</tt> action, resulting in <tt>Int</tt>.
unpackIntAP :: GetIntAP -> FileId -> TagLib Int

-- | FFI Type Synonyms
type SetStringTag = Ptr Tag -> CString -> IO ()
type SetIntTag = Ptr Tag -> CInt -> IO ()
type GetStringTag = Ptr Tag -> IO (Ptr CChar)
type GetIntTag = Ptr Tag -> IO CInt
type GetIntAP = Ptr AudioProperties -> IO CInt

-- | Set the track title.
setTitle :: FileId -> Text -> TagLib ()

-- | Set the artist name.
setArtist :: FileId -> Text -> TagLib ()

-- | Set the album name.
setAlbum :: FileId -> Text -> TagLib ()

-- | Set the comment field.
setComment :: FileId -> Text -> TagLib ()

-- | Set the genre field.
setGenre :: FileId -> Text -> TagLib ()

-- | Set the release year.
setYear :: FileId -> Int -> TagLib ()

-- | Set the track number.
setTrack :: FileId -> Int -> TagLib ()
c_taglib_tag_set_title :: SetStringTag
c_taglib_tag_set_artist :: SetStringTag
c_taglib_tag_set_album :: SetStringTag
c_taglib_tag_set_comment :: SetStringTag
c_taglib_tag_set_genre :: SetStringTag
c_taglib_tag_set_year :: SetIntTag
c_taglib_tag_set_track :: SetIntTag

-- | Get the track title.
getTitle :: FileId -> TagLib Text

-- | Get the artist name.
getArtist :: FileId -> TagLib Text

-- | Get the album name.
getAlbum :: FileId -> TagLib Text

-- | Get the contents of the comment field.
getComment :: FileId -> TagLib Text

-- | Get the contents of the genre field.
getGenre :: FileId -> TagLib Text

-- | Get the release year.
getYear :: FileId -> TagLib Int

-- | Get the track number.
getTrack :: FileId -> TagLib Int
c_taglib_tag_title :: GetStringTag
c_taglib_tag_artist :: GetStringTag
c_taglib_tag_album :: GetStringTag
c_taglib_tag_comment :: GetStringTag
c_taglib_tag_genre :: GetStringTag
c_taglib_tag_year :: GetIntTag
c_taglib_tag_track :: GetIntTag

-- | Retrieves the duration of the given file, in seconds.
getLength :: FileId -> TagLib Int

-- | Retrieves the bitrate of the given file, in kb/s.
getBitrate :: FileId -> TagLib Int

-- | Retrieves the sample rate of the given file, in Hz.
getSampleRate :: FileId -> TagLib Int

-- | Retrieves the number of channels in the given file.
getChannels :: FileId -> TagLib Int
c_taglib_audioproperties_length :: GetIntAP
c_taglib_audioproperties_bitrate :: GetIntAP
c_taglib_audioproperties_samplerate :: GetIntAP
c_taglib_audioproperties_channels :: GetIntAP

-- | Monad for performing TagLib operations
newtype TagLib a
TagLib :: StateT TagLibEnv IO a -> TagLib a
unTagLib :: TagLib a -> StateT TagLibEnv IO a

-- | Embed an IO action in the TagLib context.
io :: IO a -> TagLib a