ruby-mpd 0.1.5 → 0.1.7

data/README.rdoc

@@ -26,7 +26,7 @@ Then, make a new MPD instance:
 
   mpd = MPD.new 'localhost', 6600
 
-You can also omit the host and/or port, and it will use the defaults.
+You can also omit the host and port, and it will use the defaults.
 
   mpd = MPD.new 'localhost'
   mpd = MPD.new
@@ -43,7 +43,7 @@ When you are done, disconnect by calling disconnect.
 be fixed by enabling callbacks (see the Callbacks section) or by issuing a
 `ping` command at certain intervals
 
-Once connected, you can issue commands to talk to the server
+Once connected, you can issue commands to talk to the server.
 
     mpd.connect
     
@@ -52,34 +52,45 @@ Once connected, you can issue commands to talk to the server
     song = mpd.current_song
     puts "Current Song: #{song.artist} - #{song.title}"
 
-You can find documentation for each command at http://www.rubydoc.info/github/archSeer/ruby-mpd/master/MPD
+You can find command documentation can be found {here}[http://www.rubydoc.info/github/archSeer/ruby-mpd/master/MPD].
 
 == Commands
 
+Some commands require URI paths. ruby-mpd allows you to use MPD::Song objects directly
+and it extracts the file paths behind the scenes.
+
+  song = mpd.songs_by_artist('Elvis Presley').first # => MPD::Song
+  mpd.add song
+
+=== Options
+
 Some commands accept "option hashes" besides their default values. For example, +#move+
 accepts an ID key instead of the position:
 
   mpd.move(1, 10) # => move first song to position 10.
-
-  mpd.move(:id => 1, 10) # => move the song with the ID of 1 to position 10.
+  mpd.move({:id => 1}, 10) # => move the song with the ID of 1 to position 10.
 
 Commands that accept ID's: +#move+, +#delete+, +#play+, +#song_priority+. +#seek+
-accepts both +:pos+ and +:id+. *Note*: #swap and #swapid are still separate!
+accepts both +:pos+ and +:id+. *Note*: +#swap+ and +#swapid+ are still separate!
 
 === Ranges
 
 Some commands also allow ranges instead of numbers, specifying a range of songs.
-ruby-mpd correctly handles inclusive and exclusive ranges (1..10 vs 1...10).
-For example, #queue allows us to return only a subset of the queue:
+ruby-mpd correctly handles inclusive and exclusive ranges (1..10 vs 1...10). Negative
+range end means that we want the range to span until the end of the list.
+
+For example, +#queue+ allows us to return only a subset of the queue:
 
   mpd.queue.count # => 20
 
   mpd.queue(1..10).count # => 10
 
-Move also allows this:
+  mpd.queue(5..-1).count # => 15 (from 5 to the end of the range)
+  mpd.queue(5...-1).count # => 15 (does the same)
 
-  mpd.move 1, 10 # => move song 1 to position 10.
+Move also allows specifying ranges to move a range of songs instead of just one.
 
+  mpd.move 1, 10 # => move song 1 to position 10.
   mpd.move 1..3, 10 # => move songs 1, 2 and 3 to position 10 (and 11 and 12).
 
 Commands that support ranges: +#delete+, +#move+, +#queue+, +#song_priority+, +#shuffle+,
@@ -88,7 +99,7 @@ Commands that support ranges: +#delete+, +#move+, +#queue+, +#song_priority+, +#
 == Searching
 
 Searching is case insensitive by default. To enable case sensitivity, pass a third
-argument in as +:case_sensitive => true+. This does not work for Playlist#searchadd.
+argument with the key +:case_sensitive+. This does not work for Playlist#searchadd.
 
   mpd.search(:artist, 'MyArtiSt', :case_sensitive => true)
 
@@ -104,7 +115,7 @@ Playlists are one of the objects that map the MPD commands onto a simple to use
 object. Instead of going trough all those function calls, passing data along to
 get your results, you simply use the object in an object-oriented way:
 
-  mpd.playlists # 0> [MPD::Playlist, MPD::Playlist...]
+  mpd.playlists # => [MPD::Playlist, MPD::Playlist...]
 
   playlist = mpd.playlists.first
 
@@ -124,8 +135,8 @@ action on them (add, delete, rename).
 
   MPD::Playlist.new(mpd, 'name')
 
-Currently, one also has to pass in the MPD connection, as playlists are tied to
-a certain connection.
+Currently, one also has to pass in the MPD instance, as playlists are tied to a
+certain connection.
 
 == Callbacks
 
@@ -139,24 +150,24 @@ the server without having to worry about timeouts.
 To make use of callbacks, we need to:
 
 1. Setup a callback to be called when something happens.
-2. Connect to the server with callbacks set as enabled.
+2. Connect to the server with callbacks enabled.
 
 Firstly, we need to create a callback block and subscribe it, so that will get
 triggered whenever a specific event happens. When the callback is triggered,
 it will also recieve the new values of the event that happened.
 
-So how do we do this? We use the MPD#on method, which sets it all up for us. The
+So how do we do this? We use the +MPD#on+ method, which sets it all up for us. The
 argument takes a symbol with the name of the event. The function also requires a block,
 which is our actual callback that will get called.
 
   mpd.on :volume do |volume|
-    puts "Volume was set to #{volume}"!
+    puts "Volume was set to #{volume}!"
   end
 
 One can also use separate methods or Procs and whatnot, just pass them in as a parameter.
   
   # Proc
-  proc = Proc.new {|volume| puts "Volume was set to #{volume}"! }
+  proc = Proc.new {|volume| puts "Volume was set to #{volume}!" }
   mpd.on :volume, &proc
 
   # Method
@@ -167,32 +178,33 @@ One can also use separate methods or Procs and whatnot, just pass them in as a p
   method = self.method(:volume_change)
   mpd.on :volume, &method
 
-ruby-mpd supports callbacks for any of the keys returned by MPD#status, as well as +:connection+.
-which will notify us when we connect or disconnect to the daemon. Here's the full list of events,
-along with the variables it will return:
-
-  * *volume*: The volume level as an Integer between 0-100.
-  * *repeat*: true or false
-  * *random*: true or false
-  * *single*: true or false
-  * *consume*: true or false
-  * *playlist*: 31-bit unsigned Integer, the playlist version number.
-  * *playlistlength*: Integer, the length of the playlist
-  * *state*: :play, :stop, or :pause, state of the playback.
-  * *song*: An MPD::Song object, representing the current song.
-  * *songid*: playlist songid of the current song stopped on or playing.
-  * *nextsong*: playlist song number of the next song to be played.
-  * *nextsongid*: playlist songid of the next song to be played.
-  * *time*: Returns two variables, *+total+* and *+elapsed+*, Integers representing seconds.
-  * *elapsed*: Float, representing total time elapsed within the current song, but with higher accuracy.
-  * *bitrate*: instantaneous bitrate in kbps.
-  * *xfade*: crossfade in seconds
-  * *mixrampdb*: mixramp threshold in dB (Float)
-  * *mixrampdelay*: mixrampdelay in seconds
-  * *audio*: Returns three variables: sampleRate, bits and channels.
-  * *updating_db*: job id
-  * *error*: if there is an error, returns message here
-
+ruby-mpd supports callbacks for any of the keys returned by +MPD#status+, as well as +:connection+.
+Here's the full list of events, along with the variables it will return:
+
+* *volume*: The volume level as an Integer between 0-100.
+* *repeat*: true or false
+* *random*: true or false
+* *single*: true or false
+* *consume*: true or false
+* *playlist*: 31-bit unsigned Integer, the playlist version number.
+* *playlistlength*: Integer, the length of the playlist
+* *state*: :play, :stop, or :pause, state of the playback.
+* *song*: An MPD::Song object, representing the current song.
+* *songid*: playlist songid of the current song stopped on or playing.
+* *nextsong*: playlist song number of the next song to be played.
+* *nextsongid*: playlist songid of the next song to be played.
+* *time*: Returns two variables, *+total+* and *+elapsed+*, Integers representing seconds.
+* *elapsed*: Float, representing total time elapsed within the current song, but with higher accuracy.
+* *bitrate*: instantaneous bitrate in kbps.
+* *xfade*: crossfade in seconds
+* *mixrampdb*: mixramp threshold in dB (Float)
+* *mixrampdelay*: mixrampdelay in seconds
+* *audio*: Returns three variables: sampleRate, bits and channels.
+* *updating_db*: job id
+* *error*: if there is an error, returns message here
+
+* *connection*: Are we connected to the daemon? true or false
+ 
 Note that if the callback returns more than one value, the callback needs more arguments
 in order to recieve those values:
 
@@ -208,10 +220,53 @@ in order to recieve those values:
 Finally, the easiest step. In order for callbacks to work, connect to the server
 with callbacks enabled:
 
-    mpd.connect true
+  mpd.connect true
 
 Easy as pie. The above will connect to the server like normal, but this time it will
 create a new thread that loops until you issue a `disconnect`. This loop checks the
 server, then sleeps for two tenths of a second, then loops. Because it's continuously
 polling the server, there's the added benefit of your client not being disconnected
 due to inactivity.
+
+== Not yet implemented
+
+This section documents the features that are missing in this library at the moment.
+
+=== Command lists
+
+Command lists are not implemented yet. The proposed API would look like:
+
+  mpd.command_list do
+    volume 80
+    repeat true
+    status
+  end
+
+What makes me not so eager to implement this is that MPD returns all values one after
+another. This gets fixed with +command_list_ok_begin+, which returns +list_OK+ for every
+command used, however then we still get more than one response, and I can't think of a
+reasonable way to retun all of them back to the user. Maybe just ignore the return values?
+
+=== Idle
+
+To implement idle, what is needed is a lock that prevents sending commands to the daemon
+while waiting for the response (except +noidle+). An intermediate solution would be to
+queue the commands to send them later, when idle has returned the response.
+
+Idle seems like a possible way to reimplement callbacks; make a separate connection
+and just use idle and when it returns, simply use idle again and again.
+
+=== Tests
+
+Tests fail at the moment, as they are 6 years old. The entire MPD server mock class
+either needs to be rewritten, or a mpd.conf along with a sample database and instructions
+for a controlled environment needs to be written.
+
+== TODO list
+
+* MPD::Song, MPD::Directory.
+* Make stickers a mixin for Playlist, Song, Directory...
+* Namespace queue
+* Make parsing per-command (because playlist is an integer in the :status command and
+  a string in :listplaylists, and :time is an array in status and integer in songs)
+* Per command parsing should also skip :directory and :playlist keys inside #songs command.

data/lib/ruby-mpd.rb

@@ -1,6 +1,7 @@
 require 'socket'
 require 'thread'
 
+require 'ruby-mpd/exceptions'
 require 'ruby-mpd/song'
 require 'ruby-mpd/parser'
 require 'ruby-mpd/playlist'
@@ -16,27 +17,6 @@ require 'ruby-mpd/plugins/outputs'
 require 'ruby-mpd/plugins/reflection'
 require 'ruby-mpd/plugins/channels'
 
-# TODO: object oriented: song commands and dir commands
-# in MPD::Song, MPD::Directory.
-# Make stickers a mixin for Playlist, Song, Directory...
-# TODO: Namespace queue?
-# TODO: fix parser to use build_group also
-
-# command list as a do block
-# mpd.command_list do
-#   volume 10
-#   play xyz
-# end
-
-# Playlist#rename -> Playlist#name= ?
-#   MPD::Playlist.new(mpd, 'name')  no mpd?
-
-# make it possible to use MPD::Song objects instead of filepath strings
-
-# commands missing: #plchangeposid, #lsinfo, #listall.
-
-# error codes stored in ack.h
-
 # @!macro [new] error_raise
 #   @raise (see #send_command)
 # @!macro [new] returnraise
@@ -45,10 +25,6 @@ require 'ruby-mpd/plugins/channels'
 
 # The main class/namespace of the MPD client.
 class MPD
-
-  # Standard MPD error.
-  class MPDError < StandardError; end
-
   include Parser
 
   include Plugins::Information
@@ -64,8 +40,6 @@ class MPD
 
   # The version of the MPD protocol the server is using.
   attr_reader :version
-  # A list of tags MPD accepts.
-  attr_reader :tags
 
   # Initialize an MPD object with the specified hostname and port.
   # When called without arguments, 'localhost' and 6600 are used.
@@ -74,6 +48,7 @@ class MPD
     @port = port
     @socket = nil
     @version = nil
+    @tags = nil
 
     @stop_cb_thread = false
     @mutex = Mutex.new
@@ -85,15 +60,18 @@ class MPD
   # that specific event happens.
   #
   #   mpd.on :volume do |volume|
-  #     puts "Volume was set to #{volume}"!
+  #     puts "Volume was set to #{volume}!"
   #   end
   #
   # One can also define separate methods or Procs and whatnot,
   # just pass them in as a parameter.
   #
-  #  method = Proc.new {|volume| puts "Volume was set to #{volume}"! }
+  #  method = Proc.new {|volume| puts "Volume was set to #{volume}!" }
   #  mpd.on :volume, &method
   #
+  # @param [Symbol] event The event we wish to listen for.
+  # @param [Proc, Method] block The actual callback.
+  # @return [void]
   def on(event, &block)
     @callbacks[event] ||= []
     @callbacks[event].push block
@@ -101,6 +79,7 @@ class MPD
 
   # Triggers an event, running it's callbacks.
   # @param [Symbol] event The event that happened.
+  # @return [void]
   def emit(event, *args)
     @callbacks[event] ||= []
     @callbacks[event].each do |handle|
@@ -120,7 +99,7 @@ class MPD
   # @return [true] Successfully connected.
   # @raise [MPDError] If connect is called on an already connected instance.
   def connect(callbacks = false)
-    raise MPDError, 'Already Connected!' if self.connected?
+    raise ConnectionError, 'Already connected!' if self.connected?
 
     @socket = File.exists?(@hostname) ? UNIXSocket.new(@hostname) : TCPSocket.new(@hostname, @port)
     @version = @socket.gets.chomp.gsub('OK MPD ', '') # Read the version
@@ -182,14 +161,16 @@ class MPD
   # Disconnect from the MPD daemon. This has no effect if the client is not
   # connected. Reconnect using the {#connect} method. This will also stop
   # the callback thread, thus disabling callbacks.
+  # @return [Boolean] True if successfully disconnected, false otherwise.
   def disconnect
     @stop_cb_thread = true
 
-    return if @socket.nil?
+    return false if !@socket
 
     @socket.puts 'close'
     @socket.close
     @socket = nil
+    return true
   end
 
   # Kills the MPD process.
@@ -198,8 +179,9 @@ class MPD
     send_command :kill
   end
 
-  # Used for authentication with the server
+  # Used for authentication with the server.
   # @param [String] pass Plaintext password
+  # @macro returnraise
   def password(pass)
     send_command :password, pass
   end
@@ -210,64 +192,26 @@ class MPD
     send_command :ping
   end
 
-  ###--- OTHER ---###
-
-  # Lists all of the albums in the database.
-  # The optional argument is for specifying an artist to list
-  # the albums for
-  #
-  # @return [Array<String>] An array of album names.
-  def albums(artist = nil)
-    list :album, artist
-  end
-
-  # Lists all of the artists in the database.
-  #
-  # @return [Array<String>] An array of artist names.
-  def artists
-    list :artist
-  end
-
-  # List all of the directories in the database, starting at path.
-  # If path isn't specified, the root of the database is used
-  #
-  # @return [Array<String>] Array of directory names
-  def directories(path = nil)
-    response = send_command :listall, path
-    return response[:directory]
-  end
-
-  # List all of the files in the database, starting at path.
-  # If path isn't specified, the root of the database is used
+  # Used to send a command to the server, and to recieve the reply.
+  # Reply gets parsed. Synchronized on a mutex to be thread safe.
   #
-  # @return [Array<String>] Array of file names
-  def files(path = nil)
-    response = send_command(:listall, path)
-    return response[:file]
-  end
-
-  # List all of the songs by an artist.
-  #
-  # @return [Array<MPD::Song>]
-  def songs_by_artist(artist)
-    search :artist, artist
-  end
-
-  # Used to send a command to the server. This synchronizes
-  # on a mutex to be thread safe
+  # Can be used to get low level direct access to MPD daemon. Not
+  # recommended, should be just left for internal use by other
+  # methods.
   #
   # @return (see #handle_server_response)
   # @raise [MPDError] if the command failed.
   def send_command(command, *args)
-    raise MPDError, "Not Connected to the Server" if @socket.nil?
+    raise ConnectionError, "Not connected to the server!" if @socket.nil?
 
     @mutex.synchronize do
       begin
         @socket.puts convert_command(command, *args)
-        return handle_server_response
+        response = handle_server_response
+        return parse_response(command, response)
       rescue Errno::EPIPE
         @socket = nil
-        raise MPDError, 'Broken Pipe (Disconnected)'
+        raise ConnectionError, 'Broken pipe (got disconnected)'
       end
     end
   end
@@ -275,8 +219,7 @@ class MPD
   private
 
   # Handles the server's response (called inside {#send_command}).
-  # Repeatedly reads the server's response from the socket and
-  # processes the output.
+  # Repeatedly reads the server's response from the socket.
   #
   # @return (see Parser#build_response)
   # @return [true] If "OK" is returned.
@@ -302,11 +245,27 @@ class MPD
 
     if !error
       return true if msg.empty?
-      return build_response(msg)
+      return msg
     else
       err = error.match(/^ACK \[(?<code>\d+)\@(?<pos>\d+)\] \{(?<command>.*)\} (?<message>.+)$/)
-      raise MPDError, "#{err[:code]}: #{err[:command]}: #{err[:message]}"
+      raise SERVER_ERRORS[err[:code].to_i], "[#{err[:command]}] #{err[:message]}"
     end
   end
 
+  SERVER_ERRORS = {
+    1 => NotListError,
+    2 => ServerArgumentError,
+    3 => IncorrectPassword,
+    4 => PermissionError,
+    5 => ServerError,
+
+    50 => NotFound,
+    51 => PlaylistMaxError,
+    52 => SystemError,
+    53 => PlaylistLoadError,
+    54 => AlreadyUpdating,
+    55 => NotPlaying,
+    56 => AlreadyExists
+  }
+
 end