hallon 0.16.0 → 0.17.0

data/lib/hallon/search.rb

@@ -52,6 +52,7 @@ module Hallon
       end
     end
 
+    # Enumerates through all playlists of a search object.
     class PlaylistEnumerator < Enumerator
       size :search_num_playlists
 

data/lib/hallon/session.rb

@@ -2,6 +2,7 @@
 require 'singleton'
 require 'timeout'
 require 'thread'
+require 'uri'
 
 module Hallon
   # The Session is fundamental for all communication with Spotify.
@@ -82,6 +83,7 @@ module Hallon
     # @option options [String] :cache_path ("") where to save cache files (`""` to disable)
     # @option options [String] :tracefile (nil) path to libspotify API tracefile (`nil` to disable)
     # @option options [String] :device_id (nil) device ID for offline synchronization (`nil` to disable)
+    # @option options [String] :proxy (nil) proxy URI (supports http, https, socks4, socks5)
     # @option options [Bool]   :load_playlists (true) load playlists into RAM on startup
     # @option options [Bool]   :compress_playlists (true) compress local copies of playlists
     # @option options [Bool]   :cache_playlist_metadata (true) cache metadata for playlists locally
@@ -90,6 +92,14 @@ module Hallon
     # @raise [Hallon::Error] if `sp_session_create` fails
     # @see http://developer.spotify.com/en/libspotify/docs/structsp__session__config.html
     def initialize(appkey, options = {}, &block)
+      if options[:proxy]
+        proxy_uri = URI(options[:proxy])
+        options[:proxy_username] ||= proxy_uri.user
+        options[:proxy_password] ||= proxy_uri.password
+        proxy_uri.user = proxy_uri.password = nil
+        options[:proxy] = proxy_uri.to_s
+      end
+
       @options = {
         :user_agent => "Hallon",
         :settings_path => "tmp/hallon/",
@@ -98,6 +108,9 @@ module Hallon
         :compress_playlists => true,
         :cache_playlist_metadata => true,
         :device_id => nil,
+        :proxy     => nil,
+        :proxy_username => nil,
+        :proxy_password => nil,
         :tracefile => nil,
       }.merge(options)
 
@@ -164,7 +177,7 @@ module Hallon
     # @note it also supports logging in via a credentials blob, if you pass
     #       a Hallon::Blob(blob_string) as the password instead of the real password
     # @param [String] username
-    # @param [String] password_or_blob
+    # @param [String] password your password, or user credentials blob
     # @param [Boolean] remember_me have libspotify remember credentials for {#relogin}
     # @return [Session]
     # @see login!
@@ -179,10 +192,10 @@ module Hallon
 
     # Login the remembered user (see {#login}).
     #
-    # @raise [Hallon::Error] if no credentials are stored in libspotify
+    # @raise [Spotify::Error] if no credentials are stored in libspotify
     # @see #relogin!
     def relogin
-      Error.maybe_raise Spotify.session_relogin(pointer)
+      Spotify.session_relogin!(pointer)
     end
 
     # Log in to Spotify using the given credentials.
@@ -219,7 +232,13 @@ module Hallon
       tap { wait_for(:logged_out) { logged_out? } }
     end
 
-    # @return [String] username of the user stored in libspotify-remembered credentials.
+    # @return [String, nil] username of the currently logged in user.
+    def username
+      username = Spotify.session_user_name(pointer)
+      username unless username.nil? or username.empty?
+    end
+
+    # @return [String, nil] username of the user stored in libspotify-remembered credentials.
     def remembered_user
       bufflen = Spotify.session_remembered_user(pointer, nil, 0)
       FFI::Buffer.alloc_out(bufflen + 1) do |b|
@@ -254,15 +273,30 @@ module Hallon
       Spotify.session_connectionstate(pointer)
     end
 
-    # Set session cache size in megabytes.
+    # @return [Boolean] true if the session is currently set to private.
+    def private?
+      Spotify.session_is_private_session(pointer)
+    end
+    alias_method :britney_spears_mode?, :private?
+
+    # Set private session.
     #
-    # @param [Integer]
-    # @return [Integer]
+    # @note mode is reverted to normal after some time without user activity,
+    #       see official libspotify documentation for details.
+    # @param [Boolean] is_private
+    def private=(is_private)
+      Spotify.session_set_private_session(pointer, !! is_private)
+    end
+    alias_method :britney_spears_mode=, :private=
+
+    # Set session cache size.
+    #
+    # @param [Integer] size new session cache size, in megabytes.
     def cache_size=(size)
       Spotify.session_set_cache_size(pointer, @cache_size = size)
     end
 
-    # @return [String] currently logged in users’ country.
+    # @return [String] currently logged in user’s country.
     def country
       coded = Spotify.session_user_country(pointer)
       country = ((coded >> 8) & 0xFF).chr
@@ -275,7 +309,10 @@ module Hallon
     #   track = Hallon::Track.new("spotify:track:2LFQV2u6wXZmmySCWBkYGu")
     #   session.star(track)
     #
-    # @param [Track…]
+    # @note (see #unstar)
+    # @raise (see #unstar)
+    #
+    # @param [Track…] tracks
     # @return [Session]
     def star(*tracks)
       tap { tracks_starred(tracks, true) }
@@ -287,7 +324,13 @@ module Hallon
     #   track = Hallon::Track.new("spotify:track:2LFQV2u6wXZmmySCWBkYGu")
     #   session.unstar(track)
     #
-    # @param [Track…]
+    # @note this method might raise a Spotify::Error, however when this might
+    #       occur is not documented in libspotify (and I have yet to find any
+    #       way to trigger it myself). it’s entirely possible that this method
+    #       never returns an error, but we can’t know for sure.
+    #
+    # @raise [Spotify:Error] if libspotify reports an error (when this happens is unknown and undocumented)
+    # @param [Track…] tracks
     # @return [Session]
     def unstar(*tracks)
       tap { tracks_starred(tracks, false) }
@@ -295,6 +338,7 @@ module Hallon
 
     # Set the connection rules for this session.
     #
+    # @raise [ArgumentError] if given invalid connection rules
     # @param [Symbol, …] connection_rules
     # @see Session.connection_rules
     def connection_rules=(connection_rules)
@@ -307,6 +351,7 @@ module Hallon
 
     # Set the connection type for this session.
     #
+    # @raise [ArgumentError] if given invalid connection type
     # @param [Symbol] connection_type
     # @see Session.connection_types
     def connection_type=(connection_type)
@@ -345,15 +390,25 @@ module Hallon
 
     # Set preferred offline bitrate.
     #
-    # @example
+    # @example setting offline bitrate without resync
+    #   session.offline_bitrate = :'96k'
+    #
+    # @example setting offline bitrate and resync already-synced tracks
     #   session.offline_bitrate = :'96k', true
     #
+    # @note under normal circumstances, ArgumentError is the error that will
+    #       be raised on an invalid bitrate. However, if Hallon fails the type
+    #       checking (for whatever reason), libspotify will itself return an
+    #       error as well.
+    #
+    # @raise [ArgumentError] if given invalid bitrate
+    # @raise [Spotify::Error] if libspotify does not accept the given bitrate (see note)
     # @param [Symbol] bitrate
     # @param [Boolean] resync (default: false)
     # @see Player.bitrates
     def offline_bitrate=(bitrate)
       bitrate, resync = Array(bitrate)
-      Spotify.session_preferred_offline_bitrate(pointer, bitrate, !! resync)
+      Spotify.session_preferred_offline_bitrate!(pointer, bitrate, !! resync)
     end
 
     # @note Returns nil when no user is logged in.
@@ -397,12 +452,13 @@ module Hallon
     private
       # Set starred status of given tracks.
       #
+      # @raise [Spotify::Error] … maybe, it’s undocumented in libspotify, who knows?
       # @param [Array<Track>] tracks
       # @param [Boolean] starred
       def tracks_starred(tracks, starred)
         FFI::MemoryPointer.new(:pointer, tracks.size) do |ptr|
           ptr.write_array_of_pointer tracks.map(&:pointer)
-          Spotify.track_set_starred(pointer, ptr, tracks.size, starred)
+          Spotify.track_set_starred!(pointer, ptr, tracks.size, starred)
         end
       end
 

data/lib/hallon/toplist.rb

@@ -114,7 +114,7 @@ module Hallon
       # Convert a given two-character region to a Spotify
       # compliant region (encoded in a 16bit integer).
       #
-      # @param [#to_s]
+      # @param [#to_s] region
       # @return [Integer]
       def to_country(region)
         code = region.to_s.upcase

data/lib/hallon/track.rb

@@ -210,9 +210,9 @@ module Hallon
 
     # Set {#starred?} status of current track.
     #
-    # @note It’ll set the starred status for the current Session.instance.
+    # @note (see Session#star)
+    # @raise (see Session#star)
     # @param [Boolean] starred
-    # @return [Boolean]
     def starred=(starred)
       starred ? session.star(self) : session.unstar(self)
     end

data/lib/hallon/version.rb

@@ -3,5 +3,5 @@ module Hallon
   # Current release version of Hallon
   #
   # @see http://semver.org/
-  VERSION = [0, 16, 0].join('.')
+  VERSION = [0, 17, 0].join('.')
 end

data/spec/hallon/album_spec.rb

@@ -80,6 +80,14 @@ describe Hallon::Album do
     it "should be nil if there is no image" do
       empty_album.cover.should be_nil
     end
+
+    it "should support specifying size" do
+      album.cover(:large).should eq Hallon::Image.new(mock_image_id)
+    end
+
+    it "should raise an error when given an invalid size" do
+      expect { album.cover(:lawl) }.to raise_error(ArgumentError)
+    end
   end
 
   describe "#cover_link" do
@@ -90,5 +98,13 @@ describe Hallon::Album do
     it "should be nil if there is no image" do
       empty_album.cover_link.should be_nil
     end
+
+    it "should support specifying size" do
+      album.cover_link(:large).should eq Hallon::Link.new("spotify:image:3ad93423add99766e02d563605c6e76ed2b0e400")
+    end
+
+    it "should raise an error when given an invalid size" do
+      expect { album.cover_link(:lawl) }.to raise_error(ArgumentError)
+    end
   end
 end

data/spec/hallon/artist_spec.rb

@@ -54,6 +54,14 @@ describe Hallon::Artist do
     it "should be nil if an image is not available" do
       empty_artist.portrait.should be_nil
     end
+
+    it "should support specifying size" do
+      artist.portrait(:large).should eq Hallon::Image.new(mock_image_id)
+    end
+
+    it "should raise an error when given an invalid size" do
+      expect { artist.portrait(:lawl) }.to raise_error(ArgumentError)
+    end
   end
 
   describe "#portrait_link" do
@@ -64,5 +72,13 @@ describe Hallon::Artist do
     it "should be nil if an image is not available" do
       empty_artist.portrait_link.should be_nil
     end
+
+    it "should support specifying size" do
+      artist.portrait_link(:large).should eq Hallon::Link.new(mock_image_uri)
+    end
+
+    it "should raise an error when given an invalid size" do
+      expect { artist.portrait_link(:lawl) }.to raise_error(ArgumentError)
+    end
   end
 end

data/spec/hallon/base_spec.rb

@@ -8,7 +8,7 @@ describe Hallon::Base do
   end
 
   let(:base_pointer) do
-    Spotify.stub!(:base_add_ref, :base_release)
+    Spotify.stub(:base_add_ref! => nil, :base_release! => nil)
     Spotify::Pointer.new(a_pointer, :base, true)
   end
 

data/spec/hallon/error_spec.rb

@@ -1,7 +1,7 @@
 describe Hallon::Error do
   subject { described_class }
 
-  it { should <= RuntimeError }
+  it { should <= StandardError }
 
   describe ".disambiguate" do
     it "should not fail on invalid numbers" do
@@ -15,11 +15,11 @@ describe Hallon::Error do
 
   describe ".explain" do
     it "should work properly given an integer" do
-      subject.explain(0).should eq 'sp_error: 0'
+      subject.explain(0).should match 'sp_error: 0'
     end
 
     it "should work properly given a symbol" do
-      subject.explain(:bad_api_version).should eq 'sp_error: 1'
+      subject.explain(:bad_api_version).should match 'sp_error: 1'
     end
   end
 

data/spec/hallon/hallon_spec.rb

@@ -5,7 +5,7 @@ describe Hallon do
   end
 
   describe "API_VERSION" do
-    specify { Hallon::API_VERSION.should == 11 }
+    specify { Hallon::API_VERSION.should == 12 }
   end
 
   describe "API_BUILD" do

data/spec/hallon/image_spec.rb

@@ -18,6 +18,12 @@ describe Hallon::Image do
 
   specify { image.should be_a Hallon::Loadable }
 
+  describe ".sizes" do
+    it "should list all sizes" do
+      Hallon::Image.sizes.should eq [:normal, :small, :large]
+    end
+  end
+
   describe "#loaded?" do
     it "returns true when the image is loaded" do
       image.should be_loaded

data/spec/hallon/observable/session_spec.rb

@@ -144,4 +144,24 @@ describe Hallon::Observable::Session do
     let(:input)  { [a_pointer, :ok] }
     let(:output) { [:ok] }
   end
+
+  specification_for_callback "credentials_blob_updated" do
+    let(:input) { [a_pointer, "credentials"] }
+    let(:output) { ["credentials"] }
+  end
+
+  specification_for_callback "connectionstate_updated" do
+    let(:input) { [a_pointer] }
+    let(:output) { [] }
+  end
+
+  specification_for_callback "scrobble_error" do
+    let(:input) { [a_pointer, :ok] }
+    let(:output) { [:ok] }
+  end
+
+  specification_for_callback "private_session_mode_changed" do
+    let(:input) { [a_pointer, true] }
+    let(:output) { [true] }
+  end
 end

data/spec/hallon/scrobbler_spec.rb

@@ -0,0 +1,119 @@
+describe Hallon::Scrobbler do
+  let(:scrobbling) { Hallon::Scrobbler.new(:facebook) }
+
+  describe ".providers" do
+    it "returns a list of social providers" do
+      Hallon::Scrobbler.providers.should include :facebook
+    end
+  end
+
+  describe "#initialize" do
+    it "raises an error if given an invalid social provider" do
+      expect { Hallon::Scrobbler.new(:invalid_provider) }.to raise_error(ArgumentError, /social provider/)
+    end
+  end
+
+  describe "#provider" do
+    it "returns the social provider the scrobbler was instantiated with" do
+      scrobbling.provider.should eq :facebook
+    end
+  end
+
+  describe "#credentials=" do
+    it "sets the credentials for the scrobbler provider" do
+      Spotify.should_receive(:session_set_social_credentials).with(anything, :facebook, "Kim", "password").and_return(:ok)
+      scrobbling.credentials = "Kim", "password"
+    end
+  end
+
+  describe "#possible?" do
+    it "returns true if scrobbling is possible" do
+      Spotify.mocksp_session_set_is_scrobbling_possible(session.pointer, scrobbling.provider, true)
+      scrobbling.should be_possible
+    end
+
+    it "returns false if scrobbling is not possible" do
+      Spotify.mocksp_session_set_is_scrobbling_possible(session.pointer, scrobbling.provider, false)
+      scrobbling.should_not be_possible
+    end
+
+    it "raises an error if libspotify does not like us" do
+      Spotify.should_receive(:session_is_scrobbling_possible).and_return(:invalid_indata)
+      expect { scrobbling.possible? }.to raise_error(Spotify::Error)
+    end
+  end
+
+  describe "#enabled=" do
+    it "sets the local scrobbling" do
+      scrobbling.should_not be_enabled
+      scrobbling.enabled = true
+      scrobbling.should be_enabled
+      scrobbling.enabled = false
+      scrobbling.should_not be_enabled
+    end
+
+    it "raises an error if setting scrobbling state fails" do
+      Spotify.should_receive(:session_set_scrobbling).and_return(:invalid_indata)
+      expect { scrobbling.enabled = true }.to raise_error(Spotify::Error, /INVALID_INDATA/)
+    end
+  end
+
+  describe "#enabled?" do
+    before do
+      Spotify.should_receive(:session_is_scrobbling).and_return do |session, provider, buffer|
+        buffer.write_int(Spotify.enum_value(state_symbol))
+      end
+    end
+
+    context "if the state is locally enabled" do
+      let(:state_symbol) { :local_enabled }
+
+      it "returns true" do
+        scrobbling.should be_enabled
+      end
+    end
+
+    context "if the state is locally disabled" do
+      let(:state_symbol) { :local_disabled }
+
+      it "returns false" do
+        scrobbling.should_not be_enabled
+      end
+    end
+
+    context "if the state is globally enabled" do
+      let(:state_symbol) { :global_enabled }
+
+      it "returns true" do
+        scrobbling.should be_enabled
+      end
+    end
+
+    context "if the state is globally disabled" do
+      let(:state_symbol) { :global_disabled }
+
+      it "returns false" do
+        scrobbling.should_not be_enabled
+      end
+    end
+  end
+
+  describe "#reset" do
+    def state(scrobbler)
+      session = scrobbling.send(:session)
+      state   = nil
+      FFI::Buffer.alloc_out(:int) do |buffer|
+        Spotify.session_is_scrobbling!(session.pointer, scrobbling.provider, buffer)
+        state = buffer.read_int
+      end
+      Spotify.enum_type(:scrobbling_state)[state]
+    end
+
+    it "sets the local scrobbling state to use the global state" do
+      scrobbling.enabled = true
+      state(scrobbling).should eq :local_enabled
+      scrobbling.reset
+      state(scrobbling).should eq :global_enabled
+    end
+  end
+end