ruby-mpd 0.3.1 → 0.3.2

data/README.rdoc

@@ -1,296 +0,0 @@
-= 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,
-originally using librmpd as a base, however almost all of the codebase was rewritten.
-ruby-mpd supports all "modern" MPD features as well as callbacks.
-
-== MPD Protocol
-
-The Music Player Daemon protocol is implemented inside the library. The implementation
-brings the entire set of features to ruby, with support of the newest protocol commands.
-However some commands were remapped, some were converted to objects, as I felt they fit
-this way much more into ruby and are more intuitive.
-
-== Installation
-
-  gem install ruby-mpd
-
-== Usage
-
-Require the library.
-
-  require 'ruby-mpd'
-
-Then, make a new MPD instance:
-
-  mpd = MPD.new 'localhost', 6600
-
-You can also omit the host and 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.
-
-  mpd.connect
-
-When you are done, disconnect by calling disconnect.
-
-  mpd.disconnect
-
-*Note*: In the past, one had to tackle the issue of the server possibly disconnecting
-the client at any time due to inactivity. Since 0.3.0, this is handled automatically
-via a reconnect mechanism.
-
-Once connected, you can issue commands to talk to the server.
-
-  mpd.connect
-    
-  mpd.play if mpd.stopped?
-
-  song = mpd.current_song
-  puts "Current Song: #{song.artist} - #{song.title}"
-
-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.
-
-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). 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
-
-  mpd.queue(5..-1).count # => 15 (from 5 to the end of the range)
-  mpd.queue(5...-1).count # => 15 (does the same)
-
-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+,
-+MPD::Playlist#load+.
-
-== Searching
-
-The MPD protocol supports two commands +find+ and +search+, where +find+ is strict
-and will be case sensitive, as well as return only full matches, while +search+ is
-"loose" -- case insensitive and allow partial matches.
-
-For ease of use, ruby-mpd encapsulates both +find+ and +search+ in one method,
-+MPD#where+.
-
-Searching is case *loose* by default, meaning it is case insensitive, and will do
-partial matching. To enable *strict* matching, enable the +strict+ option.
-
-This does not work for Playlist#searchadd.
-
-  mpd.where({artist: 'MyArtiSt'}, {strict: true})
-
-Multiple query parameters can also be used:
-
-  mpd.where(artist: 'Bonobo', album: 'Black Sands')
-
-Query keys can be any of of the tags supported by MPD (a list can be fetched via
-MPD#tags), 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.
-
-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.where({artist: 'MyArtiSt'}, {strict: true, add: true})
-
-=== Queue searching
-
-Queue searching works the same way (except by using +MPD#queue_where+), and it also
-accepts multiple search parameters (which seems to be undocumented in the MPD protocol
-specification).
-
-Same as +#where+, it is "loose" by default, and it supports a +:strict+ option.
-
-  mpd.queue_where(artist: 'James Brown', genre: 'Funk')
-
-  mpd.queue_where({artist: 'James Brown', genre: 'Funk'}, {strict: true})
-
-== Playlists
-
-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 # => [MPD::Playlist, MPD::Playlist...]
-
-  playlist = mpd.playlists.first
-
-  p playlist.name # => "My playlist"
-
-  playlist.songs # => [MPD::Song, MPD::Song...]
-
-  playlist.rename('Awesomelist')
-  p playlist.name # => "Awesomelist"
-
-  playlist.add('awesome_track.mp3')
-
-To create a new playlist, simply create a new object. The playlist will be created
-in the daemon's library automatically as soon as you use +#add+ or +#searchadd+. There
-is also no save method, as playlists get 'saved' by the daemon any time you do an
-action on them (add, delete, rename).
-
-  MPD::Playlist.new(mpd, 'name')
-
-Currently, one also has to pass in the MPD instance, as playlists are tied to a
-certain connection.
-
-== Callbacks
-
-Callbacks are a simple way to make your client respond to events, rather that
-have to continuously ask the server for updates. This allows you to focus on
-displaying the data, rather that working overly hard to get it. This is done
-by having a background thread continuously check the server for changes.
-
-To make use of callbacks, we need to:
-
-1. Setup a callback to be called when something happens.
-2. Create a MPD client instance 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
-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}!"
-  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}!" }
-  mpd.on :volume, &proc
-
-  # Method
-  def volume_change(value)
-    puts "Volume changed to #{value}!"
-  end
-
-  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+.
-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:
-
-  mpd.on :audio do |sampleRate, bits, channels|
-    puts bits
-  end
-
-  # or
-  mpd.on :audio do |*args|
-    puts args.join(',')
-  end
-
-Finally, the easiest step. In order for callbacks to work, create a MPD instance
-with callbacks enabled:
-
-  MPD.new('localhost', 6600, {callbacks: 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.
-
-== 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
-
-* Merge +where+ and +queue_where+, by doing +where(..., {in_queue: true})+?

data/test/test_parser.rb

@@ -1,52 +0,0 @@
-require_relative '../lib/ruby-mpd'
-require 'minitest/autorun'
-
-Parser = Class.new do
-  include MPD::Parser
-end
-Parser.send(:public, *MPD::Parser.private_instance_methods)
-
-class TestParser < MiniTest::Test
-
-  def setup
-    @parser = Parser.new
-  end
-
-  def teardown
-
-  end
-
-  # Conversions for commands to the server
-  def test_convert_bool
-    assert_equal @parser.convert_command(:pause, true), 'pause 1'
-    assert_equal @parser.convert_command(:pause, false), 'pause 0'
-  end
-
-  def test_convert_range
-    # inclusive range
-    assert_equal @parser.convert_command(:playlistinfo, 1..10), 'playlistinfo 1:11'
-    # exclusive range
-    assert_equal @parser.convert_command(:playlistinfo, 2...5), 'playlistinfo 2:5'
-
-    # negative means "till end of range"
-    assert_equal @parser.convert_command(:playlistinfo, 2...-1), 'playlistinfo 2:'
-  end
-
-  def test_convert_escape_whitespace
-    assert_equal @parser.convert_command(:lsinfo, '/media/Storage/epic music'), 'lsinfo "/media/Storage/epic music"'
-  end
-
-  # Parse replies from server
-  def test_parse_empty_listall_command
-    assert_equal @parser.parse_response(:listall, ''), {}
-  end
-
-  def test_parse_playlist_uint
-    assert_equal @parser.parse_key(:playlist, '31'), 31
-  end
-
-  def test_parse_playlist_name
-    assert_equal @parser.parse_key(:playlist, 'leftover/classics.m3u'), 'leftover/classics.m3u'
-  end
-
-end