hallon 0.15.0 → 0.16.0

data/lib/hallon/playlist_container.rb

@@ -289,6 +289,44 @@ module Hallon
       symbol == :ok
     end
 
+    # Retrieve the number of unseen tracks for the given playlist.
+    #
+    # @param [Playlist] playlist
+    # @return [Integer] number of unseen tracks
+    def unseen_tracks_count_for(playlist)
+      Spotify.playlistcontainer_get_unseen_tracks(pointer, playlist.pointer, nil, 0).tap do |count|
+        raise OperationFailedError if count < 0
+      end
+    end
+
+    # Retrieve the unseen tracks for the given playlist.
+    #
+    # @note The playlist must be in this container, or this method will fail.
+    # @see clear_unseen_tracks_for
+    # @param [Playlist] playlist
+    # @return [Array<Track>] array of unseen tracks.
+    def unseen_tracks_for(playlist, count = unseen_tracks_count_for(playlist))
+      tracks_ary = FFI::MemoryPointer.new(:pointer, count)
+      real_count = Spotify.playlistcontainer_get_unseen_tracks(pointer, playlist.pointer, tracks_ary, count)
+      raise OperationFailedError if real_count < 0
+      tracks_ary.read_array_of_pointer([real_count, count].min).map do |track|
+        track_pointer = Spotify::Pointer.new(track, :track, true)
+        Hallon::Track.new(track_pointer)
+      end
+    end
+
+    # Clears the unseen tracks for the given playlist.
+    #
+    # @note in libspotify v11.1.60, this method appears to do nothing
+    # @param [Playlist] playlist
+    # @return [PlaylistContainer] self
+    def clear_unseen_tracks_for(playlist)
+      tap do
+        result = Spotify.playlistcontainer_clear_unseen_tracks(pointer, playlist.pointer)
+        raise OperationFailedError if result < 0
+      end
+    end
+
     protected
       # Wrapper for original API; adjusts indices accordingly.
       #

data/lib/hallon/search.rb

@@ -52,6 +52,49 @@ module Hallon
       end
     end
 
+    class PlaylistEnumerator < Enumerator
+      size :search_num_playlists
+
+      # @return [Integer] total playlists available from connected search result.
+      def total
+        Spotify.search_total_playlists(pointer)
+      end
+    end
+
+    # Enumerates through all playlist names of a search object.
+    class PlaylistNames < PlaylistEnumerator
+      # @return [String, nil]
+      item :search_playlist_name
+    end
+
+    # Enumerates through all playlist uris of a search object.
+    class PlaylistUris < PlaylistEnumerator
+      # @return [String, nil]
+      item :search_playlist_uri
+    end
+
+    # Enumerates through all playlist image uris of a search object.
+    class PlaylistImageUris < PlaylistEnumerator
+      # @return [String, nil]
+      item :search_playlist_image_uri
+    end
+
+    # Enumerates through all playlists of a search object.
+    class Playlists < PlaylistEnumerator
+      # @return [Playlist]
+      item :search_playlist_uri do |uri|
+        Playlist.from(uri)
+      end
+    end
+
+    # Enumerates through all playlist images of a search object.
+    class Images < PlaylistEnumerator
+      # @return [Playlist]
+      item :search_playlist_image_uri do |uri|
+        Image.from(uri)
+      end
+    end
+
     include Linkable
 
     to_link :from_search
@@ -74,7 +117,8 @@ module Hallon
         :tracks_offset  => 0,
         :albums_offset  => 0,
         :artists_offset => 0,
-        :playlists_offset => 0
+        :playlists_offset => 0,
+        :type => :standard
       }
     end
 
@@ -82,6 +126,7 @@ module Hallon
     #
     # @param [String, Link] search search query or spotify URI
     # @param [Hash] options additional search options
+    # @option options [Symbol] :type (:standard) search type, either standard or suggest
     # @option options [#to_i] :tracks (25) max number of tracks you want in result
     # @option options [#to_i] :albums (25) max number of albums you want in result
     # @option options [#to_i] :artists (25) max number of artists you want in result
@@ -93,6 +138,7 @@ module Hallon
     # @see http://developer.spotify.com/en/libspotify/docs/group__search.html#gacf0b5e902e27d46ef8b1f40e332766df
     def initialize(search, options = {})
       opts = Search.defaults.merge(options)
+      type = opts.delete(:type)
       opts = opts.values_at(:tracks_offset, :tracks, :albums_offset, :albums, :artists_offset, :artists, :playlists_offset, :playlists).map(&:to_i)
       search = from_link(search) if Link.valid?(search)
 
@@ -100,7 +146,7 @@ module Hallon
         @pointer = if Spotify::Pointer.typechecks?(search, :search)
           search
         else
-          Spotify.search_create!(session.pointer, search, *opts, :standard, callback, nil)
+          Spotify.search_create!(session.pointer, search, *opts, type, callback, nil)
         end
 
         raise ArgumentError, "search with #{search} failed" if @pointer.null?
@@ -120,12 +166,12 @@ module Hallon
 
     # @return [String] search query this search was created with.
     def query
-      Spotify.search_query(pointer)
+      Spotify.search_query(pointer).to_s
     end
 
     # @return [String] “did you mean?” suggestion for current search.
     def did_you_mean
-      Spotify.search_did_you_mean(pointer)
+      Spotify.search_did_you_mean(pointer).to_s
     end
 
     # @return [Tracks] list of all tracks in the search result.
@@ -142,5 +188,30 @@ module Hallon
     def artists
       Artists.new(self)
     end
+
+    # @return [PlaylistNames] list of all playlist names in the search result.
+    def playlist_names
+      PlaylistNames.new(self)
+    end
+
+    # @return [PlaylistUris] list of all playlist uris in the search result.
+    def playlist_uris
+      PlaylistUris.new(self)
+    end
+
+    # @return [PlaylistImageUris] list of all playlist image uris in the search result.
+    def playlist_image_uris
+      PlaylistImageUris.new(self)
+    end
+
+    # @return [Playlists] list of all playlists in the search result.
+    def playlists
+      Playlists.new(self)
+    end
+
+    # @return [Images] list of all images in the search result.
+    def playlist_images
+      Images.new(self)
+    end
   end
 end

data/lib/hallon/session.rb

@@ -55,7 +55,7 @@ module Hallon
     #
     # @return [Session]
     def Session.instance
-      @__instance__ or raise "Session has not been initialized"
+      @__instance__ or raise NoSessionError, "Session has not been initialized"
     end
 
     # @return [Boolean] true if a Session instance exists.
@@ -120,11 +120,20 @@ module Hallon
         # You pass a pointer to the session pointer to libspotify >:)
         FFI::MemoryPointer.new(:pointer) do |p|
           Error::maybe_raise Spotify.session_create(config, p)
-          @pointer = Spotify::Pointer.new(p.read_pointer, :session, false)
+          @pointer = p.read_pointer
         end
       end
     end
 
+    # Flushes the Session cache to disk.
+    #
+    # @note libspotify does this automatically periodically, under normal
+    #       circumstances this method should not need to be used.
+    # @return [Session]
+    def flush_caches
+      Spotify.session_flush_caches(pointer)
+    end
+
     # PlaylistContainer for the currently logged in session.
     #
     # @note returns nil if the session is not logged in.
@@ -144,43 +153,18 @@ module Hallon
       end
     end
 
-    # Wait for the given callbacks to fire until the block returns true
-    #
-    # @note Given block will be called once instantly without parameters.
-    # @note If no events happen for 0.25 seconds, the given block will be called
-    #       with `:timeout` as parameter.
-    # @param [Symbol, ...] *events list of events to wait for
-    # @yield [Symbol, *args] name of the callback that fired, and its’ arguments
-    # @return [Hash<Event, Arguments>]
-    def process_events_on(*events)
-      yield or protecting_handlers do
-        channel = SizedQueue.new(1)
-        block   = proc { |*args| channel << args }
-        events.each { |event| on(event, &block) }
-        on(:notify_main_thread) { channel << :notify }
-
-        loop do
-          begin
-            timeout = [process_events.fdiv(1000), 5].min # scope to five seconds
-            timeout = timeout + 0.010 # minimum of ten miliseconds timeout
-            params = Timeout::timeout(timeout) { channel.pop }
-            redo if params == :notify
-          rescue Timeout::Error
-            params = :timeout
-          end
-
-          if result = yield(*params)
-            return result
-          end
-        end
-      end
-    end
-    alias :wait_for :process_events_on
-
     # Log into Spotify using the given credentials.
     #
+    # @example logging in with password
+    #   session.login 'Kim', 'password'
+    #
+    # @example logging in with credentials blob
+    #   session.login 'Kim', Hallon::Blob('blob string')
+    #
+    # @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
+    # @param [String] password_or_blob
     # @param [Boolean] remember_me have libspotify remember credentials for {#relogin}
     # @return [Session]
     # @see login!
@@ -189,7 +173,8 @@ module Hallon
         raise ArgumentError, "username and password may not be blank"
       end
 
-      tap { Spotify.session_login(pointer, username, password, remember_me, nil) }
+      password, blob = blob, password if password.is_a?(Blob)
+      tap { Spotify.session_login(pointer, username, password, remember_me, blob) }
     end
 
     # Login the remembered user (see {#login}).
@@ -221,7 +206,8 @@ module Hallon
     # @raise [Error] if failed to log in
     # @see #relogin
     def relogin!
-      tap { relogin; wait_until_logged_in }
+      relogin
+      tap { wait_until_logged_in }
     end
 
     # Log out the current user.
@@ -229,7 +215,8 @@ module Hallon
     # @note This method will not return until you’ve logged out successfully.
     # @return [Session]
     def logout!
-      tap { logout; wait_for(:logged_out) { logged_out? } }
+      logout
+      tap { wait_for(:logged_out) { logged_out? } }
     end
 
     # @return [String] username of the user stored in libspotify-remembered credentials.
@@ -335,12 +322,14 @@ module Hallon
 
     # Offline synchronization status.
     #
-    # @return [Hash, nil] sync status, or nil if not applicable
+    # @return [Hash] sync status (empty hash if not applicable)
     # @see http://developer.spotify.com/en/libspotify/docs/structsp__offline__sync__status.html
     def offline_sync_status
       struct = Spotify::OfflineSyncStatus.new
       if Spotify.offline_sync_get_status(pointer, struct.pointer)
         Hash[struct.members.zip(struct.values)]
+      else
+        {}
       end
     end
 
@@ -424,8 +413,8 @@ module Hallon
       # @see login!
       # @see relogin!
       def wait_until_logged_in
-        wait_for(:connection_error) do |error|
-          Error.maybe_raise(error, :ignore => :timeout)
+        wait_for(:logged_in, :connection_error) do |event, error|
+          Error.maybe_raise(error)
           session.logged_in?
         end
       end

data/lib/hallon/toplist.rb

@@ -103,11 +103,11 @@ module Hallon
     end
 
     # @note If the object is not loaded, the result is undefined.
-    # @note Returns nil if the request was served from the local libspotify cache.
-    # @return [Rational, nil] time it took for the toplistbrowse request to complete (in seconds).
+    # @return [Rational] time it took for the toplistbrowse request to complete (in seconds).
     def request_duration
       duration = Spotify.toplistbrowse_backend_request_duration(pointer)
-      Rational(duration, 1000) if duration > 0
+      duration = 0 if duration < 0
+      Rational(duration, 1000)
     end
 
     private

data/lib/hallon/track.rb

@@ -50,6 +50,24 @@ module Hallon
 
     # Create a new local track.
     #
+    # Local tracks in Spotify allows you to specify title, artist, and
+    # optionally also album and length. This will create a local track
+    # (meaning {Track#local?} returns true) that libspotify will try to
+    # match up with an *actual* track in the Spotify database.
+    #
+    # If the track is successfully matched, once loaded, {Track#available?}
+    # will return true and you’ll be able to inspect the track’s {#artist}
+    # and {#album}, as well as the information in the track itself. If the
+    # track is playable you’ll also be able to play it!
+    #
+    # @example creating a local track
+    #   track = Hallon::Track.local "Californication", "Red Hot Chili Peppers"
+    #   puts track.artist.name # => "Red Hot Chili Peppers"
+    #   puts track.album.name # => "Californication"
+    #   p track.local? # => true
+    #
+    # @note I’ve been unable to get local tracks to get matched up in libspotify v11,
+    #       it’s possible this function does not work properly in libspotify v11.
     # @param [String] title
     # @param [String] artist
     # @param [String] album
@@ -60,7 +78,6 @@ module Hallon
       new(track)
     end
 
-    # @note This’ll be an empty string unless the track is loaded.
     # @return [String]
     def name
       Spotify.track_name(pointer)
@@ -68,23 +85,22 @@ module Hallon
 
     # Duration of the track in seconds.
     #
-    # @note This’ll be `0` unless the track is loaded.
     # @return [Rational]
     def duration
       Rational(Spotify.track_duration(pointer), 1000)
     end
 
-    # Track popularity, between 0 and 1.
+    # Track popularity, between 0 and 100.
     #
-    # @note This’ll be `0` unless the track is loaded.
     # @return [Rational]
     def popularity
-      Rational(Spotify.track_popularity(pointer), 100)
+      Spotify.track_popularity(pointer)
     end
 
     # Disc number this track appears in.
     #
     # @note This function is a bit special. See libspotify docs for details.
+    # @return [Integer] disc index from album this track appears in.
     def disc
       Spotify.track_disc(pointer)
     end
@@ -139,7 +155,6 @@ module Hallon
       Spotify.track_offline_get_status(pointer)
     end
 
-    # @note This’ll be `nil` unless the track is loaded.
     # @return [Hallon::Album] album this track belongs to.
     def album
       album = Spotify.track_album!(pointer)
@@ -153,13 +168,11 @@ module Hallon
       artists.first
     end
 
-    # @note Track must be loaded, or you’ll get zero artists.
     # @return [Artists] all {Artist}s who performed this Track.
     def artists
       Artists.new(self)
     end
 
-    # @note This’ll always return false unless the track is loaded.
     # @return [Boolean] true if {#availability} is available.
     def available?
       availability == :available
@@ -172,13 +185,18 @@ module Hallon
       Spotify.track_get_availability(session.pointer, pointer)
     end
 
-    # @note This’ll always return false unless the track is loaded.
+    # @see autolinked?
+    # @return [Track] the track this track is autolinked to for audio playback.
+    def playable_track
+      track = Spotify.track_get_playable!(session.pointer, pointer)
+      Track.from(track)
+    end
+
     # @return [Boolean] true if the track is a local track.
     def local?
       Spotify.track_is_local(session.pointer, pointer)
     end
 
-    # @note This’ll always return false unless the track is loaded.
     # @return [Boolean] true if the track is autolinked.
     def autolinked?
       Spotify.track_is_autolinked(session.pointer, pointer)

data/lib/hallon/version.rb

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

data/spec/hallon/album_browse_spec.rb

@@ -1,11 +1,21 @@
 # coding: utf-8
 describe Hallon::AlbumBrowse do
-  it { should be_a Hallon::Loadable }
+  let(:browse) do
+    album = Hallon::Album.new(mock_albums[:default])
+    Hallon::AlbumBrowse.new(album)
+  end
+
+  let(:empty_browse) do
+    album = Hallon::Album.new(mock_albums[:empty])
+    Hallon::AlbumBrowse.new(album)
+  end
+
+  specify { browse.should be_a Hallon::Loadable }
 
   describe ".new" do
     it "should raise an error if the browse request failed" do
       Spotify.should_receive(:albumbrowse_create).and_return(null_pointer)
-      expect { mock_session { Hallon::AlbumBrowse.new(mock_album) } }.to raise_error(FFI::NullPointerError)
+      expect { Hallon::AlbumBrowse.new(mock_album) }.to raise_error(FFI::NullPointerError)
     end
 
     it "should raise an error given a non-album spotify pointer" do
@@ -13,31 +23,71 @@ describe Hallon::AlbumBrowse do
     end
   end
 
-  let(:browse) do
-    album = Hallon::Album.new(mock_album)
-    mock_session { Hallon::AlbumBrowse.new(album) }
+  describe "#loaded?" do
+    it "is true when the album browser is loaded" do
+      browse.should be_loaded
+    end
+  end
+
+  describe "#status" do
+    it "returns the album status" do
+      browse.status.should eq :ok
+    end
+  end
+
+  describe "#album" do
+    it "returns the album" do
+      browse.album.should eq Hallon::Album.new(mock_albums[:default])
+    end
   end
 
-  subject { browse }
+  describe "#artist" do
+    it "returns the album’s artist" do
+      browse.artist.should eq Hallon::Artist.new(mock_artists[:default])
+    end
 
-  it { should be_loaded }
-  its(:status) { should eq :ok }
-  its(:album)  { should eq Hallon::Album.new(mock_album) }
-  its(:artist) { should eq Hallon::Artist.new(mock_artist) }
-  its('copyrights.size') { should eq 2 }
-  its('copyrights.to_a') { should eq %w[Kim Elin] }
-  its('tracks.size') { should eq 2 }
-  its('tracks.to_a') { should eq instantiate(Hallon::Track, mock_track, mock_track_two) }
-  its(:review) { should eq "This album is AWESOME" }
+    it "returns nil if the album browser is not loaded" do
+      empty_browse.artist.should be_nil
+    end
+  end
+
+  describe "#review" do
+    it "returns the album’s review" do
+      browse.review.should eq "This album is AWESOME"
+    end
+
+    it "returns an empty string if the album browser is not loaded" do
+      empty_browse.review.should be_empty
+    end
+  end
+
+  describe "#copyrights" do
+    it "returns an enumerator of the album’s copyright texts" do
+      browse.copyrights.to_a.should eq %w[Kim Elin]
+    end
+
+    it "returns an empty enumerator when the album browser is not loaded" do
+      empty_browse.copyrights.size.should eq 0
+    end
+  end
+
+  describe "#tracks" do
+    it "returns an enumerator of the album’s tracks" do
+      browse.tracks.to_a.should eq instantiate(Hallon::Track, mock_track, mock_track_two) 
+    end
+
+    it "returns an empty enumerator if the album browser is not loaded" do
+      empty_browse.tracks.size.should eq 0
+    end
+  end
 
   describe "#request_duration" do
     it "should return the request duration in seconds" do
       browse.request_duration.should eq 2.751
     end
 
-    it "should be nil if the request was fetched from local cache" do
-      Spotify.should_receive(:albumbrowse_backend_request_duration).and_return(-1)
-      browse.request_duration.should be_nil
+    it "should be zero if the request was fetched from local cache" do
+      empty_browse.request_duration.should eq 0
     end
   end
 end