hallon 0.13.0 → 0.14.0

data/lib/hallon/loadable.rb

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+module Hallon
+  module Loadable
+    # @param [Numeric] timeout after this time, if the object is not loaded, an error is raised.
+    # @return [self]
+    # @raise [Hallon::TimeoutError] after `timeout` seconds if the object does not load.
+    def load(timeout = Hallon.load_timeout)
+      Timeout.timeout(timeout, Hallon::TimeoutError) do
+        until loaded?
+          session.process_events
+
+          if respond_to?(:status)
+            Error.maybe_raise(status, :ignore => :is_loading)
+          end
+
+          sleep(0.001)
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/hallon/observable.rb

@@ -138,7 +138,7 @@ module Hallon
     # @return whatever the block returns
     def subscribe_for_callbacks
       yield(self.class.callbacks).tap do
-        self.class.subscribe(self, pointer)
+        self.class.subscribe(self, pointer) unless pointer.null?
       end
     end
 

data/lib/hallon/observable/playlist.rb

@@ -27,7 +27,12 @@ module Hallon::Observable
     # @yieldparam [Integer] position
     # @yieldparam [Playlist] self
     def tracks_added_callback(pointer, tracks, num_tracks, position, userdata)
-      trigger(pointer, :tracks_added, callback_make_tracks(tracks, num_tracks), position)
+      tracks_ary = tracks.read_array_of_pointer(num_tracks).map do |track|
+        ptr = Spotify::Pointer.new(track, :track, true)
+        Hallon::Track.new(ptr)
+      end
+
+      trigger(pointer, :tracks_added, tracks_ary, position)
     end
 
     # @example listening to this event
@@ -38,8 +43,8 @@ module Hallon::Observable
     # @yield [tracks, self] tracks_removed
     # @yieldparam [Array<Track>] tracks
     # @yieldparam [Playlist] self
-    def tracks_removed_callback(pointer, tracks, num_tracks, userdata)
-      trigger(pointer, :tracks_removed, callback_make_tracks(tracks, num_tracks))
+    def tracks_removed_callback(pointer, track_indices, num_indices, userdata)
+      trigger(pointer, :tracks_removed, track_indices.read_array_of_int(num_indices))
     end
 
     # @example listening to this event
@@ -51,8 +56,8 @@ module Hallon::Observable
     # @yieldparam [Array<Track>] tracks
     # @yieldparam [Integer] new_position
     # @yieldparam [Playlist] self
-    def tracks_moved_callback(pointer, tracks, num_tracks, new_position, userdata)
-      trigger(pointer, :tracks_moved, callback_make_tracks(tracks, num_tracks), new_position)
+    def tracks_moved_callback(pointer, track_indices, num_indices, new_position, userdata)
+      trigger(pointer, :tracks_moved, track_indices.read_array_of_int(num_indices), new_position)
     end
 
     # @example listening to this event
@@ -179,16 +184,5 @@ module Hallon::Observable
     def subscribers_changed_callback(pointer, userdata)
       trigger(pointer, :subscribers_changed)
     end
-
-    protected
-      # @param [FFI::Pointer] tracks
-      # @param [Integer] num_tracks
-      # @param [Array<Track>]
-      def callback_make_tracks(tracks, num_tracks)
-        tracks.read_array_of_pointer(num_tracks).map do |track|
-          ptr = Spotify::Pointer.new(track, :track, true)
-          Hallon::Track.new(ptr)
-        end
-      end
   end
 end

data/lib/hallon/observable/playlist_container.rb

@@ -27,8 +27,7 @@ module Hallon::Observable
     # @yieldparam [Integer] position
     # @yieldparam [PlaylistContainer] self
     def playlist_added_callback(pointer, playlist, position, userdata)
-      playlist = Spotify::Pointer.new(playlist, :playlist, true)
-      trigger(pointer, :playlist_added, Hallon::Playlist.new(playlist), position)
+      trigger(pointer, :playlist_added, playlist_from(playlist), position)
     end
 
     # @example listening to this event
@@ -41,8 +40,7 @@ module Hallon::Observable
     # @yieldparam [Integer] position
     # @yieldparam [PlaylistContainer] self
     def playlist_removed_callback(pointer, playlist, position, userdata)
-      playlist = Spotify::Pointer.new(playlist, :playlist, true)
-      trigger(pointer, :playlist_removed, Hallon::Playlist.new(playlist), position)
+      trigger(pointer, :playlist_removed, playlist_from(playlist), position)
     end
 
     # @example listening to this event
@@ -56,8 +54,7 @@ module Hallon::Observable
     # @yieldparam [Integer] new_position
     # @yieldparam [PlaylistContainer] self
     def playlist_moved_callback(pointer, playlist, position, new_position, userdata)
-      playlist = Spotify::Pointer.new(playlist, :playlist, true)
-      trigger(pointer, :playlist_moved, Hallon::Playlist.new(playlist), position, new_position)
+      trigger(pointer, :playlist_moved, playlist_from(playlist), position, new_position)
     end
 
     # @example listening to this event
@@ -70,5 +67,14 @@ module Hallon::Observable
     def container_loaded_callback(pointer, userdata)
       trigger(pointer, :container_loaded)
     end
+
+    protected
+
+      # @param [Spotify::Pointer] playlist
+      # @return [Hallon::Playlist] a playlist for the given pointer.
+      def playlist_from(pointer)
+        pointer = Spotify::Pointer.new(pointer, :playlist, true)
+        Hallon::Playlist.new(pointer)
+      end
   end
 end

data/lib/hallon/player.rb

@@ -48,7 +48,7 @@ module Hallon
       # data to the driver or not (see #status=)
       @status_c = @queue.new_cond
       # set initial status (we assume stopped)
-      self.status = @status = :stopped
+      self.status = :stopped
 
       # this thread feeds the audio driver with data, but
       # if we are not playing it’ll wait until we are
@@ -125,9 +125,9 @@ module Hallon
     #
     # @param [Symbol] status one of :playing, :paused, :stopped
     # @raise [ArgumentError] if given an invalid status
-    def status=(status)
+    def status=(new_status)
       @queue.synchronize do
-        old_status, @status = @status, status
+        old_status, @status = status, new_status
 
         case status
         when :playing

data/lib/hallon/playlist.rb

@@ -94,6 +94,7 @@ module Hallon
     end
 
     extend Linkable
+    include Loadable
 
     # CAN HAZ CALLBAKZ
     extend Observable::Playlist
@@ -104,6 +105,24 @@ module Hallon
 
     to_link :from_playlist
 
+    # Given a string, returns `false` if the string is a valid spotify playlist name.
+    # If it’s an invalid spotify playlist name, a string describing the fault is returned.
+    #
+    # @see http://developer.spotify.com/en/libspotify/docs/group__playlist.html#ga840b82b1074a7ca1c9eacd351bed24c2
+    # @param [String] name
+    # @return [String, false] description of why the name is invalid, or false if it’s valid
+    def self.invalid_name?(name)
+      unless name.bytesize < 256
+        return "name must be shorter than 256 bytes"
+      end
+
+      unless name =~ /[^[:space:]]/
+        return "name must not be blank"
+      end
+
+      return false # no error
+    end
+
     # Construct a new Playlist, given a pointer.
     #
     # @param [String, Link, FFI::Pointer] link
@@ -185,17 +204,11 @@ module Hallon
     # @param [#to_s] name new name for playlist
     # @raise [Error] if name could not be changed
     def name=(name)
-      name = name.to_s.encode('UTF-8')
-
-      unless name.bytesize < 256
-        raise ArgumentError, "name must be shorter than 256 bytes"
+      unless error = Playlist.invalid_name?(name)
+        Error.maybe_raise(Spotify.playlist_rename(pointer, name))
+      else
+        raise ArgumentError, error
       end
-
-      unless name =~ /[^ ]/u
-        raise ArgumentError, "name must not consist of only spaces"
-      end unless name.empty?
-
-      Error.maybe_raise(Spotify.playlist_rename(pointer, name))
     end
 
     # @return [User, nil]
@@ -209,7 +222,9 @@ module Hallon
       Spotify.playlist_get_description(pointer)
     end
 
-    # @return [Image, nil]
+    # @note this is not the mosaic image you see in the client. Spotify allows custom images
+    #       on playlists for promo campaigns etc.
+    # @return [Image, nil] custom image for the playlist, if one exists
     def image
       buffer = FFI::Buffer.alloc_out(20)
       if Spotify.playlist_get_image(pointer, buffer)
@@ -297,6 +312,14 @@ module Hallon
     # @return [Playlist]
     # @raise [Error] if the operation failed
     def remove(*indices)
+      unless indices == indices.uniq
+        raise ArgumentError, "no index may occur twice"
+      end
+
+      unless indices.all? { |i| i.between?(0, size-1) }
+        raise ArgumentError, "indices must be inside #{0...size}"
+      end
+
       indices_ary = FFI::MemoryPointer.new(:int, indices.size)
       indices_ary.write_array_of_int(indices)
 

data/lib/hallon/playlist_container.rb

@@ -58,7 +58,7 @@ module Hallon
 
     # Folders are parts of playlist containers in that they surround playlists
     # with a beginning marker and an ending marker. The playlists between these
-    # markers are considered "inside the playlist".
+    # markers are considered "inside the folder".
     class Folder
       # @return [Integer] index this folder starts at in the container.
       attr_reader :begin
@@ -88,7 +88,7 @@ module Hallon
       # @param [#to_s] new_name
       # @return [Folder] the new folder
       def rename(new_name)
-        raise IndexError, "playlist has moved from #{@begin}..#{@end}" if moved?
+        raise IndexError, "folder has moved from #{@begin}..#{@end}" if moved?
 
         insert_at = @begin
         container.remove(@begin)
@@ -134,6 +134,7 @@ module Hallon
     end
 
     extend Observable::PlaylistContainer
+    include Loadable
 
     # Wrap an existing PlaylistContainer pointer in an object.
     #
@@ -194,7 +195,11 @@ module Hallon
     # @return [Playlist, nil] the added playlist, or nil if the operation failed
     def add(name, force_create = false)
       playlist = if force_create or not Link.valid?(name) and name.is_a?(String)
-        Spotify.playlistcontainer_add_new_playlist!(pointer, name.to_s)
+        unless error = Playlist.invalid_name?(name)
+          Spotify.playlistcontainer_add_new_playlist!(pointer, name)
+        else
+          raise ArgumentError, error
+        end
       else
         link = Link.new(name)
         Spotify.playlistcontainer_add_playlist!(pointer, link.pointer)
@@ -278,7 +283,8 @@ module Hallon
     # @param (see #move)
     # @return [Boolean] true if the operation can be performed
     def can_move?(from, to)
-      error = move_playlist(from, to, true)
+      dry_run = true
+      error   = move_playlist(from, to, dry_run)
       _, symbol = Error.disambiguate(error)
       symbol == :ok
     end

data/lib/hallon/search.rb

@@ -51,6 +51,7 @@ module Hallon
     end
 
     extend Observable::Search
+    include Loadable
 
     # @return [Array<Symbol>] a list of radio genres available for search
     def self.genres

data/lib/hallon/session.rb

@@ -92,8 +92,8 @@ module Hallon
     def initialize(appkey, options = {}, &block)
       @options = {
         :user_agent => "Hallon",
-        :settings_path => "tmp",
-        :cache_path => "",
+        :settings_path => "tmp/hallon/",
+        :cache_path => "tmp/hallon/",
         :load_playlists => true,
         :compress_playlists => true,
         :cache_playlist_metadata => true,

data/lib/hallon/toplist.rb

@@ -37,6 +37,10 @@ module Hallon
     end
 
     extend Observable::Toplist
+    include Loadable
+
+    # @return [Symbol] type of toplist request (one of :artists, :albums or :tracks)
+    attr_reader :type
 
     # Create a Toplist browsing object.
     #
@@ -67,6 +71,7 @@ module Hallon
       end
 
       subscribe_for_callbacks do |callback|
+        @type    = type
         @pointer = Spotify.toplistbrowse_create!(session.pointer, type, region, user, callback, nil)
       end
     end
@@ -82,19 +87,19 @@ module Hallon
       Spotify.toplistbrowse_error(pointer)
     end
 
-    # @return [Artists] a list of artists.
-    def artists
-      Artists.new(self)
-    end
-
-    # @return [Albums] a list of albums.
-    def albums
-      Albums.new(self)
-    end
+    # @note the returned enumerator corresponds to the #type of Toplist.
+    # @return [Artists, Albums, Tracks] an enumerator over the collection of results.
+    def results
+      klass = case type
+      when :artists
+        Artists
+      when :albums
+        Albums
+      when :tracks
+        Tracks
+      end
 
-    # @return [Tracks] a list of tracks.
-    def tracks
-      Tracks.new(self)
+      klass.new(self)
     end
 
     # @note If the object is not loaded, the result is undefined.

data/lib/hallon/track.rb

@@ -16,6 +16,7 @@ module Hallon
     end
 
     extend Linkable
+    include Loadable
 
     from_link :as_track_and_offset
     to_link   :from_track

data/lib/hallon/user.rb

@@ -7,24 +7,60 @@ module Hallon
   #
   # @see http://developer.spotify.com/en/libspotify/docs/group__user.html
   class User < Base
-    extend Linkable
-
     # A Post is created upon sending tracks (with an optional message) to a user.
     #
     # @see http://developer.spotify.com/en/libspotify/docs/group__inbox.html
     class Post < Base
       extend Observable::Post
+      include Loadable
+
+      # Use {.create} instead!
+      private_class_method :new
+
+      # @param (see #initialize)
+      # @return [Post, nil] post, or nil if posting failed.
+      def self.create(recipient_name, message, tracks)
+        post = new(recipient_name, message, tracks)
+        post unless post.pointer.null?
+      end
+
+      # @return [Array<Track>] an array of tracks posted.
+      attr_reader :tracks
+
+      # @param [String, nil] message together with the post.
+      attr_reader :message
 
-      # @param [Spotify::Pointer<inbox>]
-      def initialize(username, message, tracks, &block)
+      # @param [String] the username of the post’s recipient.
+      attr_reader :recipient_name
+
+      # Send a list of tracks to another users’ inbox.
+      #
+      # @param [String] recipient_name username of person to send post to
+      # @param [String, nil] message
+      # @param [Track, Array<Track>] tracks
+      def initialize(recipient_name, message, tracks)
+        tracks = Array(tracks)
         ary = FFI::MemoryPointer.new(:pointer, tracks.length)
         ary.write_array_of_pointer tracks.map(&:pointer)
 
         subscribe_for_callbacks do |callback|
-          @pointer = Spotify.inbox_post_tracks!(session.pointer, username, ary, tracks.length, message, callback, nil)
+          @tracks  = tracks
+          @message = message
+          @recipient_name = recipient_name
+          @pointer = Spotify.inbox_post_tracks!(session.pointer, @recipient_name, ary, tracks.length, @message, callback, nil)
         end
       end
 
+      # @return [User] the user named {#recipient_name}.
+      def recipient
+        User.new(recipient_name)
+      end
+
+      # @return [Boolean] true if the post has been successfully sent.
+      def loaded?
+        status == :ok
+      end
+
       # @see Error.explain
       # @return [Symbol] error status of inbox post
       def status
@@ -32,6 +68,9 @@ module Hallon
       end
     end
 
+    extend Linkable
+    include Loadable
+
     from_link :profile do |link|
       Spotify.link_as_user!(link)
     end
@@ -90,16 +129,14 @@ module Hallon
     #
     # @overload post(message, tracks)
     #   @param [#to_s] message
-    #   @param [Array<Track>] tracks
+    #   @param [Track, Array<Track>] tracks
     #
     # @overload post(tracks)
-    #   @param [Array<Track>] tracks
+    #   @param [Track, Array<Track>] tracks
     #
-    # @return [Post, nil]
+    # @return (see Post.create)
     def post(message = nil, tracks)
-      message &&= message.encode('UTF-8')
-      post = Post.new(name, message, tracks)
-      post unless post.pointer.null?
+      Post.create(name, message, tracks)
     end
   end
 end