hallon 0.4.0 → 0.8.0

data/lib/hallon/artist.rb

@@ -0,0 +1,59 @@
+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
+  # 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.
+  #
+  # Both Albums and Tracks can have more than one artist.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__artist.html
+  class Artist < Base
+    extend Linkable
+
+    from_link :as_artist
+    to_link   :from_artist
+
+    # Construct an artist given a link.
+    #
+    # @param [String, Link, FFI::Pointer] link
+    def initialize(link)
+      @pointer = Spotify::Pointer.new from_link(link), :artist, true
+    end
+
+    # Retrieve Artist name. Empty string if Artist is not loaded.
+    #
+    # @return [String]
+    def name
+      Spotify.artist_name(@pointer)
+    end
+
+    # True if the Artist is loaded.
+    #
+    # @return [Boolean]
+    def loaded?
+      Spotify.artist_is_loaded(@pointer)
+    end
+
+    # @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
+    def portrait(as_image = true)
+      portrait = Spotify.link_create_from_artist_portrait(@pointer)
+      unless portrait.null?
+        klass = as_image ? Image : Link
+        klass.new(portrait)
+      end
+    end
+
+    # Browse the Artist, giving you the ability to explore its’
+    # portraits, biography and more.
+    #
+    # @return [ArtistBrowse] an artist browsing object
+    def browse
+      ArtistBrowse.new(pointer)
+    end
+  end
+end

data/lib/hallon/artist_browse.rb

@@ -0,0 +1,89 @@
+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
+
+    # 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) }
+
+      artistbrowse = Spotify.artistbrowse_create(session.pointer, artist, @callback, nil)
+      @pointer     = Spotify::Pointer.new(artistbrowse, :artistbrowse, false)
+    end
+
+    # @return [Boolean] true if the album browser is loaded
+    def loaded?
+      Spotify.artistbrowse_is_loaded(@pointer)
+    end
+
+    # @see Error
+    # @return [Symbol] artist browser error status
+    def error
+      Spotify.artistbrowse_error(@pointer)
+    end
+
+    # @return [Artist, nil] artist this browser is browsing
+    def artist
+      artist = Spotify.artistbrowse_artist(@pointer)
+      Artist.new(artist) unless artist.null?
+    end
+
+    # @return [String] artist biography
+    def biography
+      Spotify.artistbrowse_biography(@pointer)
+    end
+
+    # @return [Enumerator<Image>] artist portraits
+    def portraits
+      size = Spotify.artistbrowse_num_portraits(@pointer)
+      Enumerator.new(size) do |i|
+        id = Spotify.artistbrowse_portrait(@pointer, i).read_string(20)
+        Image.new(id)
+      end
+    end
+
+    # @return [Enumerator<Track>] artist authored tracks
+    def tracks
+      size = Spotify.artistbrowse_num_tracks(@pointer)
+      Enumerator.new(size) do |i|
+        track = Spotify.artistbrowse_track(@pointer, i)
+        Track.new(track)
+      end
+    end
+
+    # @return [Enumerator<Album>] artist authored albums
+    def albums
+      size = Spotify.artistbrowse_num_albums(@pointer)
+      Enumerator.new(size) do |i|
+        album = Spotify.artistbrowse_album(@pointer, i)
+        Album.new(album)
+      end
+    end
+
+    # @return [Enumartor<Artist>] similar artists to this artist
+    def similar_artists
+      size = Spotify.artistbrowse_num_similar_artists(@pointer)
+      Enumerator.new(size) do |i|
+        artist = Spotify.artistbrowse_similar_artist(@pointer, i)
+        Artist.new(artist)
+      end
+    end
+  end
+end

data/lib/hallon/base.rb

@@ -16,5 +16,12 @@ module Hallon
     rescue NoMethodError
       super
     end
+
+    # The current Session instance.
+    #
+    # @return [Session]
+    def session
+      Session.instance
+    end
   end
 end

data/lib/hallon/enumerator.rb

@@ -0,0 +1,64 @@
+module Hallon
+  # Hallon::Enumerator is like a lazy Array.
+  #
+  # It provides methods from Enumerable to enumerate through its’ contents,
+  # size information and Array access methods. It’s used throughout Hallon
+  # for collections of items such as artist tracks, albums and so on.
+  class Enumerator
+    include Enumerable
+
+    # @return [Integer] number of items this enumerator can yield
+    attr_reader :size
+
+    # Construct an enumerator of `size` elements.
+    #
+    # @param [Integer] size
+    # @yield to the given block when an item is requested (through #each, #[] etc)
+    # @yieldparam [Integer] index item to retrieve
+    def initialize(size, &yielder)
+      @size  = size
+      @items = Array.new(size) do |i|
+        lambda { yielder[i] }
+      end
+    end
+
+    # Yield each item out of the enumerator.
+    #
+    # @yield obj
+    # @return [Enumerator]
+    def each
+      tap do
+        size.times { |i| yield(self[i]) }
+      end
+    end
+
+    # @overload [](index)
+    #   @return [Object, nil]
+    #
+    # @overload [](start, length)
+    #   @return [Array, nil]
+    #
+    # @overload [](range)
+    #   @return [Array, nil]
+    #
+    # Works exactly the same as Array#[], including the special cases.
+    #
+    # @see http://rdoc.info/stdlib/core/1.9.2/Array:[]
+    def [](*args)
+      result = @items[*args]
+
+      if result.nil?
+        nil
+      elsif result.respond_to?(:map)
+        result.map(&:call)
+      else
+        result.call
+      end
+    end
+
+    # @return [String] String representation of the Enumerator.
+    def to_s
+      "<#{self.class.name}:0x#{object_id.to_s(16)} @size=#{size}>"
+    end
+  end
+end

data/lib/hallon/error.rb

@@ -9,7 +9,7 @@ module Hallon
       #
       # @return [Hash<Symbol, Integer>]
       def table
-        Spotify::enum_type(:error).to_hash
+        Spotify.enum_type(:error).to_hash
       end
 
       # Given a number or a symbol, find both the symbol and the error
@@ -18,7 +18,7 @@ module Hallon
       # @param [Symbol, Fixnum] error
       # @return [[Fixnum, Symbol]] (error code, error symbol)
       def disambiguate(error)
-        @enum ||= Spotify::enum_type(:error)
+        @enum ||= Spotify.enum_type(:error)
 
         if error.is_a? Symbol
           error = @enum[symbol = error]
@@ -38,15 +38,17 @@ module Hallon
       # @param [Fixnum, Symbol]
       # @return [String]
       def explain(error)
-        Spotify::error_message disambiguate(error)[0]
+        Spotify.error_message disambiguate(error)[0]
       end
 
-      # Raise an {Error} with the given errno, unless it is `0` or `:ok`.
+      # Raise an {Error} with the given errno, unless it is `nil`, `:timeout`, `0` or `:ok`.
       #
       # @param [Fixnum, Symbol] error
       # @return [nil]
-      def maybe_raise(error)
-        error, symbol = disambiguate(error)
+      def maybe_raise(x)
+        return nil if [nil, :timeout].include?(x)
+
+        error, symbol = disambiguate(x)
         return symbol if symbol == :ok
 
         message = []

data/lib/hallon/ext/spotify.rb

@@ -15,11 +15,11 @@ module Spotify
     #
     # @param [FFI::Pointer] ptr
     # @param [Symbol] type session, link, etc
-    # @param [Boolean[ add_ref increase reference count
+    # @param [Boolean] add_ref increase reference count
     # @return [FFI::AutoPointer]
     def initialize(ptr, type, add_ref = false)
       super ptr, releaser_for(@type = type)
-      Spotify::send(:"#{type}_add_ref", ptr) if add_ref
+      Spotify.send(:"#{type}_add_ref", ptr) if add_ref
     end
 
     # Create a proc that will accept a pointer of a given type and
@@ -31,7 +31,7 @@ module Spotify
       lambda do |ptr|
         unless ptr.null?
           $stdout.puts "Spotify::#{type}_release(#{ptr})" if $DEBUG
-          Spotify::send(:"#{type}_release", ptr)
+          Spotify.send(:"#{type}_release", ptr)
         end
       end
     end

data/lib/hallon/image.rb

@@ -7,21 +7,21 @@ module Hallon
     extend Linkable
 
     from_link :as_image do |link, session|
-      Spotify::image_create_from_link(session, link)
+      Spotify.image_create_from_link(session, link)
     end
 
     to_link :from_image
 
     # Image triggers `:load` when loaded
-    include Hallon::Observable
+    include Observable
 
     # Create a new instance of an Image.
     #
     # @param [String, Link, FFI::Pointer] link link or image id
     # @param [Hallon::Session] session
-    def initialize(link, session = Session.instance)
+    def initialize(link)
       if link.is_a?(String)
-        link = to_id($1) if link =~ %r|image[:/](\h{40})|
+        link = to_id($1) if link =~ %r|image[:/]([a-fA-F0-9]{40})|
 
         FFI::MemoryPointer.new(:char, 20) do |ptr|
           ptr.write_bytes link
@@ -33,11 +33,14 @@ module Hallon
 
       @pointer = Spotify::Pointer.new link, :image
 
-      @callback = proc { trigger(:load) }
-      Spotify::image_add_load_callback(@pointer, @callback, nil)
+      @callback = proc { trigger :load }
+      Spotify.image_add_load_callback(@pointer, @callback, nil)
 
       # TODO: remove load_callback when @pointer is released
-      # TODO: this makes libspotify segfault, figure out why
+      # NOTE: on(:load) will trigger while load callback is still executing,
+      #       and removing the load callback from within the load callback
+      #       does not make libspotify happy, and thus segfaults D:
+      #
       # on(:load) { Spotify::image_remove_load_callback(@pointer, @callback, nil) }
     end
 
@@ -45,21 +48,21 @@ module Hallon
     #
     # @return [Boolean]
     def loaded?
-      Spotify::image_is_loaded(@pointer)
+      Spotify.image_is_loaded(@pointer)
     end
 
     # Retrieve the current error status.
     #
     # @return [Symbol] error
     def status
-      Spotify::image_error(@pointer)
+      Spotify.image_error(@pointer)
     end
 
     # Retrieve image format.
     #
     # @return [Symbol] `:jpeg` or `:unknown`
     def format
-      Spotify::image_format(@pointer)
+      Spotify.image_format(@pointer)
     end
 
     # Retrieve image ID as a string.
@@ -67,7 +70,7 @@ module Hallon
     # @param [Boolean] raw true if you want the image id as a hexadecimal string
     # @return [String]
     def id(raw = false)
-      id = Spotify::image_image_id(@pointer).read_string(20)
+      id = Spotify.image_image_id(@pointer).read_string(20)
       raw ? id : to_hex(id)
     end
 
@@ -76,11 +79,21 @@ module Hallon
     # @return [String]
     def data
       FFI::MemoryPointer.new(:size_t) do |size|
-        data = Spotify::image_data(@pointer, size)
+        data = Spotify.image_data(@pointer, size)
         return data.read_bytes(size.read_size_t)
       end
     end
 
+    # True if the images both have the same ID, or if their
+    # pointers are the same.
+    #
+    # @see Base#==
+    def ==(other)
+      super or id(true) == other.id(true)
+    rescue NoMethodError, ArgumentError
+      false
+    end
+
     protected
       # @param [String]
       # @return [String]

data/lib/hallon/link.rb

@@ -28,7 +28,7 @@ module Hallon
     # @raise [ArgumentError] link could not be parsed
     def initialize(uri)
       if (link = uri).respond_to? :to_str
-        link = Spotify::link_create_from_string(link.to_str)
+        link = Spotify.link_create_from_string(link.to_str)
       end
 
       @pointer = Spotify::Pointer.new(link, :link)
@@ -40,14 +40,14 @@ module Hallon
     #
     # @return [Symbol]
     def type
-      Spotify::link_type(@pointer)
+      Spotify.link_type(@pointer)
     end
 
     # Spotify URI length.
     #
     # @return [Fixnum]
     def length
-      Spotify::link_as_string(@pointer, nil, 0)
+      Spotify.link_as_string(@pointer, nil, 0)
     end
 
     # Get the Spotify URI this Link represents.
@@ -57,7 +57,7 @@ module Hallon
     # @return [String]
     def to_str(length = length)
       FFI::Buffer.alloc_out(length + 1) do |b|
-        Spotify::link_as_string(@pointer, b, b.size)
+        Spotify.link_as_string(@pointer, b, b.size)
         return b.get_string(0)
       end
     end

data/lib/hallon/linkable.rb

@@ -35,9 +35,11 @@ module Hallon
       type    = as_object.to_s[/^(as_)?([^_]+)/, 2].to_sym
 
       define_method(:from_link) do |link, *args|
-        if link.is_a? FFI::Pointer then link else
+        link = if link.is_a? FFI::Pointer then link else
           block.call Link.new(link).pointer(type), *args
         end
+
+        link.tap { raise Hallon::Error, "invalid link" if link.null? }
       end
     end
 
@@ -51,7 +53,7 @@ module Hallon
     def to_link(cmethod)
       define_method(:to_link) do |*args|
         link = Spotify.__send__(:"link_create_#{cmethod}", @pointer, *args)
-        Hallon::Link.new(link)
+        Link.new(link)
       end
     end
   end

data/lib/hallon/observable.rb

@@ -4,9 +4,6 @@ module Hallon
   #
   # @private
   module Observable
-    # Required for maintaining thread-safety around #handlers
-    include Hallon::Synchronizable
-
     # Defines a handler for the given event.
     #
     # @example defining a handler and triggering it
@@ -33,7 +30,7 @@ module Hallon
     def on(*events, &block)
       raise ArgumentError, "no block given" unless block
       wrap = events.length > 1
-      events.each do |event|
+      events.map(&:to_sym).each do |event|
         block = proc { |*args| yield(event, *args) } if wrap
         __handlers[event] = [] unless __handlers.has_key?(event)
         __handlers[event] << block