hallon 0.8.0 → 0.9.0

data/lib/hallon/base.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 module Hallon
   # All objects in Hallon are mere representations of Spotify objects.
   # Hallon::Base covers basic functionality shared by all of these.
@@ -17,11 +18,73 @@ module Hallon
       super
     end
 
-    # The current Session instance.
-    #
-    # @return [Session]
-    def session
-      Session.instance
+    # Default string representation of self.
+    def to_s
+      name    = self.class.name
+      address = pointer.address.to_s(16)
+      "<#{name} address=0x#{address}>"
     end
+
+    private
+      # @macro [attach] to_link
+      #   @method to_link
+      #   @scope  instance
+      #   @return [Hallon::Link] {Link} for the current object.
+      def self.to_link(cmethod)
+        # this is here to work around a YARD limitation, see
+        # {Linkable} for the actual source
+      end
+
+      # @macro [attach] from_link
+      #   @method from_link
+      #   @scope  instance
+      #   @visibility private
+      #   @param  [String, Hallon::Link, Spotify::Pointer] link
+      #   @return [Spotify::Pointer] pointer representation of given link.
+      def self.from_link(as_object, &block)
+        # this is here to work around a YARD limitation, see
+        # {Linkable} for the actual source
+      end
+
+      # The current Session instance.
+      #
+      # @return [Session]
+      def session
+        Session.instance
+      end
+
+      # Convert a given object to a pointer by best of ability.
+      #
+      # @param [Spotify::Pointer, String, Link] resource
+      # @return [Spotify::Pointer]
+      # @raise [TypeError] when pointer could not be created, or null
+      def to_pointer(resource, type, *args)
+        if resource.is_a?(FFI::Pointer) and not resource.is_a?(Spotify::Pointer)
+          raise TypeError, "Hallon does not support raw FFI::Pointers, wrap it in a Spotify::Pointer"
+        end
+
+        pointer = if Spotify::Pointer.typechecks?(resource, type)
+          resource
+        elsif is_linkable? and Spotify::Pointer.typechecks?(resource, :link)
+          from_link(resource, *args)
+        elsif is_linkable? and Link.valid?(resource)
+          from_link(resource, *args)
+        elsif block_given?
+          yield(resource, *args)
+        end
+
+        if pointer.nil? or pointer.null?
+          raise ArgumentError, "#{resource.inspect} is not a valid spotify #{type} URI or pointer"
+        elsif not Spotify::Pointer.typechecks?(pointer, type)
+          raise TypeError, "“#{resource}” is of type #{resource.type}, #{type} expected"
+        else
+          pointer
+        end
+      end
+
+      # @return [Boolean] true if the object can convert links to pointers
+      def is_linkable?
+        respond_to?(:from_link, true)
+      end
   end
 end

data/lib/hallon/enumerator.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 module Hallon
   # Hallon::Enumerator is like a lazy Array.
   #

data/lib/hallon/error.rb

@@ -35,6 +35,9 @@ module Hallon
 
       # Explain a Spotify error with a string message.
       #
+      # @example
+      #   Hallon::Error.explain(:ok) # => "No error"
+      #
       # @param [Fixnum, Symbol]
       # @return [String]
       def explain(error)

data/lib/hallon/ext/spotify.rb

@@ -4,22 +4,125 @@
 #
 # @see https://github.com/Burgestrand/libspotify-ruby
 module Spotify
-  extend FFI::Library
-  ffi_lib ['libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
+  # Fetches the associated value of an enum from a given symbol.
+  #
+  # @param [Symbol] symbol
+  # @param [#to_s] type
+  # @raise ArgumentError on failure
+  def self.enum_value!(symbol, type)
+    enum_value(symbol) or raise ArgumentError, "invalid #{type}: #{symbol}"
+  end
+
+  # Wraps the function `function` so that it always returns
+  # a Spotify::Pointer with correct refcount. Functions that
+  # contain the word `create` are assumed to start out with
+  # a refcount of `+1`.
+  #
+  # @param [#to_s] function
+  # @param [#to_s] return_type
+  # @raise [NoMethodError] if `function` is not defined
+  # @see Spotify::Pointer
+  def self.wrap_function(function, return_type)
+    define_singleton_method("#{function}!") do |*args|
+      pointer = public_send(function, *args)
+      Spotify::Pointer.new(pointer, return_type, function !~ /create/)
+    end
+  end
+
+  # @macro [attach] wrap_function
+  #   Same as {Spotify}.`$1`, but wraps result in a {Spotify::Pointer}.
+  #
+  #   @method $1!
+  #   @return [Spotify::Pointer<$2>]
+  #   @see #$1
+  wrap_function :session_user, :user
+  wrap_function :session_playlistcontainer, :playlistcontainer
+  wrap_function :session_inbox_create, :playlist
+  wrap_function :session_starred_create, :playlist
+  wrap_function :session_starred_for_user_create, :playlist
+  wrap_function :session_publishedcontainer_for_user_create, :playlistcontainer
+
+  wrap_function :track_artist, :artist
+  wrap_function :track_album, :album
+  wrap_function :localtrack_create, :track
+
+  wrap_function :album_artist, :artist
+
+  wrap_function :albumbrowse_create, :albumbrowse
+  wrap_function :albumbrowse_album, :album
+  wrap_function :albumbrowse_artist, :artist
+  wrap_function :albumbrowse_track, :track
+
+  wrap_function :artistbrowse_create, :artistbrowse
+  wrap_function :artistbrowse_artist, :artist
+  wrap_function :artistbrowse_track, :track
+  wrap_function :artistbrowse_album, :album
+  wrap_function :artistbrowse_similar_artist, :artist
+
+  wrap_function :image_create, :image
+  wrap_function :image_create_from_link, :image
+
+  wrap_function :link_as_track, :track
+  wrap_function :link_as_track_and_offset, :track
+  wrap_function :link_as_album, :album
+  wrap_function :link_as_artist, :artist
+  wrap_function :link_as_user, :user
+
+  wrap_function :link_create_from_string, :link
+  wrap_function :link_create_from_track, :link
+  wrap_function :link_create_from_album, :link
+  wrap_function :link_create_from_artist, :link
+  wrap_function :link_create_from_search, :link
+  wrap_function :link_create_from_playlist, :link
+  wrap_function :link_create_from_artist_portrait, :link
+  wrap_function :link_create_from_artistbrowse_portrait, :link
+  wrap_function :link_create_from_album_cover, :link
+  wrap_function :link_create_from_image, :link
+  wrap_function :link_create_from_user, :link
+
+  wrap_function :search_create, :search
+  wrap_function :radio_search_create, :search
+  wrap_function :search_track, :track
+  wrap_function :search_album, :album
+  wrap_function :search_artist, :artist
+
+  wrap_function :playlist_track, :track
+  wrap_function :playlist_track_creator, :user
+  wrap_function :playlist_owner, :user
+  wrap_function :playlist_create, :playlist
+
+  wrap_function :playlistcontainer_playlist, :playlist
+  wrap_function :playlistcontainer_add_new_playlist, :playlist
+  wrap_function :playlistcontainer_add_playlist, :playlist
+  wrap_function :playlistcontainer_owner, :user
+
+  wrap_function :toplistbrowse_create, :toplistbrowse
+  wrap_function :toplistbrowse_artist, :artist
+  wrap_function :toplistbrowse_album, :album
+  wrap_function :toplistbrowse_track, :track
+
+  wrap_function :inbox_post_tracks, :inbox
 
   # The Pointer is a kind of AutoPointer specially tailored for Spotify
-  # objects. It will automatically release the inner pointer with the
-  # proper function, based on the given type to #initialize.
+  # objects, that releases the raw pointer on GC.
   class Pointer < FFI::AutoPointer
-    # Initialize the Spotify::Pointer
-    #
-    # @param [FFI::Pointer] ptr
-    # @param [Symbol] type session, link, etc
-    # @param [Boolean] add_ref increase reference count
+    attr_reader :type
+
+    # @param [FFI::Pointer] pointer
+    # @param [#to_s] type session, link, etc
+    # @param [Boolean] add_ref
     # @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
+    def initialize(pointer, type, add_ref)
+      super pointer, self.class.releaser_for(@type = type.to_s)
+
+      unless pointer.null?
+        Spotify.send(:"#{type}_add_ref", pointer)
+      end if add_ref
+    end
+
+    # @return [String] representation of the spotify pointer
+    def to_s
+      "<#{self.class} address=#{address} type=#{type}>"
     end
 
     # Create a proc that will accept a pointer of a given type and
@@ -27,45 +130,42 @@ module Spotify
     #
     # @param [Symbol]
     # @return [Proc]
-    def releaser_for(type)
-      lambda do |ptr|
-        unless ptr.null?
-          $stdout.puts "Spotify::#{type}_release(#{ptr})" if $DEBUG
-          Spotify.send(:"#{type}_release", ptr)
+    def self.releaser_for(type)
+      lambda do |pointer|
+        unless pointer.null?
+          $stdout.puts "Spotify::#{type}_release(#{pointer})" if $DEBUG
+          Spotify.send(:"#{type}_release", pointer)
         end
       end
     end
-  end
 
-  # Extensions to SessionCallbacks, making it easier to define callbacks.
-  class SessionCallbacks < FFI::Struct
-    # Assigns the callbacks to call the given target; the callback
-    # procs are stored in the `storage` parameter. **Make sure the
-    # storage does not get garbage collected as long as these callbacks
-    # are needed!**
-    #
-    # @param [Object] target
-    # @param [#&#91;&#93;&#61;] storage
-    def initialize(target, storage)
-      members.each do |member|
-        callback = lambda { |ptr, *args| target.trigger(member, *args) }
-        self[member] = storage[member] = callback
+    # @param [Object] pointer
+    # @param [Symbol] type (optional, no type checking is done if not given)
+    # @return [Boolean] true if object is a spotify pointer and of correct type
+    def self.typechecks?(object, type = nil)
+      if ! object.is_a?(Spotify::Pointer)
+        false
+      elsif type
+        object.type == type.to_s
+      else
+        true
       end
     end
   end
 
   # Extensions to SessionConfig, allowing more sensible configuration names.
-  class SessionConfig < FFI::Struct
-    [:cache_location, :settings_location, :user_agent].each do |field|
+  SessionConfig.class_eval do
+    [:cache_location, :settings_location, :user_agent, :device_id, :tracefile].each do |field|
       method = field.to_s.gsub('location', 'path')
+
       define_method(:"#{method}") { self[field].read_string }
       define_method(:"#{method}=") do |string|
-        self[field] = FFI::MemoryPointer.from_string(string)
+        string &&= FFI::MemoryPointer.from_string(string)
+        self[field] = string
       end
     end
 
-    # Also sets application_key_size.
-    #
+    # @note Also sets application_key_size.
     # @param [#to_s]
     def application_key=(appkey)
       self[:application_key] = FFI::MemoryPointer.from_string(appkey)
@@ -98,4 +198,37 @@ module Spotify
       self[:dont_save_metadata_for_playlists] = ! bool
     end
   end
+
+  # Extensions to SessionCallbacks, making it easier to define callbacks.
+  SessionCallbacks.class_eval do
+    # Assigns the callbacks to call the given target; the callback
+    # procs are stored in the `storage` parameter. **Make sure the
+    # storage does not get garbage collected as long as these callbacks
+    # are needed!**
+    #
+    # @param [Object] target
+    # @param [#&#91;&#93;&#61;] storage
+    def initialize(target, storage)
+      members.each do |member|
+        callback = lambda { |ptr, *args| target.trigger(member, *args) }
+        self[member] = storage[member] = callback
+      end
+    end
+  end
+
+  PlaylistCallbacks.class_eval do
+    # Assigns the callbacks to call the given target; the callback
+    # procs are stored in the `storage` parameter. **Make sure the
+    # storage does not get garbage collected as long as these callbacks
+    # are needed!**
+    #
+    # @param [Object] target
+    # @param [#&#91;&#93;&#61;] storage
+    def initialize(target, storage)
+      members.each do |member|
+        callback = lambda { |ptr, *args| target.trigger(member, *args[0...-1]) }
+        self[member] = storage[member] = callback
+      end
+    end
+  end
 end

data/lib/hallon/image.rb

@@ -6,8 +6,8 @@ module Hallon
   class Image < Base
     extend Linkable
 
-    from_link :as_image do |link, session|
-      Spotify.image_create_from_link(session, link)
+    from_link :as_image do |link|
+      Spotify.image_create_from_link!(session.pointer, link)
     end
 
     to_link :from_image
@@ -17,77 +17,63 @@ module Hallon
 
     # Create a new instance of an Image.
     #
-    # @param [String, Link, FFI::Pointer] link link or image id
+    # @example from a link
+    #   image = Hallon::Image.new("spotify:image:3ad93423add99766e02d563605c6e76ed2b0e450")
+    #
+    # @example from an image id
+    #   image = Hallon::Image.new("3ad93423add99766e02d563605c6e76ed2b0e450")
+    #
+    # @param [String, Link, Spotify::Pointer] link link or image id
     # @param [Hallon::Session] session
     def initialize(link)
-      if link.is_a?(String)
-        link = to_id($1) if link =~ %r|image[:/]([a-fA-F0-9]{40})|
-
-        FFI::MemoryPointer.new(:char, 20) do |ptr|
-          ptr.write_bytes link
-          link = Spotify.image_create(session.pointer, ptr)
-        end
-      else
-        link = from_link(link, session.pointer)
+      if link.respond_to?(:=~) and link =~ %r~(?:image[:/]|\A)([a-fA-F0-9]{40})\z~
+        link = to_id($1)
       end
 
-      @pointer = Spotify::Pointer.new link, :image
+      @pointer = to_pointer(link, :image) do
+        ptr = FFI::MemoryPointer.new(:char, 20)
+        ptr.write_bytes(link)
+        Spotify.image_create!(session.pointer, ptr)
+      end
 
       @callback = proc { trigger :load }
-      Spotify.image_add_load_callback(@pointer, @callback, nil)
-
-      # TODO: remove load_callback when @pointer is released
-      # 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) }
+      Spotify.image_add_load_callback(pointer, @callback, nil)
     end
 
-    # True if the image has been loaded.
-    #
-    # @return [Boolean]
+    # @return [Boolean] true if the image is loaded.
     def loaded?
-      Spotify.image_is_loaded(@pointer)
+      Spotify.image_is_loaded(pointer)
     end
 
-    # Retrieve the current error status.
-    #
-    # @return [Symbol] error
+    # @see Error.explain
+    # @return [Symbol] image error status.
     def status
-      Spotify.image_error(@pointer)
+      Spotify.image_error(pointer)
     end
 
-    # Retrieve image format.
-    #
-    # @return [Symbol] `:jpeg` or `:unknown`
+    # @return [Symbol] image format, one of `:jpeg` or `:unknown`
     def format
-      Spotify.image_format(@pointer)
+      Spotify.image_format(pointer)
     end
 
-    # Retrieve image ID as a string.
-    #
     # @param [Boolean] raw true if you want the image id as a hexadecimal string
-    # @return [String]
+    # @return [String] image ID as a 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
 
-    # Raw image data as a binary encoded string.
-    #
-    # @return [String]
+    # @return [String] raw image data as a binary encoded 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#==
+    # @param [Object] other
+    # @return [Boolean] true if the images are the same object or have the same ID.
     def ==(other)
       super or id(true) == other.id(true)
     rescue NoMethodError, ArgumentError