hallon 0.0.0 → 0.1.0

data/lib/hallon/ext/spotify.rb

@@ -0,0 +1,101 @@
+# coding: utf-8
+
+# Extensions to the Spotify gem.
+#
+# @see https://github.com/Burgestrand/libspotify-ruby
+module Spotify
+  extend FFI::Library
+  ffi_lib ['libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
+
+  # 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.
+  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
+    # @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
+    end
+
+    # Create a proc that will accept a pointer of a given type and
+    # release it with the correct function if it’s not null.
+    #
+    # @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)
+        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
+      end
+    end
+  end
+
+  # Extensions to SessionConfig, allowing more sensible configuration names.
+  class SessionConfig < FFI::Struct
+    [:cache_location, :settings_location, :user_agent].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)
+      end
+    end
+
+    # Also sets application_key_size.
+    #
+    # @param [#to_s]
+    def application_key=(appkey)
+      self[:application_key] = FFI::MemoryPointer.from_string(appkey)
+      self[:application_key_size] = appkey.bytesize
+    end
+
+    # Allows setting compress_playlists using a boolean.
+    #
+    # @param [Boolean]
+    # @return [Boolean]
+    def compress_playlists=(bool)
+      self[:compress_playlists] = !! bool
+    end
+
+    # Allows setting initially_unload_playlists using a boolean.
+    #
+    # @note Set to the inverse of the requested value.
+    # @param [Boolean]
+    # @return [Boolean]
+    def load_playlists=(bool)
+      self[:initially_unload_playlists] = ! bool
+    end
+
+    # Allows setting dont_save_metadata_for_playlists using a boolean.
+    #
+    # @note Set to the inverse of the requested value.
+    # @param [Boolean]
+    # @return [Boolean]
+    def cache_playlist_metadata=(bool)
+      self[:dont_save_metadata_for_playlists] = ! bool
+    end
+  end
+end

data/lib/hallon/image.rb

@@ -0,0 +1,70 @@
+# coding: utf-8
+module Hallon
+  # Images are JPEG images that can be linked to and saved.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__image.html
+  class Image
+    extend Linkable
+
+    from_link(:image) do |link, session|
+      Spotify::image_create_from_link(session.pointer, link)
+    end
+
+    to_link(:image)
+
+    # Image triggers `:load` when loaded
+    include Hallon::Observable
+
+    # Create a new instance of an Image.
+    #
+    # @param [String, Link, FFI::Pointer] link
+    # @param [Hallon::Session] session
+    def initialize(link, session = Session.instance)
+      @callback = proc { trigger(:load) }
+      @pointer  = Spotify::Pointer.new from_link(link, session), :image
+      Spotify::image_add_load_callback(@pointer, @callback, nil)
+
+      # TODO: remove load_callback when @pointer is released
+      # TODO: this makes libspotify segfault, figure out why
+      # on(:load) { Spotify::image_remove_load_callback(@pointer, @callback, nil) }
+    end
+
+    # True if the image has been loaded.
+    #
+    # @return [Boolean]
+    def loaded?
+      Spotify::image_is_loaded(@pointer)
+    end
+
+    # Retrieve the current error status.
+    #
+    # @return [Symbol] error
+    def status
+      Spotify::image_error(@pointer)
+    end
+
+    # Retrieve image format.
+    #
+    # @return [Symbol] `:jpeg` or `:unknown`
+    def format
+      Spotify::image_format(@pointer)
+    end
+
+    # Retrieve image ID as a hexadecimal string.
+    #
+    # @return [String]
+    def id
+      Spotify::image_image_id(@pointer).read_string(20).unpack('H*')[0]
+    end
+
+    # Raw image data as a binary encoded string.
+    #
+    # @return [String]
+    def data
+      FFI::MemoryPointer.new(:size_t) do |size|
+        data = Spotify::image_data(@pointer, size)
+        return data.read_bytes(size.read_size_t)
+      end
+    end
+  end
+end

data/lib/hallon/link.rb

@@ -0,0 +1,101 @@
+# coding: utf-8
+module Hallon
+  # Wraps Spotify URIs in a class, giving access to methods performable on them.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__link.html
+  class Link
+    include Comparable
+
+    # True if the given Spotify URI is valid (parsable by libspotify).
+    #
+    # @param (see Hallon::Link#initialize)
+    # @return [Boolean]
+    def self.valid?(spotify_uri)
+      !! new(spotify_uri)
+    rescue ArgumentError
+      false
+    end
+
+    # Overloaded to short-circuit when given a Link.
+    #
+    # @return [Hallon::Link]
+    def self.new(uri)
+      uri.is_a?(Link) ? uri : super
+    end
+
+    # Parse the given Spotify URI into a Link.
+    #
+    # @note Unless you have a {Session} initialized, this will segfault!
+    # @param [#to_str] uri
+    # @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)
+      end
+
+      @pointer = Spotify::Pointer.new(link, :link)
+
+      raise ArgumentError, "#{uri} is not a valid Spotify link" if @pointer.null?
+    end
+
+    # Link type as a symbol.
+    #
+    # @return [Symbol]
+    def type
+      Spotify::link_type(@pointer)
+    end
+
+    # Spotify URI length.
+    #
+    # @return [Fixnum]
+    def length
+      Spotify::link_as_string(@pointer, nil, 0)
+    end
+
+    # Get the Spotify URI this Link represents.
+    #
+    # @see #length
+    # @param [Fixnum] length truncate to this size
+    # @return [String]
+    def to_str(length = length)
+      FFI::Buffer.alloc_out(length + 1) do |b|
+        Spotify::link_as_string(@pointer, b, b.size)
+        return b.get_string(0)
+      end
+    end
+
+    # Retrieve the full Spotify HTTP URL for this Link.
+    #
+    # @return [String]
+    def to_url
+      "http://open.spotify.com/%s" % to_str[8..-1].gsub(':', '/')
+    end
+
+    # Compare this Link to another object
+    #
+    # @param [#to_str] other
+    # @return [Integer]
+    def <=>(other)
+      to_str <=> String.try_convert(other)
+    end
+
+    # String representation of the given Link.
+    #
+    # @return [String]
+    def to_s
+      "<#{self.class.name} #{to_str}>"
+    end
+
+    # Retrieve the underlying pointer.
+    #
+    # @param [Symbol] expected_type if given, makes sure the link is of this type
+    # @return [FFI::Pointer]
+    # @raise ArgumentError if `type` is given and does not match link {#type}
+    def pointer(expected_type = nil)
+      unless type == expected_type
+        raise ArgumentError, "expected #{expected_type} link, but it is of type #{type}"
+      end if expected_type
+      @pointer
+    end
+  end
+end

data/lib/hallon/linkable.rb

@@ -0,0 +1,50 @@
+# coding: utf-8
+module Hallon
+  # Methods shared between objects that can be created from Spotify URIs,
+  # or can be turned into Spotify URIs.
+  #
+  # @note Linkable is not part of Hallons’ public API.
+  # @private
+  module Linkable
+    # These are extended onto a class when {Linkable} is included.
+    include Forwardable
+
+    # Creates `from_link` class & instance method which’ll convert a link to a pointer
+    #
+    # @example
+    #   # Creates instance method `from_link(link)`
+    #   from_link(:playlist) { |link| Spotify::link_as_playlist(link) }
+    #
+    # @param [Symbol] type expected link type
+    # @yield [link, *args] called when conversion is needed from Link pointer
+    # @yieldparam [Hallon::Link] link
+    # @yieldparam *args any extra arguments given to `#from_link`
+    # @see Link#pointer
+    def from_link(type)
+      define_singleton_method(:from_link) do |link, *args|
+        if link.is_a? FFI::Pointer then link else
+          yield Link.new(link).pointer(type), *args
+        end
+      end
+
+      def_delegators 'self.class', :from_link
+    end
+
+    # Defines `to_link` class & instance method.
+    #
+    # @example
+    #   to_link(:artist)
+    #
+    # @note Calls down to `Spotify::link_create_from_#{type}(@pointer)`
+    # @param [Symbol] type object kind
+    # @return [Link]
+    def to_link(type)
+      define_singleton_method(:to_link) do |ptr, *args|
+        link = Spotify.__send__(:"link_create_from_#{type}", ptr, *args)
+        Hallon::Link.new(link)
+      end
+
+      define_method(:to_link) { |*args, &block| self.class.to_link(@pointer, *args, &block) }
+    end
+  end
+end

data/lib/hallon/observable.rb

@@ -0,0 +1,91 @@
+# coding: utf-8
+module Hallon
+  # A module providing event capabilities to Hallon objects.
+  #
+  # @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
+    #   on(:callback) do |message|
+    #     puts message
+    #   end
+    #
+    #   trigger(:callback, "Moo!") # => prints "Moo!"
+    #
+    # @example multiple events with one handler
+    #   on(:a, :b, :c) do |name, *args|
+    #     puts "#{name} called with: #{args.inspect}"
+    #   end
+    #
+    #   trigger(:a) # => prints ":a called with: []"
+    #   trigger(:b, :c) # => prints ":b called with: [:c]"
+    #
+    # @note when defining a handler for multiple events, the
+    #       first argument passed to the handler is the name
+    #       of the event that called it
+    # @param [#to_sym] event name of event to handle
+    # @yield (*args) event handler block
+    # @see #initialize
+    def on(*events, &block)
+      raise ArgumentError, "no block given" unless block
+      wrap = events.length > 1
+      events.each do |event|
+        block = proc { |*args| yield(event, *args) } if wrap
+        __handlers[event] = [] unless __handlers.has_key?(event)
+        __handlers[event] << block
+      end
+    end
+
+    # Trigger a handler for a given event.
+    #
+    # @param [#to_sym] event
+    # @param [Object, ...] params given to each handler
+    def trigger(event, *params, &block)
+      catch :return do
+        return_value = nil
+        __handlers[event.to_sym].each do |handler|
+          return_value = handler.call(*params, &block)
+        end
+        return_value
+      end
+    end
+
+    # Run the given block, protecting all previous event handlers.
+    #
+    # @example
+    #   o = Object.new
+    #   o.instance_eval { include Hallon::Base }
+    #   o.on(:method) { "outside" }
+    #
+    #   puts o.on_method # => "outside"
+    #   o.protecting_handlers do
+    #     o.on(:method) { "inside" }
+    #     puts o.on_method # => "inside"
+    #   end
+    #   puts o.on_method # => "outside"
+    #
+    # @yield
+    # @return whatever the given block returns
+    def protecting_handlers
+      deep_copy = __handlers.dup.clear
+      __handlers.each do |k, v|
+        deep_copy[k] = v.dup
+      end
+      yield
+    ensure
+      __handlers.replace deep_copy
+    end
+
+    private
+      # Hash mapping events to handlers.
+      #
+      # @return [Hash]
+      def __handlers
+        @__handlers ||= Hash.new([])
+      end
+  end
+end

data/lib/hallon/session.rb

@@ -0,0 +1,189 @@
+# coding: utf-8
+require 'singleton'
+require 'timeout'
+require 'thread'
+
+module Hallon
+  # The Session is fundamental for all communication with Spotify.
+  # Pretty much all API calls require you to have established a session
+  # with Spotify before using them.
+  #
+  # @see https://developer.spotify.com/en/libspotify/docs/group__session.html
+  class Session
+    # The options Hallon used at {Session#initialize}.
+    #
+    # @return [Hash]
+    attr_reader :options
+
+    # Underlying Spotify pointer.
+    #
+    # @return [FFI::Pointer]
+    attr_reader :pointer
+
+    # libspotify only allows one session per process.
+    include Singleton
+    class << self
+      undef :instance
+    end
+
+    # Session allows you to define your own callbacks.
+    include Hallon::Observable
+
+    # Allows you to create a Spotify session. Subsequent calls to this method
+    # will return the previous instance, ignoring any passed arguments.
+    #
+    # @param (see Session#initialize)
+    # @see Session#initialize
+    # @return [Session]
+    def Session.instance(*args, &block)
+      @__instance__ ||= new(*args, &block)
+    end
+
+    # Create a new Spotify session.
+    #
+    # @param [#to_s] appkey
+    # @param [Hash] options
+    # @option options [String] :user_agent ("Hallon") User-Agent to use (length < 256)
+    # @option options [String] :settings_path ("tmp") where to save settings and user-specific cache
+    # @option options [String] :cache_path ("") where to save cache files (set to "" to disable)
+    # @option options [Bool]   :load_playlists (true) load playlists into RAM on startup
+    # @option options [Bool]   :compress_playlists (true) compress local copies of playlists
+    # @option options [Bool]   :cache_playlist_metadata (true) cache metadata for playlists locally
+    # @yield allows you to define handlers for events (see {Hallon::Base#on})
+    # @raise [ArgumentError] if `options[:user_agent]` is more than 256 characters long
+    # @raise [Hallon::Error] if `sp_session_create` fails
+    # @see http://developer.spotify.com/en/libspotify/docs/structsp__session__config.html
+    def initialize(appkey, options = {}, &block)
+      @appkey  = appkey.to_s
+      @options = {
+        :user_agent => "Hallon",
+        :settings_path => "tmp",
+        :cache_path => "",
+        :load_playlists => true,
+        :compress_playlists => true,
+        :cache_playlist_metadata => true
+      }.merge(options)
+
+      if @options[:user_agent].bytesize > 255
+        raise ArgumentError, "User-agent must be less than 256 bytes long"
+      end
+
+      # Set configuration, as well as callbacks
+      config  = Spotify::SessionConfig.new
+      config[:api_version]   = Hallon::API_VERSION
+      config.application_key = @appkey
+      @options.each { |(key, value)| config.send(:"#{key}=", value) }
+      config[:callbacks]     = Spotify::SessionCallbacks.new(self, @sp_callbacks = {})
+
+      instance_eval(&block) if block_given?
+
+      # You pass a pointer to the session pointer to libspotify >:)
+      FFI::MemoryPointer.new(:pointer) do |p|
+        Hallon::Error::maybe_raise Spotify::session_create(config, p)
+        @pointer = p.read_pointer
+      end
+    end
+
+    # Process pending Spotify events (might fire callbacks).
+    #
+    # @return [Fixnum] minimum time until it should be called again
+    def process_events
+      FFI::MemoryPointer.new(:int) do |p|
+        Spotify::session_process_events(@pointer, p)
+        return p.read_int
+      end
+    end
+
+    # Wait for the given callbacks to fire until the block returns true
+    #
+    # @param [Symbol, ...] *events list of events to wait for
+    # @yield [Symbol, *args] name of the callback that fired, and its’ arguments
+    # @return [Hash<Event, Arguments>]
+    def process_events_on(*events, &block)
+      channel = SizedQueue.new(1)
+
+      protecting_handlers do
+        on(*events) { |*args| channel << args }
+        on(:notify_main_thread) { channel << :notify }
+
+        loop do
+          begin
+            process_events
+            params = Timeout::timeout(0.25) { channel.pop }
+            redo if params == :notify
+          rescue Timeout::Error
+            params = nil
+          end
+
+          if result = block.call(*params)
+            return result
+          end
+        end
+      end
+    end
+
+    # Log into Spotify using the given credentials.
+    #
+    # @param [String] username
+    # @param [String] password
+    # @return [self]
+    def login(username, password)
+      Spotify::session_login(@pointer, username, password)
+      self
+    end
+
+    # Logs out of Spotify. Does nothing if not logged in.
+    #
+    # @return [self]
+    def logout
+      Spotify::session_logout(@pointer) if logged_in?
+      self
+    end
+
+    # Retrieve the currently logged in {User}.
+    #
+    # @return [User]
+    def user
+      User.new Spotify::session_user(@pointer)
+    end
+
+    # Retrieve the relation type between logged in {User} and `user`.
+    #
+    # @return [Symbol] :unknown, :none, :unidirectional or :bidirectional
+    def relation_type?(user)
+      Spotify::user_relation_type(@pointer, user.pointer)
+    end
+
+    # Retrieve current connection status.
+    #
+    # @return [Symbol]
+    def status
+      Spotify::session_connectionstate(@pointer)
+    end
+
+    # True if currently logged in.
+    # @see #status
+    def logged_in?
+      status == :logged_in
+    end
+
+    # True if logged out.
+    # @see #status
+    def logged_out?
+      status == :logged_out
+    end
+
+    # True if session has been disconnected.
+    # @see #status
+    def disconnected?
+      status == :disconnected
+    end
+
+    # String representation of the Session.
+    #
+    # @return [String]
+    def to_s
+      "<#{self.class.name}>"
+    end
+  end
+end