-- 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.4.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
getPassword :: (MonadMPD m) => m Password

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


-- | 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 Meta
Artist :: Meta
Album :: Meta
Title :: Meta
Track :: Meta
Name :: Meta
Genre :: Meta
Date :: Meta
Composer :: Meta
Performer :: Meta
Disc :: Meta
Any :: Meta
Filename :: Meta

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

-- | Represents a song's playlist index.
data PLIndex

-- | A playlist position index (starting from 0)
Pos :: Integer -> PLIndex

-- | A playlist ID number that more robustly identifies a song.
ID :: Integer -> PLIndex

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

-- | Represents the various MPD subsystems.
data Subsystem

-- | The song database
Database :: Subsystem

-- | Database updates
Update :: Subsystem

-- | Stored playlists
StoredPlaylist :: Subsystem

-- | The current playlist
Playlist :: Subsystem

-- | The player
Player :: Subsystem

-- | The volume mixer
Mixer :: Subsystem

-- | Audio outputs
Output :: Subsystem

-- | Playback options
Options :: 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

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

-- | Represents a single song item.
data Song

-- | Auxiliary song fields
Song :: String -> String -> String -> String -> String -> String -> String -> String -> Seconds -> Int -> (Int, Int) -> Maybe (Int, Int) -> Maybe PLIndex -> [(String, String)] -> Song
sgArtist :: Song -> String
sgAlbum :: Song -> String
sgTitle :: Song -> String
sgFilePath :: Song -> String
sgGenre :: Song -> String
sgName :: Song -> String
sgComposer :: Song -> String
sgPerformer :: Song -> String

-- | Length in seconds
sgLength :: Song -> Seconds

-- | Year
sgDate :: Song -> Int

-- | Track number/total tracks
sgTrack :: Song -> (Int, Int)

-- | Position in set/total in set
sgDisc :: Song -> Maybe (Int, Int)
sgIndex :: Song -> Maybe PLIndex
sgAux :: Song -> [(String, String)]
defaultSong :: Song

-- | Container for MPD status.
data Status
Status :: State -> Int -> Bool -> Bool -> Integer -> Integer -> Maybe PLIndex -> Maybe PLIndex -> Maybe PLIndex -> Maybe PLIndex -> (Seconds, Seconds) -> Int -> Seconds -> (Int, Int, Int) -> Integer -> Bool -> Bool -> 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 PLIndex

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

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

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

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

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

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

-- | 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 -> 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.
(=?) :: Meta -> 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 PLIndex -> m ()

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

-- | Seek to some point in a song. Seeks in current song if no position is
--   given.
seek :: (MonadMPD m) => Maybe PLIndex -> 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 Integer

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

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

-- | Move a song to a given position in the current playlist.
move :: (MonadMPD m) => PLIndex -> Integer -> 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 [(PLIndex, Path)]

-- | 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 (Either PLIndex (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 [(PLIndex, PLIndex)]

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

-- | Swap the positions of two songs. Note that the positions must be of
--   the same type, i.e. mixing <a>Pos</a> and <a>ID</a> will result in a
--   no-op.
swap :: (MonadMPD m) => PLIndex -> PLIndex -> 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) => Meta -> 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)])]

-- | 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
--   <a>prune</a> for this).
deleteMany :: (MonadMPD m) => PlaylistName -> [PLIndex] -> m ()

-- | Returns all songs and directories that match the given partial path
--   name.
complete :: (MonadMPD m) => String -> m [Either Path Song]

-- | Crop playlist. The bounds are inclusive. If <a>Nothing</a> is passed
--   the cropping will leave your playlist alone on that side. Using
--   <a>ID</a> will automatically find the absolute playlist position and
--   use that as the cropping boundary.
crop :: (MonadMPD m) => Maybe PLIndex -> Maybe PLIndex -> m ()

-- | Remove duplicate playlist entries.
prune :: (MonadMPD m) => m ()

-- | List directories non-recursively.
lsDirs :: (MonadMPD m) => Path -> m [Path]

-- | List files non-recursively.
lsFiles :: (MonadMPD m) => Path -> m [Path]

-- | List all playlists.
lsPlaylists :: (MonadMPD m) => m [PlaylistName]

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

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

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

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