hallon 0.8.0 → 0.9.0

data/lib/hallon/toplist.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 module Hallon
   # Toplists are what they sound like. They’re collections of
   # artists, albums or tracks popular in a certain area either
@@ -13,6 +14,15 @@ module Hallon
     # @overload initialize(type, country)
     # @overload initialize(type)
     #
+    # @example with a given username
+    #   toplist = Hallon::Toplist.new(:artists, "burgestrand")
+    #
+    # @example with a given country
+    #   toplist = Hallon::Toplist.new(:tracks, :se)
+    #
+    # @example everywhere
+    #   toplist = Hallon::Toplist.new(:albums)
+    #
     # @param [Symbol] type one of :artists, :albums or :tracks
     # @param [String, Symbol, nil] region username, 2-letter country code or nil
     def initialize(type, region = nil)
@@ -21,53 +31,61 @@ module Hallon
         user   = region
         region = :user
       when NilClass
-        region = :anywhere
+        region = :everywhere
       when Symbol
         region = to_country(region)
       end
 
       @callback = proc { trigger(:load) }
-      pointer = Spotify.toplistbrowse_create(session.pointer, type, region, user, @callback, nil)
-      @pointer = Spotify::Pointer.new(pointer, :toplistbrowse, false)
+      @pointer  = Spotify.toplistbrowse_create!(session.pointer, type, region, user, @callback, nil)
     end
 
-    # @return [Boolean] true if the toplist is loaded
+    # @return [Boolean] true if the toplist is loaded.
     def loaded?
-      Spotify.toplistbrowse_is_loaded(@pointer)
+      Spotify.toplistbrowse_is_loaded(pointer)
     end
 
-    # @return [Symbol] toplist error status
-    def error
-      Spotify.toplistbrowse_error(@pointer)
+    # @see Error.explain
+    # @return [Symbol] toplist error status.
+    def status
+      Spotify.toplistbrowse_error(pointer)
     end
 
-    # @return [Enumerator<Artist>]
+    # @return [Enumerator<Artist>] a list of artists.
     def artists
-      size = Spotify.toplistbrowse_num_artists(@pointer)
+      size = Spotify.toplistbrowse_num_artists(pointer)
       Enumerator.new(size) do |i|
-        artist = Spotify.toplistbrowse_artist(@pointer, i)
+        artist = Spotify.toplistbrowse_artist!(pointer, i)
         Artist.new(artist)
       end
     end
 
-    # @return [Enumerator<Album>]
+    # @return [Enumerator<Album>] a list of albums.
     def albums
-      size = Spotify.toplistbrowse_num_albums(@pointer)
+      size = Spotify.toplistbrowse_num_albums(pointer)
       Enumerator.new(size) do |i|
-        album = Spotify.toplistbrowse_album(@pointer, i)
-        Artist.new(album)
+        album = Spotify.toplistbrowse_album!(pointer, i)
+        Album.new(album)
       end
     end
 
-    # @return [Enumerator<Track>]
+    # @return [Enumerator<Track>] a list of tracks.
     def tracks
-      size = Spotify.toplistbrowse_num_tracks(@pointer)
+      size = Spotify.toplistbrowse_num_tracks(pointer)
       Enumerator.new(size) do |i|
-        track = Spotify.toplistbrowse_track(@pointer, i)
-        Artist.new(track)
+        track = Spotify.toplistbrowse_track!(pointer, i)
+        Track.new(track)
       end
     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).
+    def request_duration
+      duration = Spotify.toplistbrowse_backend_request_duration(pointer)
+      Rational(duration, 1000) if duration > 0
+    end
+
     private
       # Convert a given two-character region to a Spotify
       # compliant region (encoded in a 16bit integer).

data/lib/hallon/track.rb

@@ -13,12 +13,13 @@ module Hallon
     # Overriden to use default parameter.
     # @see #to_link
     alias_method :_to_link, :to_link
+
     # Create a Link to the current track and offset in seconds.
     #
     # @param [Float] offset offset into track in seconds
     # @return [Hallon::Link]
     def to_link(offset = offset)
-      _to_link (offset * 1000).to_i
+      _to_link((offset * 1000).to_i)
     end
 
     # Offset into track in seconds this track was created with.
@@ -31,7 +32,7 @@ module Hallon
     # @param [String, Link, FFI::Pointer] link
     def initialize(link)
       FFI::MemoryPointer.new(:int) do |ptr|
-        @pointer = Spotify::Pointer.new from_link(link, ptr), :track, true
+        @pointer = to_pointer(link, :track, ptr)
         @offset  = Rational(ptr.read_int, 1000)
       end
     end
@@ -44,14 +45,14 @@ module Hallon
     # @param [Integer] length
     # @return [Track]
     def self.local(title, artist, album = nil, length = nil)
-      track = Spotify.localtrack_create(artist, title, album || "", length || -1)
+      track = Spotify.localtrack_create!(artist, title, album || "", length || -1)
       new(track)
     end
 
     # @note This’ll be an empty string unless the track is loaded.
     # @return [String]
     def name
-      Spotify.track_name(@pointer)
+      Spotify.track_name(pointer)
     end
 
     # Duration of the track in seconds.
@@ -59,7 +60,7 @@ module Hallon
     # @note This’ll be `0` unless the track is loaded.
     # @return [Rational]
     def duration
-      Rational(Spotify.track_duration(@pointer), 1000)
+      Rational(Spotify.track_duration(pointer), 1000)
     end
 
     # Track popularity, between 0 and 1.
@@ -67,97 +68,119 @@ module Hallon
     # @note This’ll be `0` unless the track is loaded.
     # @return [Rational]
     def popularity
-      Rational(Spotify.track_popularity(@pointer), 100)
+      Rational(Spotify.track_popularity(pointer), 100)
     end
 
     # Disc number this track appears in.
     #
     # @note This function is a bit special. See libspotify docs for details.
     def disc
-      Spotify.track_disc(@pointer)
+      Spotify.track_disc(pointer)
     end
 
-    # Position of track on its’ disc.
-    #
     # @note This function is a bit special. See libspotify docs for details.
+    # @return [Integer] position of track on its’ disc.
     def index
-      Spotify.track_index(@pointer)
+      Spotify.track_index(pointer)
     end
 
-    # Retrieve track error status.
-    #
-    # @return [Symbol]
+    # @see Error.explain
+    # @return [Symbol] track error status.
     def status
-      Spotify.track_error(@pointer)
+      Spotify.track_error(pointer)
     end
 
-    # True if the track is loaded
-    #
-    # @return [Boolean]
+    # @return [Boolean] true if track is loaded.
     def loaded?
-      Spotify.track_is_loaded(@pointer)
+      Spotify.track_is_loaded(pointer)
     end
 
-    # Album this track belongs to.
+    # @note Track does not have to be loaded for this to return a useful value.
+    #
+    # @note Placeholder tracks are not really tracks, but merely containers
+    # for other objects to allow storing them in playlists such as the inbox.
     #
+    # @return [Boolean] true if the track is a placeholder.
+    # @see unwrap
+    def placeholder?
+      Spotify.track_is_placeholder(pointer)
+    end
+
+    # Unwraps a {#placeholder?} Track into its’ real object.
+    #
+    # @see placeholder?
+    # @return [Track, Artist, Album, Playlist]
+    def unwrap
+      return self unless placeholder?
+
+      case (link = to_link).type
+      when :playlist
+        Playlist.new(link)
+      when :album
+        Album.new(link)
+      when :artist
+        Artist.new(link)
+      end
+    end
+
+    # @return [Symbol] track offline status.
+    def offline_status
+      Spotify.track_offline_get_status(pointer)
+    end
+
     # @note This’ll be `nil` unless the track is loaded.
-    # @return [Hallon::Album]
+    # @return [Hallon::Album] album this track belongs to.
     def album
-      album = Spotify.track_album(@pointer)
+      album = Spotify.track_album!(pointer)
       Album.new(album) unless album.null?
     end
 
-    # Artist who performed this Track.
-    #
     # @note There may be more than one artist, see {#artists} for retrieving them all!
     # @see #artists
-    # @return [Hallon::Artist, nil]
+    # @return [Hallon::Artist, nil] artist who performed this track.
     def artist
       artists.first
     end
 
-    # All {Artist}s who performed this Track.
-    #
     # @note Track must be loaded, or you’ll get zero artists.
-    # @return [Hallon::Enumerator<Artist>]
+    # @return [Hallon::Enumerator<Artist>] all {Artist}s who performed this Track.
     def artists
-      size = Spotify.track_num_artists(@pointer)
+      size = Spotify.track_num_artists(pointer)
       Enumerator.new(size) do |i|
-        artist = Spotify.track_artist(@pointer, i)
-        Artist.new(artist) unless artist.null?
+        artist = Spotify.track_artist!(pointer, i)
+        Artist.new(artist)
       end
     end
 
-    # True if the Track is available.
-    #
     # @note This’ll always return false unless the track is loaded.
-    # @return [Boolean]
+    # @return [Boolean] true if {#availability} is available.
     def available?
-      Spotify.track_is_available(session.pointer, @pointer)
+      availability == :available
     end
 
-    # True if the Track is a local track.
+    # Track availability.
     #
+    # @return [Symbol] :unavailable, :available, :not_streamable, :banned_by_artist
+    def availability
+      Spotify.track_get_availability(session.pointer, pointer)
+    end
+
     # @note This’ll always return false unless the track is loaded.
-    # @return [Boolean]
+    # @return [Boolean] true if the track is a local track.
     def local?
-      Spotify.track_is_local(session.pointer, @pointer)
+      Spotify.track_is_local(session.pointer, pointer)
     end
 
-    # True if the Track is autolinked.
-    #
     # @note This’ll always return false unless the track is loaded.
-    # @return [Boolean]
+    # @return [Boolean] true if the track is autolinked.
     def autolinked?
-      Spotify.track_is_autolinked(session.pointer, @pointer)
+      Spotify.track_is_autolinked(session.pointer, pointer)
     end
 
-    # True if the track is starred.
-    #
     # @note This’ll always return false unless the track is loaded.
-    # @return [Boolean]
+    # @return [Boolean] true if the track is starred.
     def starred?
-      Spotify.track_is_starred(session.pointer, @pointer)
+      Spotify.track_is_starred(session.pointer, pointer)
     end
 
     # Set {#starred?} status of current track.

data/lib/hallon/user.rb

@@ -9,60 +9,96 @@ module Hallon
   class User < Base
     extend Linkable
 
-    # @macro [attach] from_link
-    #   Given a Link, get its’ underlying pointer.
+    # A Post is created upon sending tracks (with an optional message) to a user.
     #
-    #   @method to_link
-    #   @scope  instance
-    #   @param  [String, Hallon::Link, FFI::Pointer] link
-    #   @return [FFI::Pointer]
+    # @see http://developer.spotify.com/en/libspotify/docs/group__inbox.html
+    class Post < Base
+      include Observable
+
+      # @param [Spotify::Pointer<inbox>]
+      def initialize(username, message, tracks, &block)
+        @callback = proc { trigger(:load) }
+
+        FFI::MemoryPointer.new(:pointer, tracks.length) do |ary|
+          ary.write_array_of_pointer tracks.map(&:pointer)
+          @pointer = Spotify.inbox_post_tracks!(session.pointer, username, ary, tracks.length, message, @callback, nil)
+        end
+      end
+
+      # @see Error.explain
+      # @return [Symbol] error status of inbox post
+      def status
+        Spotify.inbox_error(pointer)
+      end
+    end
+
     from_link :profile do |link|
-      Spotify.link_as_user(link)
+      Spotify.link_as_user!(link)
     end
 
-    # @macro [attach] to_link
-    #   Create a Link to the current object.
-    #
-    #   @method to_link
-    #   @scope  instance
-    #   @return [Hallon::Link]
     to_link :from_user
 
     # Construct a new instance of User.
     #
-    # @param [String, Link, FFI::Pointer] link
+    # @example from a canonical username
+    #   Hallon::User.new("burgestrand")
+    #
+    # @example from a spotify URI
+    #   Hallon::User.new("spotify:user:burgestrand")
+    #
+    # @note You can also instantiate User with a canonical username
+    # @param [String, Link, Spotify::Pointer] link
     def initialize(link)
-      @pointer = Spotify::Pointer.new from_link(link), :user, true
+      @pointer = to_pointer(link, :user) do
+        if link.is_a?(String) and link !~ /\Aspotify:user:/
+          to_pointer("spotify:user:#{link}", :user)
+        end
+      end
     end
 
     # @return [Boolean] true if the user is loaded
     def loaded?
-      Spotify.user_is_loaded(@pointer)
+      Spotify.user_is_loaded(pointer)
     end
 
-    # Retrieve the name of the current user.
+    # Retrieve the canonical name of the User.
     #
-    # @note Unless the user is {User#loaded?} only the canonical name is accessible
-    # @param [Symbol] type one of :canonical, :display, :full
     # @return [String]
-    def name(type = :canonical)
-      case type
-      when :display
-        Spotify.user_display_name(@pointer)
-      when :full
-        Spotify.user_full_name(@pointer)
-      when :canonical
-        Spotify.user_canonical_name(@pointer)
-      else
-        raise ArgumentError, "expected type to be :display, :full or :canonical, but was #{type}"
-      end.to_s
+    def name
+      Spotify.user_canonical_name(pointer)
     end
 
-    # Retrieve the URL to the users’ profile picture.
+    # Retrieve the dispaly name of the User.
     #
+    # @note Unless {#loaded?} is true, this will return the same thing as {#name}.
     # @return [String]
-    def picture
-      Spotify.user_picture(@pointer).to_s
+    def display_name
+      Spotify.user_display_name(pointer)
+    end
+
+    # Retrieve the users’ starred playlist.
+    #
+    # @note Returns nil unless {User#loaded?}
+    # @return [Playlist, nil]
+    def starred
+      playlist = Spotify.session_starred_for_user_create!(session.pointer, name)
+      Playlist.new(playlist) unless playlist.null?
+    end
+
+    # Send tracks to this users’ inbox, with an optional message.
+    #
+    # @overload post(message, tracks)
+    #   @param [#to_s] message
+    #   @param [Array<Track>] tracks
+    #
+    # @overload post(tracks)
+    #   @param [Array<Track>] tracks
+    #
+    # @return [Post, nil]
+    def post(message = nil, tracks)
+      message &&= message.encode('UTF-8')
+      post = Post.new(name, message, tracks)
+      post unless post.pointer.null?
     end
   end
 end

data/lib/hallon/version.rb

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

data/spec/hallon/album_browse_spec.rb

@@ -1,20 +1,26 @@
 # coding: utf-8
 describe Hallon::AlbumBrowse do
-  subject do
-    mock_session do
-      album = Hallon::Album.new(mock_album)
-      Spotify.should_receive(:albumbrowse_create).and_return(mock_albumbrowse)
-      Hallon::AlbumBrowse.new(album)
-    end
-  end
+  let(:browse) { mock_session { Hallon::AlbumBrowse.new(mock_album) } }
+  subject { browse }
 
   it { should be_loaded }
-  its(:error)  { should eq :ok }
+  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 [mock_track, mock_track_two].map{ |p| Hallon::Track.new(p) } }
+  its('tracks.to_a') { should eq instantiate(Hallon::Track, mock_track, mock_track_two) }
   its(:review) { should eq "This album is AWESOME" }
+
+  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
+    end
+  end
 end