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


-- | An MPD client library.
--   
--   A client library for MPD, the Music Player Daemon
--   (<a>http://www.musicpd.org/</a>).
@package libmpd
@version 0.7.2


-- | The core datatypes and operations are defined here, including the
--   primary instance of the <a>MonadMPD</a> class, <a>MPD</a>.
module Network.MPD.Core

-- | A typeclass to allow for multiple implementations of a connection to
--   an MPD server.
class (Monad m, MonadError MPDError m) => MonadMPD m
open :: MonadMPD m => m ()
close :: MonadMPD m => m ()
send :: MonadMPD m => String -> m String
getHandle :: MonadMPD m => m (Maybe Handle)
getPassword :: MonadMPD m => m Password
setPassword :: MonadMPD m => String -> m ()
getVersion :: MonadMPD m => m (Int, Int, Int)

-- | The main implementation of an MPD client. It actually connects to a
--   server and interacts with it.
--   
--   To use the error throwing/catching capabilities:
--   
--   <pre>
--   import Control.Monad.Error (throwError, catchError)
--   </pre>
--   
--   To run IO actions within the MPD monad:
--   
--   <pre>
--   import Control.Monad.Trans (liftIO)
--   </pre>
data MPD a

-- | The MPDError type is used to signal errors, both from the MPD and
--   otherwise.
data MPDError

-- | MPD not responding
NoMPD :: MPDError

-- | The connection timed out
TimedOut :: MPDError

-- | MPD returned an unexpected response. This is a bug, either in the
--   library or in MPD itself.
Unexpected :: String -> MPDError

-- | Used for misc. errors
Custom :: String -> MPDError

-- | ACK type and a message from the server
ACK :: ACKType -> String -> MPDError

-- | Represents various MPD errors (aka. ACKs).
data ACKType

-- | Invalid argument passed (ACK 2)
InvalidArgument :: ACKType

-- | Invalid password supplied (ACK 3)
InvalidPassword :: ACKType

-- | Authentication required (ACK 4)
Auth :: ACKType

-- | Unknown command (ACK 5)
UnknownCommand :: ACKType

-- | File or directory not found ACK 50)
FileNotFound :: ACKType

-- | Playlist at maximum size (ACK 51)
PlaylistMax :: ACKType

-- | A system error (ACK 52)
System :: ACKType

-- | Playlist loading failed (ACK 53)
PlaylistLoad :: ACKType

-- | Update already running (ACK 54)
Busy :: ACKType

-- | An operation requiring playback got interrupted (ACK 55)
NotPlaying :: ACKType

-- | File already exists (ACK 56)
FileExists :: ACKType

-- | An unknown ACK (aka. bug)
UnknownACK :: ACKType

-- | A response is either an <a>MPDError</a> or some result.
type Response = Either MPDError
type Host = String
type Port = Integer
type Password = String

-- | The most configurable API for running an MPD action.
withMPDEx :: Host -> Port -> Password -> MPD a -> IO (Response a)

-- | Send a command to the MPD server and return the result.
getResponse :: MonadMPD m => String -> m [String]

-- | Kill the server. Obviously, the connection is then invalid.
kill :: MonadMPD m => m ()
instance Functor MPD
instance Monad MPD
instance MonadIO MPD
instance MonadError MPDError MPD
instance MonadMPD MPD
instance Applicative MPD


-- | Extensions and shortcuts to the standard MPD command set.
module Network.MPD.Commands.Extensions

-- | Like <a>update</a>, but returns the update job id.
updateId :: MonadMPD m => [Path] -> m Integer

-- | Toggles play/pause. Plays if stopped.
toggle :: MonadMPD m => m ()

-- | Add a list of songs/folders to a playlist. Should be more efficient
--   than running <a>add</a> many times.
addMany :: MonadMPD m => PlaylistName -> [Path] -> m ()

-- | Delete a list of songs from a playlist. If there is a duplicate then
--   no further songs will be deleted, so take care to avoid them (see
--   <tt>prune</tt> for this).
--   
--   List the artists in the database.
listArtists :: MonadMPD m => m [Artist]

-- | List the albums in the database, optionally matching a given artist.
listAlbums :: MonadMPD m => Maybe Artist -> m [Album]

-- | List the songs in an album of some artist.
listAlbum :: MonadMPD m => Artist -> Album -> m [Song]

-- | Retrieve the current playlist. Equivalent to <tt>playlistinfo
--   Nothing</tt>.
getPlaylist :: MonadMPD m => m [Song]

-- | Increase or decrease volume by a given percent, e.g. 'volume 10' will
--   increase the volume by 10 percent, while 'volume (-10)' will decrease
--   it by the same amount.
volume :: MonadMPD m => Int -> m ()


-- | An MPD client library. MPD is a daemon for playing music that is
--   controlled over a network socket. Its site is at
--   <a>http://www.musicpd.org/</a>.
--   
--   To avoid name clashes with the standard Prelude functions, do:
--   
--   <pre>
--   import qualified Network.MPD as MPD
--   </pre>
module Network.MPD

-- | A typeclass to allow for multiple implementations of a connection to
--   an MPD server.
class (Monad m, MonadError MPDError m) => MonadMPD m
close :: MonadMPD m => m ()

-- | The main implementation of an MPD client. It actually connects to a
--   server and interacts with it.
--   
--   To use the error throwing/catching capabilities:
--   
--   <pre>
--   import Control.Monad.Error (throwError, catchError)
--   </pre>
--   
--   To run IO actions within the MPD monad:
--   
--   <pre>
--   import Control.Monad.Trans (liftIO)
--   </pre>
data MPD a

-- | The MPDError type is used to signal errors, both from the MPD and
--   otherwise.
data MPDError

-- | MPD not responding
NoMPD :: MPDError

-- | The connection timed out
TimedOut :: MPDError

-- | MPD returned an unexpected response. This is a bug, either in the
--   library or in MPD itself.
Unexpected :: String -> MPDError

-- | Used for misc. errors
Custom :: String -> MPDError

-- | ACK type and a message from the server
ACK :: ACKType -> String -> MPDError

-- | Represents various MPD errors (aka. ACKs).
data ACKType

-- | Invalid argument passed (ACK 2)
InvalidArgument :: ACKType

-- | Invalid password supplied (ACK 3)
InvalidPassword :: ACKType

-- | Authentication required (ACK 4)
Auth :: ACKType

-- | Unknown command (ACK 5)
UnknownCommand :: ACKType

-- | File or directory not found ACK 50)
FileNotFound :: ACKType

-- | Playlist at maximum size (ACK 51)
PlaylistMax :: ACKType

-- | A system error (ACK 52)
System :: ACKType

-- | Playlist loading failed (ACK 53)
PlaylistLoad :: ACKType

-- | Update already running (ACK 54)
Busy :: ACKType

-- | An operation requiring playback got interrupted (ACK 55)
NotPlaying :: ACKType

-- | File already exists (ACK 56)
FileExists :: ACKType

-- | An unknown ACK (aka. bug)
UnknownACK :: ACKType

-- | A response is either an <a>MPDError</a> or some result.
type Response = Either MPDError
type Host = String
type Port = Integer
type Password = String

-- | A wrapper for <a>withMPDEx</a> that uses localhost:6600 as the default
--   host:port, or whatever is found in the environment variables MPD_HOST
--   and MPD_PORT. If MPD_HOST is of the form "password@host" the password
--   will be supplied as well.
--   
--   Examples:
--   
--   <pre>
--   withMPD $ play Nothing
--   withMPD $ add_ "tool" &gt;&gt; play Nothing &gt;&gt; currentSong
--   </pre>
withMPD :: MPD a -> IO (Response a)

-- | The most configurable API for running an MPD action.
withMPDEx :: Host -> Port -> Password -> MPD a -> IO (Response a)
type Artist = String
type Album = String
type Title = String

-- | Used for commands which require a playlist name. If empty, the current
--   playlist is used.
type PlaylistName = String

-- | Used for commands which require a path within the database. If empty,
--   the root path is used.
type Path = String

-- | Available metadata types/scope modifiers, used for searching the
--   database for entries with certain metadata values.
data Metadata
Artist :: Metadata

-- | ArtistSort
Album :: Metadata

-- | AlbumArtist | AlbumArtistSort
Title :: Metadata
Track :: Metadata
Name :: Metadata
Genre :: Metadata
Date :: Metadata
Composer :: Metadata
Performer :: Metadata

-- | Comment
Disc :: Metadata
MUSICBRAINZ_ARTISTID :: Metadata

-- | MUSICBRAINZ_ALBUMID | MUSICBRAINZ_ALBUMARTISTID
MUSICBRAINZ_TRACKID :: Metadata

-- | Object types.
data ObjectType
SongObj :: ObjectType
type Seconds = Integer

-- | Represents the different playback states.
data State
Playing :: State
Stopped :: State
Paused :: State

-- | Represents the various MPD subsystems.
data Subsystem

-- | The song database
DatabaseS :: Subsystem

-- | Database updates
UpdateS :: Subsystem

-- | Stored playlists
StoredPlaylistS :: Subsystem

-- | The current playlist
PlaylistS :: Subsystem

-- | The player
PlayerS :: Subsystem

-- | The volume mixer
MixerS :: Subsystem

-- | Audio outputs
OutputS :: Subsystem

-- | Playback options
OptionsS :: Subsystem
data ReplayGainMode

-- | Disable replay gain
Off :: ReplayGainMode

-- | Per track mode
TrackMode :: ReplayGainMode

-- | Per album mode
AlbumMode :: ReplayGainMode

-- | Represents the result of running <tt>count</tt>.
data Count
Count :: Integer -> Seconds -> Count

-- | Number of songs matching the query
cSongs :: Count -> Integer

-- | Total play time of matching songs
cPlaytime :: Count -> Seconds
defaultCount :: Count

-- | Represents an output device.
data Device
Device :: Int -> String -> Bool -> Device

-- | Output's ID number
dOutputID :: Device -> Int

-- | Output's name as defined in the MPD configuration file
dOutputName :: Device -> String
dOutputEnabled :: Device -> Bool
defaultDevice :: Device

-- | Represents a single song item.
data Song
Song :: String -> Map Metadata [String] -> Maybe UTCTime -> Seconds -> Maybe Id -> Maybe Int -> Song
sgFilePath :: Song -> String

-- | Map of available tags (multiple occurences of one tag type allowed)
sgTags :: Song -> Map Metadata [String]

-- | Last modification date
sgLastModified :: Song -> Maybe UTCTime

-- | Length of the song in seconds
sgLength :: Song -> Seconds

-- | Id in playlist
sgId :: Song -> Maybe Id

-- | Position in playlist
sgIndex :: Song -> Maybe Int
newtype Id
Id :: Int -> Id

-- | Get list of specific tag type
sgGetTag :: Metadata -> Song -> Maybe [String]

-- | Add metadata tag value.
sgAddTag :: Metadata -> String -> Song -> Song
defaultSong :: Song

-- | Container for database statistics.
data Stats
Stats :: Integer -> Integer -> Integer -> Seconds -> Seconds -> Seconds -> Integer -> Stats

-- | Number of artists.
stsArtists :: Stats -> Integer

-- | Number of albums.
stsAlbums :: Stats -> Integer

-- | Number of songs.
stsSongs :: Stats -> Integer

-- | Daemon uptime in seconds.
stsUptime :: Stats -> Seconds

-- | Total playing time.
stsPlaytime :: Stats -> Seconds

-- | Total play time of all the songs in the database.
stsDbPlaytime :: Stats -> Seconds

-- | Last database update in UNIX time.
stsDbUpdate :: Stats -> Integer
defaultStats :: Stats

-- | Container for MPD status.
data Status
Status :: State -> Int -> Bool -> Bool -> Integer -> Integer -> Maybe Int -> Maybe Id -> Maybe Int -> Maybe Id -> (Double, Seconds) -> Int -> Seconds -> Double -> Double -> (Int, Int, Int) -> Integer -> Bool -> Bool -> Maybe String -> Status
stState :: Status -> State

-- | A percentage (0-100)
stVolume :: Status -> Int
stRepeat :: Status -> Bool
stRandom :: Status -> Bool

-- | A value that is incremented by the server every time the playlist
--   changes.
stPlaylistVersion :: Status -> Integer

-- | The number of items in the current playlist.
stPlaylistLength :: Status -> Integer

-- | Current song's position in the playlist.
stSongPos :: Status -> Maybe Int

-- | Current song's playlist ID.
stSongID :: Status -> Maybe Id

-- | Next song's position in the playlist.
stNextSongPos :: Status -> Maybe Int

-- | Next song's playlist ID.
stNextSongID :: Status -> Maybe Id

-- | Time elapsed/total time.
stTime :: Status -> (Double, Seconds)

-- | Bitrate (in kilobytes per second) of playing song (if any).
stBitrate :: Status -> Int

-- | Crossfade time.
stXFadeWidth :: Status -> Seconds

-- | MixRamp threshold in dB
stMixRampdB :: Status -> Double

-- | MixRamp extra delay in seconds
stMixRampDelay :: Status -> Double

-- | Samplerate/bits/channels for the chosen output device (see mpd.conf).
stAudio :: Status -> (Int, Int, Int)

-- | Job ID of currently running update (if any).
stUpdatingDb :: Status -> Integer

-- | If True, MPD will play only one song and stop after finishing it.
stSingle :: Status -> Bool

-- | If True, a song will be removed after it has been played.
stConsume :: Status -> Bool

-- | Last error message (if any).
stError :: Status -> Maybe String
defaultStatus :: Status

-- | An interface for creating MPD queries.
--   
--   For example, to match any song where the value of artist is "Foo", we
--   use:
--   
--   <pre>
--   Artist =? "Foo"
--   </pre>
--   
--   We can also compose queries, thus narrowing the search. For example,
--   to match any song where the value of artist is "Foo" and the value of
--   album is "Bar", we use:
--   
--   <pre>
--   Artist =? "Foo" &lt;&amp;&gt; Album =? "Bar"
--   </pre>
data Query

-- | Create a query.
(=?) :: Metadata -> String -> Query

-- | Combine queries.
(<&>) :: Query -> Query -> Query

-- | An empty query. Matches anything.
anything :: Query

-- | Clear the current error message in status.
clearError :: MonadMPD m => m ()

-- | Get the currently playing song.
currentSong :: (Functor m, MonadMPD m) => m (Maybe Song)

-- | Wait until there is a noteworthy change in one or more of MPD's
--   susbystems. Note that running this command will block until either
--   <a>idle</a> returns or is cancelled by <a>noidle</a>.
idle :: MonadMPD m => m [Subsystem]

-- | Cancel <a>idle</a>.
noidle :: MonadMPD m => m ()

-- | Get the server's status.
status :: MonadMPD m => m Status

-- | Get server statistics.
stats :: MonadMPD m => m Stats

-- | Set consume mode
consume :: MonadMPD m => Bool -> m ()

-- | Set crossfading between songs.
crossfade :: MonadMPD m => Seconds -> m ()

-- | Set random playing.
random :: MonadMPD m => Bool -> m ()

-- | Set repeating.
repeat :: MonadMPD m => Bool -> m ()

-- | Set the volume (0-100 percent).
setVolume :: MonadMPD m => Int -> m ()

-- | Set single mode
single :: MonadMPD m => Bool -> m ()

-- | Set the replay gain mode.
replayGainMode :: MonadMPD m => ReplayGainMode -> m ()

-- | Get the replay gain options.
replayGainStatus :: MonadMPD m => m [String]

-- | Play the next song.
next :: MonadMPD m => m ()

-- | Pause playing.
pause :: MonadMPD m => Bool -> m ()

-- | Begin/continue playing.
play :: MonadMPD m => Maybe Int -> m ()

-- | Play a file with given id.
playId :: MonadMPD m => Id -> m ()

-- | Play the previous song.
previous :: MonadMPD m => m ()

-- | Seek to some point in a song.
seek :: MonadMPD m => Int -> Seconds -> m ()

-- | Seek to some point in a song (id version)
seekId :: MonadMPD m => Id -> Seconds -> m ()

-- | Stop playing.
stop :: MonadMPD m => m ()

-- | Like <a>add_</a> but returns a list of the files added.
add :: MonadMPD m => Path -> m [Path]

-- | Add a song (or a whole directory) to the current playlist.
add_ :: MonadMPD m => Path -> m ()

-- | Like <a>add</a>, but returns a playlist id.
addId :: MonadMPD m => Path -> Maybe Integer -> m Id

-- | Clear the current playlist.
clear :: MonadMPD m => m ()

-- | Remove a song from the current playlist.
delete :: MonadMPD m => Int -> m ()

-- | Remove a song from the current playlist.
deleteId :: MonadMPD m => Id -> m ()

-- | Move a song to a given position in the current playlist.
move :: MonadMPD m => Int -> Int -> m ()

-- | Move a song from (songid) to (playlist index) in the playlist. If to
--   is negative, it is relative to the current song in the playlist (if
--   there is one).
moveId :: MonadMPD m => Id -> Int -> m ()

-- | Retrieve file paths and positions of songs in the current playlist.
--   Note that this command is only included for completeness sake; it's
--   deprecated and likely to disappear at any time, please use
--   <a>playlistInfo</a> instead.
playlist :: MonadMPD m => m [(Int, Path)]

-- | Displays a list of songs in the playlist. If id is specified, only its
--   info is returned.
playlistId :: MonadMPD m => Maybe Id -> m [Song]

-- | Search for songs in the current playlist with strict matching.
playlistFind :: MonadMPD m => Query -> m [Song]

-- | Retrieve metadata for songs in the current playlist.
playlistInfo :: MonadMPD m => Maybe (Int, Int) -> m [Song]

-- | Search case-insensitively with partial matches for songs in the
--   current playlist.
playlistSearch :: MonadMPD m => Query -> m [Song]

-- | Retrieve a list of changed songs currently in the playlist since a
--   given playlist version.
plChanges :: MonadMPD m => Integer -> m [Song]

-- | Like <a>plChanges</a> but only returns positions and ids.
plChangesPosId :: MonadMPD m => Integer -> m [(Int, Id)]

-- | Shuffle the playlist.
shuffle :: MonadMPD m => Maybe (Int, Int) -> m ()

-- | Swap the positions of two songs.
swap :: MonadMPD m => Int -> Int -> m ()

-- | Swap the positions of two songs (Id version
swapId :: MonadMPD m => Id -> Id -> m ()

-- | Retrieve a list of files in a given playlist.
listPlaylist :: MonadMPD m => PlaylistName -> m [Path]

-- | Retrieve metadata for files in a given playlist.
listPlaylistInfo :: MonadMPD m => PlaylistName -> m [Song]

-- | Retreive a list of stored playlists.
listPlaylists :: MonadMPD m => m [PlaylistName]

-- | Load an existing playlist.
load :: MonadMPD m => PlaylistName -> m ()

-- | Like <a>playlistAdd</a> but returns a list of the files added.
playlistAdd :: MonadMPD m => PlaylistName -> Path -> m [Path]

-- | Add a song (or a whole directory) to a stored playlist. Will create a
--   new playlist if the one specified does not already exist.
playlistAdd_ :: MonadMPD m => PlaylistName -> Path -> m ()

-- | Clear a playlist. If the specified playlist does not exist, it will be
--   created.
playlistClear :: MonadMPD m => PlaylistName -> m ()

-- | Remove a song from a playlist.
playlistDelete :: MonadMPD m => PlaylistName -> Integer -> m ()

-- | Move a song to a given position in the playlist specified.
playlistMove :: MonadMPD m => PlaylistName -> Integer -> Integer -> m ()

-- | Rename an existing playlist.
rename :: MonadMPD m => PlaylistName -> PlaylistName -> m ()

-- | Delete existing playlist.
rm :: MonadMPD m => PlaylistName -> m ()

-- | Save the current playlist.
save :: MonadMPD m => PlaylistName -> m ()

-- | Count the number of entries matching a query.
count :: MonadMPD m => Query -> m Count

-- | Search the database for entries exactly matching a query.
find :: MonadMPD m => Query -> m [Song]

-- | Adds songs matching a query to the current playlist.
findAdd :: MonadMPD m => Query -> m ()

-- | List all metadata of metadata (sic).
list :: MonadMPD m => Metadata -> Query -> m [String]

-- | List the songs (without metadata) in a database directory recursively.
listAll :: MonadMPD m => Path -> m [Path]

-- | Recursive <a>lsInfo</a>.
listAllInfo :: MonadMPD m => Path -> m [Either Path Song]

-- | Non-recursively list the contents of a database directory.
lsInfo :: MonadMPD m => Path -> m [Either Path Song]

-- | Search the database using case insensitive matching.
search :: MonadMPD m => Query -> m [Song]

-- | Update the server's database. If no paths are given, all paths will be
--   scanned. Unreadable or non-existent paths are silently ignored.
update :: MonadMPD m => [Path] -> m ()

-- | Like <a>update</a> but also rescans unmodified files.
rescan :: MonadMPD m => [Path] -> m ()

-- | Reads a sticker value for the specified object.
stickerGet :: MonadMPD m => ObjectType -> String -> String -> m [String]

-- | Adds a sticker value to the specified object.
stickerSet :: MonadMPD m => ObjectType -> String -> String -> String -> m ()

-- | Delete a sticker value from the specified object.
stickerDelete :: MonadMPD m => ObjectType -> String -> String -> m ()

-- | Lists the stickers for the specified object.
stickerList :: MonadMPD m => ObjectType -> String -> m [(String, String)]

-- | Searches the sticker database for stickers with the specified name,
--   below the specified path.
stickerFind :: MonadMPD m => ObjectType -> String -> String -> m [(String, String)]

-- | Close the connection.
close :: MonadMPD m => m ()

-- | Kill the server. Obviously, the connection is then invalid.
kill :: MonadMPD m => m ()

-- | Send password to server to authenticate session. Password is sent as
--   plain text.
password :: MonadMPD m => String -> m ()

-- | Check that the server is still responding.
ping :: MonadMPD m => m ()

-- | Turn off an output device.
disableOutput :: MonadMPD m => Int -> m ()

-- | Turn on an output device.
enableOutput :: MonadMPD m => Int -> m ()

-- | Retrieve information for all output devices.
outputs :: MonadMPD m => m [Device]

-- | Retrieve a list of available commands.
commands :: MonadMPD m => m [String]

-- | Retrieve a list of unavailable (due to access restrictions) commands.
notCommands :: MonadMPD m => m [String]

-- | Retrieve a list of available song metadata.
tagTypes :: MonadMPD m => m [String]

-- | Retrieve a list of supported urlhandlers.
urlHandlers :: MonadMPD m => m [String]

-- | Retreive a list of decoder plugins with associated suffix and mime
--   types.
decoders :: MonadMPD m => m [(String, [(String, String)])]