hallon 0.8.0 → 0.9.0

data/lib/hallon/album.rb

@@ -1,85 +1,99 @@
+# coding: utf-8
 module Hallon
   # Albums are non-detailed metadata about actual music albums.
   #
   # To retrieve copyrights, album review and tracks you need to browse
-  # the album, which is not currently supported by Hallon. You can retrieve
-  # the {#pointer} use the raw Spotify API on it, however.
+  # the album. You do this by calling {Album#browse} to retrieve an
+  # {AlbumBrowse} instance.
   #
-  # @note All metadata methods require the album to be {Album#loaded?}
+  # It does still allow you to query some metadata information, such as
+  # its’ {#name}, {#release_year}, {#type}, {#artist}, {#cover}…
+  #
+  # @note Pretty much all methods require the album to be {Album#loaded?}
+  #       to return meaningful results.
   #
   # @see http://developer.spotify.com/en/libspotify/docs/group__album.html
   class Album < Base
-    # An array of different kinds of albums. Singles, compilations etc.
+    # @example
+    #
+    #   Hallon::Album.types # => [:album, :single, :compilation, :unknown]
+    #
+    # @return [Array<Symbol>] an array of different kinds of albums (compilations, singles, …)
     def self.types
       Spotify.enum_type(:albumtype).symbols
     end
 
     extend Linkable
 
-    from_link :as_album
     to_link   :from_album
 
+    from_link :as_album
+
     # Construct an Album from a link.
     #
-    # @param [String, Link, FFI::Pointer] link
+    # @example from a spotify URI
+    #
+    #   album = Hallon::Album.new("spotify:album:6TECAywzyJGh0kwxfeBgGc")
+    #
+    # @example from a link
+    #
+    #   link = Hallon::Link.new("spotify:album:6TECAywzyJGh0kwxfeBgGc")
+    #   album = Hallon::Album.new(link)
+    #
+    # @param [String, Link, Spotify::Pointer] link
     def initialize(link)
-      @pointer = Spotify::Pointer.new from_link(link), :album, true
+      @pointer = to_pointer(link, :album)
     end
 
-    # Name of album.
-    #
-    # @return [String]
+    # @return [String] name of the album.
     def name
-      Spotify.album_name(@pointer)
+      Spotify.album_name(pointer)
     end
 
-    # Release year of album.
-    #
-    # @return [Integer]
-    def year
-      Spotify.album_year(@pointer)
+    # @return [Integer] release year of the album.
+    def release_year
+      Spotify.album_year(pointer)
     end
 
-    # Retrieve album type.
-    #
-    # @return [Symbol] one of {Album.types}
+    # @see Album.types
+    # @return [Symbol] album type.
     def type
-      Spotify.album_type(@pointer)
+      Spotify.album_type(pointer)
     end
 
-    # True if the album is available from the current session.
-    #
-    # @return [Boolean]
+    # @return [Boolean] true if the album is available.
     def available?
-      Spotify.album_is_available(@pointer)
+      Spotify.album_is_available(pointer)
     end
 
-    # True if album has been loaded.
-    #
-    # @return [Boolean]
+    # @return [Boolean] true if the album is loaded.
     def loaded?
-      Spotify.album_is_loaded(@pointer)
+      Spotify.album_is_loaded(pointer)
     end
 
-    # Retrieve album cover art.
-    #
-    # @return [Image]
-    def cover
-      image_id = Spotify.album_cover(@pointer)
-      Image.new(image_id.read_string(20)) unless image_id.null?
+    # @return [Artist, nil] album artist.
+    def artist
+      artist = Spotify.album_artist!(pointer)
+      Artist.new(artist) unless artist.null?
     end
 
-    # Retrieve the album Artist.
+    # Retrieves album cover art as an {Image} or a {Link}.
     #
-    # @return [Artist, nil]
-    def artist
-      artist = Spotify.album_artist(@pointer)
-      Artist.new(artist) unless artist.null?
+    # @param [Boolean] as_image true if you want it as an {Image}.
+    # @return [Image, Link, nil] album cover, the link to it, or nil.
+    def cover(as_image = true)
+      if as_image
+        image_id = Spotify.album_cover(pointer)
+        Image.new(image_id.read_string(20)) unless image_id.null?
+      else
+        link = Spotify.link_create_from_album_cover!(pointer)
+        Link.new(link)
+      end
     end
 
-    # Retrieve an AlbumBrowse object for this Album.
+    # Browse the Album by creating an {AlbumBrowse} instance from it.
     #
-    # @return [AlbumBrowse]
+    # @return [AlbumBrowse] an album browsing object
     def browse
       AlbumBrowse.new(pointer)
     end

data/lib/hallon/album_browse.rb

@@ -1,18 +1,9 @@
+# coding: utf-8
 module Hallon
   # AlbumBrowse objects are for retrieving additional data from
   # an album that cannot otherwise be acquired. This includes
   # tracks, reviews, copyright information.
   #
-  # AlbumBrowse object triggers the `:load` callback on itself
-  # when it loads.
-  #
-  # @example
-  #   browse = album.browse # album is a Hallon::Album
-  #   browse.on(:load) do
-  #     puts "Album browser for #{browse.album.name} has been loaded!"
-  #   end
-  #   session.wait_for { browse.loaded? } # will eventually trigger above callback
-  #
   # @see Album
   # @see http://developer.spotify.com/en/libspotify/docs/group__albumbrowse.html
   class AlbumBrowse < Base
@@ -20,58 +11,71 @@ module Hallon
 
     # Creates an AlbumBrowse instance from an Album or an Album pointer.
     #
-    # @note Use {Album#browse} to browse an Album.
-    # @param [Album, FFI::Pointer] album
+    # @note Also {Album#browse} to browse an Album.
+    # @param [Album, Spotify::Pointer] album
     def initialize(album)
-      album   = album.pointer if album.respond_to?(:pointer)
-      @callback = proc { trigger(:load) }
+      pointer = album
+      pointer = pointer.pointer if pointer.respond_to?(:pointer)
+
+      unless Spotify::Pointer.typechecks?(pointer, :album)
+        given = pointer.respond_to?(:type) ? pointer.type : pointer.inspect
+        raise TypeError, "expected album pointer, was given #{given}"
+      end
 
-      albumbrowse = Spotify.albumbrowse_create(session.pointer, album, @callback, nil)
-      @pointer    = Spotify::Pointer.new(albumbrowse, :albumbrowse, false)
+      @callback = proc { trigger(:load) }
+      @pointer  = Spotify.albumbrowse_create!(session.pointer, pointer, @callback, nil)
     end
 
-    # @return [Boolean] true if the album is loaded
+    # @return [Boolean] true if the album browser is loaded.
     def loaded?
-      Spotify.albumbrowse_is_loaded(@pointer)
+      Spotify.albumbrowse_is_loaded(pointer)
     end
 
-    # @see Error
-    # @return [Symbol] album browser error status
-    def error
-      Spotify.albumbrowse_error(@pointer)
+    # @see Error.explain
+    # @return [Symbol] album browser error status.
+    def status
+      Spotify.albumbrowse_error(pointer)
     end
 
-    # @return [String] album review
+    # @return [String] album review.
     def review
-      Spotify.albumbrowse_review(@pointer)
+      Spotify.albumbrowse_review(pointer)
     end
 
-    # @return [Artist] artist performing this album
+    # @return [Artist, nil] artist performing this album.
     def artist
-      pointer = Spotify.albumbrowse_artist(@pointer)
-      Artist.new(pointer) unless pointer.null?
+      artist = Spotify.albumbrowse_artist!(pointer)
+      Artist.new(artist) unless artist.null?
     end
 
-    # @return [Album] album this object is browsing
+    # @return [Album, nil] album this object is browsing.
     def album
-      pointer = Spotify.albumbrowse_album(@pointer)
-      Album.new(pointer) unless pointer.null?
+      album = Spotify.albumbrowse_album!(pointer)
+      Album.new(album) unless album.null?
+    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 albumbrowse request to complete (in seconds).
+    def request_duration
+      duration = Spotify.albumbrowse_backend_request_duration(pointer)
+      Rational(duration, 1000) if duration > 0
     end
 
-    # @return [Enumerator<String>] list of copyright notices
+    # @return [Enumerator<String>] list of copyright notices.
     def copyrights
-      size = Spotify.albumbrowse_num_copyrights(@pointer)
+      size = Spotify.albumbrowse_num_copyrights(pointer)
       Enumerator.new(size) do |i|
-        Spotify.albumbrowse_copyright(@pointer, i)
+        Spotify.albumbrowse_copyright(pointer, i)
       end
     end
 
-    # @return [Enumerator<Track>] list of tracks
+    # @return [Enumerator<Track>] list of tracks.
     def tracks
-      size = Spotify.albumbrowse_num_tracks(@pointer)
+      size = Spotify.albumbrowse_num_tracks(pointer)
       Enumerator.new(size) do |i|
-        pointer = Spotify.albumbrowse_track(@pointer, i)
-        Track.new(pointer) unless pointer.null?
+        track = Spotify.albumbrowse_track!(pointer, i)
+        Track.new(track) unless track.null?
       end
     end
   end

data/lib/hallon/artist.rb

@@ -1,12 +1,11 @@
+# coding: utf-8
 module Hallon
   # Artists in Hallon are the people behind the songs. Methods
   # are defined for retrieving their names and loaded status.
   #
-  # To retrieve more information about an artist, you can browse
+  # To retrieve more information about an artist, you can {#browse}
   # it. This will give access to more detailed data such as bio,
-  # portraits and more. Hallon does not support this as of yet,
-  # but you can use the underlying Spotify API for this, just like
-  # we have for {Album}s.
+  # portraits and more.
   #
   # Both Albums and Tracks can have more than one artist.
   #
@@ -17,43 +16,53 @@ module Hallon
     from_link :as_artist
     to_link   :from_artist
 
-    # Construct an artist given a link.
+    # Construct an Artist from a link.
+    #
+    # @example from a spotify URI
+    #
+    #   artist = Hallon::Artist.new("spotify:artist:6uSKeCyQEhvPC2NODgiqFE")
+    #
+    # @example from a link
+    #
+    #   link = Hallon::Link.new("spotify:artist:6uSKeCyQEhvPC2NODgiqFE")
+    #   artist = Hallon::Artist.new(link)
     #
     # @param [String, Link, FFI::Pointer] link
     def initialize(link)
-      @pointer = Spotify::Pointer.new from_link(link), :artist, true
+      @pointer = to_pointer(link, :artist)
     end
 
-    # Retrieve Artist name. Empty string if Artist is not loaded.
-    #
-    # @return [String]
+    # @return [String] name of the artist.
     def name
-      Spotify.artist_name(@pointer)
+      Spotify.artist_name(pointer)
     end
 
-    # True if the Artist is loaded.
-    #
-    # @return [Boolean]
+    # @return [Boolean] true if the artist is loaded.
     def loaded?
-      Spotify.artist_is_loaded(@pointer)
+      Spotify.artist_is_loaded(pointer)
     end
 
+    # Retrieve artist portrait as an {Image} or a {Link}.
+    #
     # @param [Boolean] as_image true if you want it as an Image
-    # @return [Image, Link, nil] artist portrait, or the link to it, or nil
+    # @return [Image, Link, nil] artist portrait, the link to it, or nil.
     def portrait(as_image = true)
-      portrait = Spotify.link_create_from_artist_portrait(@pointer)
-      unless portrait.null?
-        klass = as_image ? Image : Link
-        klass.new(portrait)
+      if as_image
+        portrait = Spotify.artist_portrait(pointer)
+        Image.new(portrait.read_bytes(20)) unless portrait.null?
+      else
+        portrait = Spotify.link_create_from_artist_portrait!(pointer)
+        Link.new(portrait) unless portrait.null?
       end
     end
 
     # Browse the Artist, giving you the ability to explore its’
     # portraits, biography and more.
     #
+    # @param [Symbol] type browsing type (see {ArtistBrowse.types})
     # @return [ArtistBrowse] an artist browsing object
-    def browse
-      ArtistBrowse.new(pointer)
+    def browse(type = :full)
+      ArtistBrowse.new(pointer, type)
     end
   end
 end

data/lib/hallon/artist_browse.rb

@@ -1,87 +1,105 @@
+# coding: utf-8
 module Hallon
   # ArtistBrowse is like AlbumBrowse, only that it’s for {Track}s.
   #
-  # When it loads, it triggers the load callback on itself, that
-  # can be utilized by giving {#on}(:load) a block to execute.
-  #
-  # @example
-  #   browse = artist.browse # artist is a Hallon::Artist
-  #   browse.on(:load) do
-  #     puts "#{browse.artist.name} browser has been loaded!"
-  #   end
-  #   session.wait_for { browse.loaded? }
-  #
   # @see Artist
   # @see http://developer.spotify.com/en/libspotify/docs/group__artistbrowse.html
   class ArtistBrowse < Base
     include Observable
 
+    # @return [Array<Symbol>] artist browsing types for use in {#initialize}
+    def self.types
+      Spotify.enum_type(:artistbrowse_type).symbols
+    end
+
     # Creates an ArtistBrowse instance from an Artist or an Artist pointer.
     #
-    # @note Use {Artist#browse} to browse an Artist.
-    # @param [Artist, FFI::Pointer] artist
-    def initialize(artist)
-      artist  = artist.pointer if artist.respond_to?(:pointer)
-      @callback = proc { trigger(:load) }
+    # @note Also use {Artist#browse} to browse an Artist.
+    # @param [Artist, Spotify::Pointer] artist
+    # @param [Symbol] type (see {.types})
+    def initialize(artist, type = :full)
+      pointer = artist
+      pointer = pointer.pointer if pointer.respond_to?(:pointer)
 
-      artistbrowse = Spotify.artistbrowse_create(session.pointer, artist, @callback, nil)
-      @pointer     = Spotify::Pointer.new(artistbrowse, :artistbrowse, false)
+      unless Spotify::Pointer.typechecks?(pointer, :artist)
+        given = pointer.respond_to?(:type) ? pointer.type : pointer.inspect
+        raise TypeError, "expected artist pointer, was given #{given}"
+      end
+
+      @callback = proc { trigger(:load) }
+      @pointer  = Spotify.artistbrowse_create!(session.pointer, pointer, type, @callback, nil)
     end
 
-    # @return [Boolean] true if the album browser is loaded
+    # @return [Boolean] true if the artist browser is loaded.
     def loaded?
-      Spotify.artistbrowse_is_loaded(@pointer)
+      Spotify.artistbrowse_is_loaded(pointer)
     end
 
-    # @see Error
-    # @return [Symbol] artist browser error status
-    def error
-      Spotify.artistbrowse_error(@pointer)
+    # @see Error.explain
+    # @return [Symbol] artist browser error status.
+    def status
+      Spotify.artistbrowse_error(pointer)
     end
 
-    # @return [Artist, nil] artist this browser is browsing
+    # @return [Artist, nil] artist this browser is browsing.
     def artist
-      artist = Spotify.artistbrowse_artist(@pointer)
+      artist = Spotify.artistbrowse_artist!(pointer)
       Artist.new(artist) unless artist.null?
     end
 
-    # @return [String] artist biography
+    # @return [String] artist biography.
     def biography
-      Spotify.artistbrowse_biography(@pointer)
+      Spotify.artistbrowse_biography(pointer)
     end
 
-    # @return [Enumerator<Image>] artist portraits
-    def portraits
-      size = Spotify.artistbrowse_num_portraits(@pointer)
+    # @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 albumbrowse request to complete (in seconds).
+    def request_duration
+      duration = Spotify.artistbrowse_backend_request_duration(pointer)
+      Rational(duration, 1000) if duration > 0
+    end
+
+    # Retrieve artist portraits as an {Image} or a {Link}.
+    #
+    # @param [Boolean] as_image true if you want an enumerator of Images (false for Links)
+    # @return [Enumerator<Image>, Enumerator<Link>] artist portraits.
+    def portraits(as_image = true)
+      size = Spotify.artistbrowse_num_portraits(pointer)
       Enumerator.new(size) do |i|
-        id = Spotify.artistbrowse_portrait(@pointer, i).read_string(20)
-        Image.new(id)
+        if as_image
+          id = Spotify.artistbrowse_portrait(pointer, i).read_string(20)
+          Image.new(id)
+        else
+          link = Spotify.link_create_from_artistbrowse_portrait!(pointer, i)
+          Link.new(link)
+        end
       end
     end
 
-    # @return [Enumerator<Track>] artist authored tracks
+    # @return [Enumerator<Track>] artist authored tracks.
     def tracks
-      size = Spotify.artistbrowse_num_tracks(@pointer)
+      size = Spotify.artistbrowse_num_tracks(pointer)
       Enumerator.new(size) do |i|
-        track = Spotify.artistbrowse_track(@pointer, i)
+        track = Spotify.artistbrowse_track!(pointer, i)
         Track.new(track)
       end
     end
 
-    # @return [Enumerator<Album>] artist authored albums
+    # @return [Enumerator<Album>] artist authored albums.
     def albums
-      size = Spotify.artistbrowse_num_albums(@pointer)
+      size = Spotify.artistbrowse_num_albums(pointer)
       Enumerator.new(size) do |i|
-        album = Spotify.artistbrowse_album(@pointer, i)
+        album = Spotify.artistbrowse_album!(pointer, i)
         Album.new(album)
       end
     end
 
-    # @return [Enumartor<Artist>] similar artists to this artist
+    # @return [Enumartor<Artist>] similar artists to this artist.
     def similar_artists
-      size = Spotify.artistbrowse_num_similar_artists(@pointer)
+      size = Spotify.artistbrowse_num_similar_artists(pointer)
       Enumerator.new(size) do |i|
-        artist = Spotify.artistbrowse_similar_artist(@pointer, i)
+        artist = Spotify.artistbrowse_similar_artist!(pointer, i)
         Artist.new(artist)
       end
     end