ruby-mpd 0.1.4 → 0.1.5

data/README.rdoc

@@ -1,7 +1,7 @@
 = ruby-mpd
 
 ruby-mpd is a powerful object-oriented Music Player Daemon library, forked from librmpd.
-librmpd is as of writing outdated by 6(*!*) years. This library tries to act as a successor,
+librmpd is as of writing outdated by 6 years! This library tries to act as a successor,
 originally using librmpd as a base, however almost all of the codebase was rewritten.
 ruby-mpd supports all "modern" MPD features.
 
@@ -22,7 +22,7 @@ Require the library.
 
   require 'ruby-mpd'
 
-Then, make a new object:
+Then, make a new MPD instance:
 
   mpd = MPD.new 'localhost', 6600
 
@@ -31,8 +31,7 @@ You can also omit the host and/or port, and it will use the defaults.
   mpd = MPD.new 'localhost'
   mpd = MPD.new
 
-
-Once you have an instance of the MPD class, connect to the server:
+Once you have an instance of the MPD class, connect to the server.
 
   mpd.connect
 
@@ -47,13 +46,57 @@ be fixed by enabling callbacks (see the Callbacks section) or by issuing a
 Once connected, you can issue commands to talk to the server
 
     mpd.connect
-    if mpd.stopped?
-      mpd.play
-    end
+    
+    mpd.play if mpd.stopped?
+
     song = mpd.current_song
     puts "Current Song: #{song.artist} - #{song.title}"
 
-You can find documentation for each command [here](TODO)
+You can find documentation for each command at http://www.rubydoc.info/github/archSeer/ruby-mpd/master/MPD
+
+== Commands
+
+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.
+
+Commands that accept ID's: +#move+, +#delete+, +#play+, +#song_priority+. +#seek+
+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:
+
+  mpd.queue.count # => 20
+
+  mpd.queue(1..10).count # => 10
+
+Move also allows this:
+
+  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+,
++MPD::Playlist#load+.
+
+== 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.
+
+  mpd.search(:artist, 'MyArtiSt', :case_sensitive => true)
+
+While searching, one can also enable the +add+ option, which will automatically add
+the songs the query returned to the queue. In that case, the response will only return
++true+, stating that the operation was successful (instead of returning an array).
+
+  mpd.search(:artist, 'MyArtiSt', {:case_sensitive => true, :add => true})
 
 == Playlists
 
@@ -95,9 +138,8 @@ 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.
-
+1. Setup a callback to be called when something happens.
+2. Connect to the server with callbacks set as 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,
@@ -158,6 +200,7 @@ in order to recieve those values:
     puts bits
   end
 
+  # or
   mpd.on :audio do |*args|
     puts args.join(',')
   end

data/lib/ruby-mpd.rb

@@ -33,6 +33,8 @@ require 'ruby-mpd/plugins/channels'
 
 # 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
@@ -248,7 +250,7 @@ class MPD
   #
   # @return [Array<MPD::Song>]
   def songs_by_artist(artist)
-    find :artist, artist
+    search :artist, artist
   end
 
   # Used to send a command to the server. This synchronizes

data/lib/ruby-mpd/playlist.rb

@@ -42,6 +42,18 @@ class MPD
       @mpd.send_command :playlistadd, @name, uri
     end
 
+    # Searches for any song that contains +what+ in the +type+ field
+    # and immediately adds them to the playlist.
+    # Searches are *NOT* case sensitive.
+    #
+    # @param [Symbol] type Can be any tag supported by MPD, or one of the two special
+    #   parameters: +:file+ to search by full path (relative to database root),
+    #   and +:any+ to match against all available tags.
+    # @macro returnraise
+    def searchadd(type, what)
+      send_command :searchaddpl, @name, type, what
+    end
+
     # Clears the playlist.
     # @macro returnraise
     def clear

data/lib/ruby-mpd/plugins/controls.rb

@@ -17,18 +17,20 @@ class MPD
         send_command :pause, toggle
       end
 
-      # Begin playing the playist.
+      # Begin/resume playing the queue.
       # @param [Integer] pos Position in the playlist to start playing.
+      # @param [Hash] pos :id of the song where to start playing.
       # @macro returnraise
       def play(pos = nil)
-        send_command :play, pos
-      end
-
-      # Begin playing the playlist.
-      # @param [Integer] songid ID of the song where to start playing.
-      # @macro returnraise
-      def playid(songid = nil)
-        send_command :playid, songid
+        if pos.is_a?(Hash) 
+          if pos[:id]
+            send_command :playid, priority, pos[:id]
+          else
+            raise ArgumentError, 'Only :id key is allowed!'
+          end
+        else
+          send_command :play, pos
+        end
       end
 
       # Plays the previous song in the playlist.
@@ -43,23 +45,16 @@ class MPD
       #
       # @since MPD 0.17
       # @param [Integer, String] time Position within the current song.
+      # @param [Hash] options Either +:id+ or +:pos+ can be specified.
       # Returns true if successful,
-      def seek(time)
-        send_command :seekcur, time
-      end
-
-      # Seeks to the position +time+ (in seconds) of the
-      # song at +pos+ in the playlist.
-      # @macro returnraise
-      def seekpos(pos, time)
-        send_command :seek, pos, time
-      end
-
-      # Seeks to the position +time+ (in seconds) of the song with
-      # the id of +songid+.
-      # @macro returnraise
-      def seekid(songid, time)
-        send_command :seekid, songid, time
+      def seek(time, options = {})
+        if options[:id]
+          send_command :seekid, options[:id], time
+        elsif options[:pos]
+          send_command :seek, options[:pos], time
+        else
+          send_command :seekcur, time
+        end
       end
 
       # Stop playing.

data/lib/ruby-mpd/plugins/database.rb

@@ -2,7 +2,8 @@ class MPD
   module Plugins
     # Commands for interacting with the music database.
     #
-    # Changes: listallinfo -> songs
+    # Changes: listallinfo -> songs, searchaddpl in MPD::Playlist#searchadd.
+    # search merges search, find, searchadd and findadd
     module Database
 
       # Counts the number of songs and their total playtime
@@ -12,19 +13,6 @@ class MPD
         send_command :count, type, what
       end
 
-      # Finds songs in the database that are *EXACTLY* matched by the what
-      # argument.
-      #
-      # @param [Symbol] type Can be any tag supported by MPD, or one of the two special
-      #   parameters: +:file+ to search by full path (relative to database root),
-      #   and +:any+ to match against all available tags.
-      # @return [Array<MPD::Song>] Songs that matched.
-      def find(type, what)
-        build_songs_list send_command(:find, type, what)
-      end
-
-      # findadd
-
       # List all tags of the specified type.
       # Type can be any tag supported by MPD or +:file+.
       # If type is 'album' then arg can be a specific artist to list the albums for
@@ -47,17 +35,28 @@ class MPD
       # lsinfo
 
       # Searches for any song that contains +what+ in the +type+ field.
-      # Searches are *NOT* case sensitive.
+      # Searches are case insensitive by default, however you can enable
+      # it using the third argument.
       #
-      # @param (see #find)
+      # Options:
+      # * *add*: Add the search results to the queue.
+      # * *case_sensitive*: Make the query case sensitive.
+      #
+      # @param [Symbol] type Can be any tag supported by MPD, or one of the two special
+      #   parameters: +:file+ to search by full path (relative to database root),
+      #   and +:any+ to match against all available tags.
+      # @param [Hash] options A hash of options.
       # @return [Array<MPD::Song>] Songs that matched.
-      def search(type, what)
-        build_songs_list(send_command(:search, type, what))
-      end
-
-      # searchadd
+      # @return [true] if +:add+ is enabled.
+      def search(type, what, options = {})
+        if options[:add]
+          command = options[:case_sensitive] ? :findadd : :searchadd
+        else
+          command = options[:case_sensitive] ? :find : :search
+        end
 
-      # searchaddpl
+        build_songs_list send_command(command, type, what)
+      end
 
       # Tell the server to update the database. Optionally,
       # specify the path to update.

data/lib/ruby-mpd/plugins/queue.rb

@@ -4,7 +4,8 @@ class MPD
     # For a distinction between this and other playlists, this is called
     # queue. 
     # Changes: playlistinfo -> queue, plchanges -> queue_changes,
-    #  playlistid -> song_with_id.
+    #  playlistid -> song_with_id, playlistfind -> queue_find,
+    #  playlistsearch -> queue_search, prio -> song_priority.
     module Queue
 
       # List the current playlist/queue.
@@ -41,15 +42,18 @@ class MPD
       # Since MPD 0.15 a range can also be passed. Songs with positions within range will be deleted.
       # @param [Integer, Range] pos Song with position in the queue will be deleted,
       # if range is passed, songs with positions within range will be deleted.
+      # @param [Hash] pos :id to specify the song ID to delete instead of position.
       # @macro returnraise
       def delete(pos)
-        send_command :delete, pos
-      end
-
-      # Delete the song with the +songid+ from the queue.
-      # @macro returnraise
-      def deleteid(songid)
-        send_command :deleteid, songid
+        if pos.is_a?(Hash) 
+          if pos[:id]
+            send_command :deleteid, pos[:id]
+          else
+            raise ArgumentError, 'Only :id key is allowed!'
+          end
+        else
+          send_command :delete, pos
+        end
       end
 
       # Move the song at +from+ to +to+ in the queue.
@@ -59,26 +63,39 @@ class MPD
       #   Moving a song to -queue.length will move it to the song _before_ the current
       #   song on the queue; so this will work for repeating playlists, too.
       # * Since 0.15, +from+ can be a range of songs to move.
+      # @param [Hash] from :id to specify the song ID to move instead of position.
       # @macro returnraise
       def move(from, to)
-        send_command :move, from, to
-      end
-
-      # Move the song with the +songid+ to +to+ in the queue.
-      # @macro returnraise
-      def moveid(songid, to)
-        send_command :moveid, songid, to
+        if pos.is_a?(Hash) 
+          if pos[:id]
+            send_command :moveid, pos[:id], to
+          else
+            raise ArgumentError, 'Only :id key is allowed!'
+          end
+        else
+          send_command :move, from, to
+        end
       end
 
-      # playlistfind
-
       # Returns the song with the +songid+ in the playlist,
       # @return [MPD::Song]
       def song_with_id(songid)
         Song.new send_command(:playlistid, songid)
       end
 
-      # playlistsearch
+      # Searches for songs in the queue matched by the what
+      # argument. Case insensitive by default.
+      #
+      # @param [Symbol] type Can be any tag supported by MPD, or one of the two special
+      #   parameters: +:file+ to search by full path (relative to database root),
+      #   and +:any+ to match against all available tags.
+      #
+      # @param [Hash] options Use +:case_sensitive+ to make the query case sensitive.
+      # @return [Array<MPD::Song>] Songs that matched.
+      def queue_search(type, what, options = {})
+        command = options[:case_sensitive] ? :playlistfind : :playlistsearch
+        build_songs_list send_command(command, type, what)
+      end
 
       # List the changes since the specified version in the queue.
       # @return [Array<MPD::Song>]
@@ -88,14 +105,28 @@ class MPD
 
       # plchangesposid
 
-      # prio
-
-      # prioid
+      # Set the priority of the specified songs. A higher priority means that it will be played
+      # first when "random" mode is enabled.
+      # @param [Integer] priority An integer between 0 and 255. The default priority of new songs is 0.
+      # @param [Integer] pos A specific position.
+      # @param [Range] pos A range of positions.
+      # @param [Hash] pos :id to specify the song ID to move instead of position.
+      def song_priority(priority, pos)
+        if pos.is_a?(Hash) 
+          if pos[:id]
+            send_command :prioid, priority, pos[:id]
+          else
+            raise ArgumentError, 'Only :id key is allowed!'
+          end
+        else
+          send_command :prio, priority, pos
+        end
+      end
 
       # Shuffles the queue.
       # Optionally, a Range can be used to shuffle a specific subset.
       # @macro returnraise
-      def shuffle(range)
+      def shuffle(range=nil)
         send_command :shuffle, range
       end
 

data/ruby-mpd.gemspec

@@ -3,7 +3,7 @@
 Gem::Specification.new do |s|
   s.platform      = Gem::Platform::RUBY
   s.name          = 'ruby-mpd'
-  s.version       = '0.1.4'
+  s.version       = '0.1.5'
   s.homepage      = 'https://github.com/archSeer/ruby-mpd'
   s.authors       = ["Blaž Hrastnik"]
   s.email         = ['speed.the.bboy@gmail.com']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mpd
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors: