;; eggdoc for mpd-client.egg

(require-library eggdoc)
(import eggdoc)

(define mpd-client-license
  `(pre #<<EOF
Copyright (c) 2006-2007, Hans Bulfone
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the author nor the names of his contributors may
      be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
EOF
))

(define mpd-client-example
  `(pre #<<EOF
#!/usr/local/bin/csi -script

(require-extension mpd-client srfi-18 utils)

(define mpd (mpd:connect))

(define (get-mpd-status)
  (let ((status (mpd:status mpd)))
    (list (alist-ref 'songid status)
          (alist-ref 'state status))))

(define (get-songname id)
  (let ((info (car (mpd:playlist/id mpd id))))
    (or (alist-ref 'Title info)
        (pathname-strip-directory
         (alist-ref 'file info)))))

(let loop ((status (get-mpd-status)) (old-status #f))
  (unless (equal? status old-status)
    (let ((song (car status))
          (state (cadr status)))
      (cond
       ((eq? state 'play)
        (printf "Now playing: ~a\n"
                (if song
                    (get-songname song)
                    "(unknown song)")))

       ((eq? state 'stop)
        (printf "STOP\n")))))
  (thread-sleep! 1)
  (loop (get-mpd-status) status))
EOF
))

(define mpd-stats-example
  `(pre #<<EOF
#;6> (pp (mpd:stats m))
((artists . 183)
 (albums . 429)
 (songs . 6200)
 (uptime . 130260)
 (playtime . 49958)
 (db_playtime . 1773229)
 (db_update . 1152376960.0))
#;7>
EOF
))

(define mpd-status-example
  `(pre #<<EOF
#;9> (pp (mpd:status m))
((volume . 78)
 (repeat . #f)
 (random . #f)
 (playlist . 78)
 (playlistlength . 77)
 (xfade . 0)
 (state . play)
 (song . 12)
 (songid . 12)
 (time 31 623)
 (bitrate . 128)
 (audio 44100 16 2))
#;10>
EOF
))

(define mpd-playlist-example
  `(pre #<<EOF
#;10>  (pp (mpd:playlist/id m 12))
(((Id . 12)
  (Pos . 12)
  (Time . 623)
  (Title . "the leper affinity")
  (Track . 1)
  (Album . "blackwater park")
  (Artist . "opeth")
  (file . "metal/opeth/blackwater park/01 the leper affinity.mp3")))
#;11>
EOF
))

(define mpd-find-example
  `(pre #<<EOF
#;13> (pp (mpd:find/album m "catch 33"))
(((Time . 101)
  (Title . "autonomy lost")
  (Track . 1)
  (Album . "catch 33")
  (Artist . "meshuggah")
  (file . "metal/meshuggah/catch 33/01 autonomy lost.mp3"))
 ((Time . 96)
  (Title . "imprint of the un-saved")
  (Track . 2)
  (Album . "catch 33")
  (Artist . "meshuggah")
  (file . "metal/meshuggah/catch 33/02 imprint of the un-saved.mp3"))
...
#;14>
EOF
))

(define doc
  `((eggdoc:begin
     (name "mpd-client")
     (description "Interface to " (a (@ (href "http://www.musicpd.org/")) "Music Player Daemon"))
     (author (a (@ (href "http://www.nil.at/"))
		"Hans Bulfone"))
     (history (version "1.0" "Initial release")
              (version "1.01" "Fixed typo in documentation")
              (version "1.02" "Fixed a bug that caused playlists to be returned incorrectly by " (tt "mpd:ls/info") " et al.")
              (version "1.1"  "Added new commands supported by recent versions of MPD"))
     (usage)
     (download "mpd-client.egg")
     
     (documentation
      (p "This extension allows convenient access to the tcp interface of "
	 (a (@ (href "http://www.musicpd.org/"))
	    "MPD")
	 ".")
      (subsection
       "Connecting to MPD and obtaining connection/server information"
       (group
	(procedure "(mpd:connect [HOST] [PORT] [PASSWORD])"
                   "Connects to the MPD instance running on " (tt "HOST") " (defaults to " (tt "localhost") ") at "
                   (tt "PORT") " (defaults to " (tt "6600") ").  Optionally authenticates using " (tt "PASSWORD")
                   ". Returns an MPD connection object.")
        (procedure "(mpd:reconnect CONN)"
                   "Reconnects the given MPD connection object.  This function should normally not be needed as "
                   "the library automatically reconnects if needed.")
        (procedure "(mpd-conn? CONN)"
                   "Returns " (tt "#t") " if " (tt "CONN") " is an MPD connection object, " (tt "#f") " otherwise.")
        (procedure "(mpd:host CONN)"
                   "Returns the hostname field of the MPD connection object " (tt "CONN") ".")
        (procedure "(mpd:port CONN)"
                   "Returns the port field of the MPD connection object " (tt "CONN") ".")
        (procedure "(mpd:password CONN)"
                   "Returns the password field of the MPD connection object " (tt "CONN") ".  This is either "
                   "a string containing the plain text password or " (tt "#f") " if no authentication should be done.")
        (procedure "(mpd:version CONN)"
                   "Returns the version field of the MPD connection object " (tt "CONN") " which contains the "
                   "version number received by the MPD server.")
        (procedure "(mpd:close CONN)"
                   "Closes the connection to MPD.  " (tt "CONN") " should not be used anymore after calling "
                   "this function.")
        (procedure "(mpd:ping CONN)"
                   "Sends a " (tt "ping") " command to the MPD server, reconnecting if necessary.")
        (procedure "(mpd:clear-error CONN)"
                   "Clears the current error message (which is returned by " (tt "(mpd:status)") "). "
                   "This is also done by any command that starts playback.")
        (procedure "(mpd:stats CONN)"
          (p "Returns an alist containing various stats:")
          ,mpd-stats-example)
        (procedure "(mpd:status CONN)"
          (p "Return an alist describing the current status of MPD:")
          ,mpd-status-example)
        (procedure "(mpd:kill CONN)"
                   "Kill MPD.")
        (procedure "(mpd:send-password CONN PASSWORD)"
                   "Sends " (tt "PASSWORD") " (a string containing the plain text password) "
                   "to the server for authentication.  Normally, this not needed as the password "
                   "can be specified when creating the connection which has the advantage that it's "
                   "automatically sent after having reconnected.")
        (procedure "(mpd:commands CONN)"
                   "Returns a list of commands the current user has access to.")
        (procedure "(mpd:not-commands CONN)"
                   "Returns a list of commands the current user doesn't have access to.")
        ))

      (subsection
       "Controlling playback"
       (group
        (procedure "(mpd:play/pos CONN POS)"
                   "Start playing at position " (tt "POS") ".")
        (procedure "(mpd:play/id CONN ID)"
                   "Start playing at song with id " (tt "ID") ".")
        (procedure "(mpd:seek/pos CONN POS SECS)"
                   "Seeks to " (tt "SECS") " in the song at position " (tt "POSITION") ".")
        (procedure "(mpd:seek/id CONN ID SECS)"
                   "Seeks to " (tt "SECS") " in the song with id " (tt "ID") ".")
        (procedure "(mpd:next CONN)"
                   "Play the next song in the playlist.")
        (procedure "(mpd:previous CONN)"
                   "Play the previous song in the playlist.")
        (procedure "(mpd:stop CONN)"
                   "Stop playback.")
        (procedure "(mpd:pause CONN PAUSE?)"
                   "Pause if " (tt "PAUSE?") " is true, resume playing otherwise.")
        (procedure "(mpd:random CONN RANDOM?)"
                   "Enable or disable random.")
        (procedure "(mpd:repeat CONN REPEAT?)"
                   "Enable or disable repeat.")
        (procedure "(mpd:crossfade CONN SECS)"
                   "Sets the cross fading setting to " (tt "SECS") " seconds (0 = disabled).")
        (procedure "(mpd:set-vol CONN VOLUME)"
                   "Sets the volume to " (tt "VOLUME") " (a fixnum in the range 0-100).")
        ))

      (subsection
       "Managing output devices"
       (group
        (procedure "(mpd:outputs CONN)"
                   "Returns a list of alists describing the available output devices.")
        (procedure "(mpd:enable-output CONN ID)"
                   "Enables the output device with id " (tt "ID") ".")
        (procedure "(mpd:disable-output CONN ID)"
                   "Disables the output device with id " (tt "ID") ".")
        ))
      
      (subsection
       "Querying and modifying the current playlist"
       (group
        (procedure "(mpd:playlist/pos CONN [POS])"
          (p "Return a list of alists describing the songs in the current playlist. "
             "(Optionally only the song at position " (tt "POS") ").  See below for an "
             "example of the result format."))
        (procedure "(mpd:playlist/id CONN [ID])"
          (p "Return a list of alists describing the songs in the current playlist. "
             "(Optionally only the song with id " (tt "ID") "):")
          ,mpd-playlist-example)
        (procedure "(mpd:current-song CONN)"
          "Returns an alist with information about the current song (the same information that "
          (tt "(mpd:playlist/id)") " returns).")
        (procedure "(mpd:pl-changes CONN VERSION)"
                   "Return a list of alists describing new songs since playlist version " (tt "VERSION") ". "
                   "Note: to detect songs that were deleted at the end of the playlist, "
                   "use the " (tt "playlistlength") " returned by " (tt "(mpd:status)") ".")
        (procedure "(mpd:pl-changes/pos+id CONN VERSION)"
                   "Similar to " (tt "mpd:pl-changes") " but only returns the position "
                   "and id of each song.")
        (procedure "(mpd:add CONN PATH)"
                   "Adds " (tt "PATH") " (a string naming a file or directory) to the end of the current "
                   "playlist.  Directories are added recursively.  Increments playlist version by 1 for "
                   "each added song.")
        (procedure "(mpd:add/id CONN PATH)"
                   "Similar to " (tt "mpd:add") " but returns a list of ids of the "
                   "newly added songs.")
        (procedure "(mpd:move/pos CONN FROM TO)"
                   "Move song at position " (tt "FROM") " to " (tt "TO") ".  The playlist version is "
                   "incremented by 1.")
        (procedure "(mpd:move/id CONN ID TO)"
                   "Move song with id " (tt "ID") " to " (tt "TO") ".  The playlist version is "
                   "incremented by 1.")
        (procedure "(mpd:swap/pos CONN POS1 POS2)"
                   "Swap position of the two songs given by playlist positions " (tt "POS1") " and " (tt "POS2") ".")
        (procedure "(mpd:swap/id CONN ID1 ID2)"
                   "Swap position of the two songs given by ids " (tt "ID1") " and " (tt "ID2") ".")
        (procedure "(mpd:delete/pos CONN POS)"
                   "Remove the song at position " (tt "POS") " from playlist.  The playlist version "
                   "is incremented by 1.")
        (procedure "(mpd:delete/id CONN ID)"
                   "Remove the song with id " (tt "ID") " from playlist.  The playlist version "
                   "is incremented by 1.")
        (procedure "(mpd:shuffle CONN)"
                   "Shuffles the current playlist and increments the playlist version by 1.")
        (procedure "(mpd:clear CONN)"
                   "Clears the current playlist, incrementing playlist version by 1.")
        ))

      (subsection
       "Managing stored playlist"
       (group
        (procedure "(mpd:load-playlist CONN PLAYLIST)"
                   "Loads the playlist named " (tt "\"PLAYLIST.m3u\"") " from the playlist directory. "
                   "The playlist version is incremented by the number of songs added.")
        (procedure "(mpd:rm-playlist CONN PLAYLIST)"
                   "Removes the playlist named " (tt "\"PLAYLIST.m3u\"") " from the playlist directory.")
        (procedure "(mpd:save-playlist CONN PLAYLIST)"
                   "Saves the current playlist to " (tt "\"PLAYLIST.m3u\"") " in the playlist directory.")
        ))

      (subsection
       "Querying/Updating song database"
       (group
        (procedure "(mpd:find CONN TYPE STRING)"
                   "Searches for songs and returns a list of alists.  "
                   (tt "TYPE") " is e.g. " (tt "'title") ", " (tt "'album") " or "
                   (tt "'artist") ".  " (tt "STRING") " is the search string "
                   "(which must match exactly).")
        (procedure "(mpd:find/album CONN ALBUM)"
          (p "Returns a list of alists describing songs on album " (tt "ALBUM") " (a string).")
          ,mpd-find-example)
        (procedure "(mpd:find/artist CONN ARTIST)"
                   "Returns a list of alists describing songs from " (tt "ARTIST") " (a string).")
        (procedure "(mpd:find/title CONN TITLE)"
                   "Returns a list of alists describing songs with title " (tt "TITLE") " (a string).")
        (procedure "(mpd:search CONN TYPE SEARCHSTRING)"
                   "Returns a list of alists describing the matching songs.  "
                   (tt "TYPE") " is e.g. " (tt "'title") ", " (tt "'album") " or "
                   (tt "'artist") ".  " (tt "SEARCHSTRING") " is the string "
                   "which is searched for (not case sensitive, doesn't need to be "
                   "an exact match).")
        (procedure "(mpd:search/album CONN SEARCHSTRING)"
                   "Returns a list of alists describing songs whose album names contain " (tt "SEARCHSTRING")
                   " (not case sensitive).")
        (procedure "(mpd:search/artist CONN SEARCHSTRING)"
                   "Returns a list of alists describing songs whose artist names contain " (tt "SEARCHSTRING")
                   " (not case sensitive).")
        (procedure "(mpd:search/title CONN SEARCHSTRING)"
                   "Returns a list of alists describing songs whose titles contain " (tt "SEARCHSTRING")
                   " (not case sensitive).")
        (procedure "(mpd:search/filename CONN SEARCHSTRING)"
                   "Returns a list of alists describing songs whose filenames contain " (tt "SEARCHSTRING")
                   " (not case sensitive).")
        (procedure "(mpd:list CONN TYPE [LIMIT STRING])"
                   "Return a list of values of metadata " (tt "TYPE") " (e.g. " (tt "'title") ", "
                   (tt "'album") " or " (tt "'artist") "), optionally limited by "
                   (tt "LIMIT") " and " (tt "STRING") "." (br)
                   "E.g. " (tt "(mpd:list m 'album 'artist \"nevermore\")")
                   " to get a list of all albums by Nevermore.")
        (procedure "(mpd:list-artists CONN)"
                   "Returns a list of all known artists.")
        (procedure "(mpd:list-albums CONN [ARTIST])"
                   "Returns a list of all known albums, optionally limited by " (tt "ARTIST") ".")
        (procedure "(mpd:list-all CONN [PATH])"
                   "Returns a list of filenames of all songs (below " (tt "PATH") ", if given).")
        (procedure "(mpd:list-all/info CONN [PATH])"
                   "Like " (tt "(mpd:list-all)") ", but also returns metadata.  The data is returned "
                   "as a list of alists.")
        (procedure "(mpd:ls/info CONN [DIR])"
                   "Returns a list of alists describing the contents of " (tt "DIR") " (a string). "
                   "This function is like " (tt "(mpd:list-all/info)") ", but doesn't operate recursively.")
        (procedure "(mpd:update CONN [PATH])"
                   "Updates MPD's database, removing old songs and adding new songs.  Optionally, the "
                   "update process can be limited to " (tt "PATH") " (a string naming a file or directory).")
        ))
      )
     
     (examples
      ,mpd-client-example)

     (license ,mpd-client-license))))


(if (eggdoc->html doc) (void))