hallon 0.8.0 → 0.9.0

data/lib/hallon/link.rb

@@ -6,92 +6,78 @@ module Hallon
   class Link < Base
     # True if the given Spotify URI is valid (parsable by libspotify).
     #
-    # @param (see Hallon::Link#initialize)
+    # @param [#to_s] spotify_uri
     # @return [Boolean]
     def self.valid?(spotify_uri)
-      !! new(spotify_uri)
-    rescue ArgumentError
-      false
-    end
+      if spotify_uri.is_a?(Link)
+        return true
+      end
 
-    # Overloaded to short-circuit when given a Link.
-    #
-    # @return [Hallon::Link]
-    def self.new(uri)
-      uri.is_a?(Link) ? uri : super
+      link = Spotify.link_create_from_string!(spotify_uri.to_s)
+      not link.null?
     end
 
     # Parse the given Spotify URI into a Link.
     #
-    # @note Unless you have a {Session} initialized, this will segfault!
+    # @note You must initialize a Session before you call this method.
     # @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)
+      # if no session instance exists, libspotify segfaults, so assert that we have one
+      unless Session.instance?
+        raise "Link.new requires an existing Session instance"
       end
 
-      @pointer = Spotify::Pointer.new(link, :link)
-
-      raise ArgumentError, "#{uri} is not a valid Spotify link" if @pointer.null?
+      @pointer = to_pointer(uri, :link) do
+        Spotify.link_create_from_string!(uri.to_str)
+      end
     end
 
-    # Link type as a symbol.
-    #
-    # @return [Symbol]
+    # @return [Symbol] link type as a symbol (e.g. `:playlist`).
     def type
-      Spotify.link_type(@pointer)
+      Spotify.link_type(pointer)
     end
 
-    # Spotify URI length.
-    #
-    # @return [Fixnum]
+    # @return [Fixnum] spotify URI length.
     def length
-      Spotify.link_as_string(@pointer, nil, 0)
+      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]
+    # @return [String] spotify URI representation of this Link.
     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
 
-    # Retrieve the full Spotify HTTP URL for this Link.
-    #
-    # @return [String]
+    alias_method :to_uri, :to_str
+
+    # @return [String] full Spotify HTTP URL.
     def to_url
       "http://open.spotify.com/%s" % to_str[8..-1].gsub(':', '/')
     end
 
-    # True if this link equals `other.to_str`
-    #
-    # @param [#to_str] other
-    # @return [Boolean]
+    # @param [Object] other
+    # @return [Boolean] true if this link equals `other.to_str`.
     def ==(other)
-      return super unless other.respond_to?(:to_str)
       to_str == other.to_str
+    rescue NoMethodError
+      super
     end
 
-    # String representation of the given Link.
-    #
-    # @return [String]
+    # @return [String] string representation of the Link.
     def to_s
       "<#{self.class.name} #{to_str}>"
     end
 
-    # Retrieve the underlying pointer. Used by {Linkable}.
-    #
     # @param [Symbol] expected_type if given, makes sure the link is of this type
-    # @return [FFI::Pointer]
+    # @return [Spotify::Pointer] the underlying Spotify::Pointer.
     # @raise ArgumentError if `type` is given and does not match link {#type}
     def pointer(expected_type = nil)
-      unless type == expected_type
+      unless type == expected_type or (expected_type == :playlist and type == :starred)
         raise ArgumentError, "expected #{expected_type} link, but it is of type #{type}"
       end if expected_type
       super()

data/lib/hallon/linkable.rb

@@ -3,58 +3,106 @@ 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.
+  # @note Linkable is part of Hallons’ private API. You probably do not
+  #       not need to care about these methods.
+  #
   # @private
   module Linkable
-    # Defines `#from_link`, used in converting a link to a pointer.
+    # Defines `#from_link`, used in converting a link to a pointer. You
+    # can either pass it a `method_name`, or a `type` and a block.
     #
-    # @overload from_link(type)
-    #   Convert from a link using said method.
+    # @overload from_link(method_name)
+    #   Define `#from_link` simply by giving the name of the method,
+    #   minus the `link_` prefix.
     #
     #   @example
-    #     from_link :as_album # => Spotify.link_as_album(pointer, *args)
+    #     class Album
+    #       extend Linkable
+    #
+    #       from_link :as_album # => Spotify.link_as_album(pointer, *args)
+    #       # ^ is roughly equivalent to:
+    #       def from_link(link, *args)
+    #         unless Spotify::Pointer.typechecks?(link, :link)
+    #           link = Link.new(link).pointer(:album)
+    #         end
+    #
+    #         Spotify.link_as_album!(link)
+    #       end
+    #     end
     #
-    #   @param [Symbol] as_object link conversion method, formatted `as_type`
+    #   @param [Symbol] method_name
     #
     # @overload from_link(type) { |*args| … }
-    #   Use the given block to convert the link.
+    #   Define `#from_link` to use the given block to convert an object
+    #   from a link. The link is converted to a pointer and typechecked
+    #   to be of the same type as `type` before given to the block.
     #
     #   @example
-    #     from_link :profile do |pointer|
-    #       Spotify.link_as_user(pointer)
+    #     class User
+    #       extend Linkable
+    #
+    #       from_link :profile do |pointer|
+    #         Spotify.link_as_user!(pointer)
+    #       end
+    #       # ^ is roughly equivalent to:
+    #       def from_link(link, *args)
+    #         unless Spotify::Pointer.typechecks?(link, :link)
+    #           link = Link.new(link).pointer(:profile)
+    #         end
+    #
+    #         Spotify.link_as_user!(link)
+    #       end
     #     end
     #
     #   @param [#to_s] type link type
     #   @yield [link, *args] called when conversion is needed from Link pointer
-    #   @yieldparam [Hallon::Link] link
+    #   @yieldparam [Spotify::Pointer] link
     #   @yieldparam *args any extra arguments given to `#from_link`
     #
-    # @see Link#pointer
+    # @note Private API. You probably do not need to care about this method.
     def from_link(as_object, &block)
-      block ||= Spotify.method(:"link_#{as_object}")
+      block ||= Spotify.method(:"link_#{as_object}!")
       type    = as_object.to_s[/^(as_)?([^_]+)/, 2].to_sym
 
       define_method(:from_link) do |link, *args|
-        link = if link.is_a? FFI::Pointer then link else
-          block.call Link.new(link).pointer(type), *args
-        end
+        if link.is_a?(FFI::Pointer) and not link.is_a?(Spotify::Pointer)
+          link
+        else
+          unless Spotify::Pointer.typechecks?(link, :link)
+            link = Link.new(link).pointer(type)
+          end
 
-        link.tap { raise Hallon::Error, "invalid link" if link.null? }
+          instance_exec(link, *args, &block)
+        end
       end
+
+      private :from_link
     end
 
-    # Defines `#to_link` method, which converts the the current object to a {Link}
+    # Defines `#to_link` method, used in converting the object to a {Link}.
     #
     # @example
-    #   to_link :from_artist # => Spotify.link_create_from_artist
+    #   class Artist
+    #     extend Linkable
     #
-    # @param [Symbol] cmethod object kind
+    #     to_link :from_artist
+    #     # ^ is the same as:
+    #     def to_link(*args)
+    #       link = Spotify.link_create_from_artist!(pointer, *args)
+    #       Link.new(link)
+    #     end
+    #   end
+    #
+    # @param [Symbol] cmethod name of the C method, say `from_artist` in `Spotify.link_create_from_artist`.
     # @return [Link]
     def to_link(cmethod)
       define_method(:to_link) do |*args|
-        link = Spotify.__send__(:"link_create_#{cmethod}", @pointer, *args)
+        link = Spotify.__send__(:"link_create_#{cmethod}!", pointer, *args)
         Link.new(link)
       end
     end
+
+    private :from_link
+    private :to_link
   end
 end

data/lib/hallon/observable.rb

@@ -26,7 +26,6 @@ module Hallon
     #       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

data/lib/hallon/player.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 module Hallon
   # A wrapper around Session for playing, stopping and otherwise
   # controlling the playback features of libspotify.
@@ -9,6 +10,9 @@ module Hallon
   class Player
     include Observable
 
+    # @return [Spotify::Pointer<Session>] session pointer
+    attr_reader :pointer
+
     # @return [Array<Symbol>] a list of available playback bitrates.
     def self.bitrates
       Spotify.enum_type(:bitrate).symbols.sort_by do |sym|
@@ -74,7 +78,7 @@ module Hallon
     # @param [Symbol] bitrate one of :96k, :160k, :320k
     # @return [Symbol]
     def bitrate=(bitrate)
-      Spotify.session_preferred_bitrate(@pointer, bitrate)
+      Spotify.session_preferred_bitrate(pointer, bitrate)
     end
 
     # Loads a Track for playing.
@@ -83,7 +87,7 @@ module Hallon
     # @return [Player]
     # @raise [Error] if the track could not be loaded
     def load(track)
-      error = Spotify.session_player_load(@pointer, track.pointer)
+      error = Spotify.session_player_load(pointer, track.pointer)
       tap { Error.maybe_raise(error) }
     end
 
@@ -93,7 +97,7 @@ module Hallon
     # @param [Track] track
     # @return [Player]
     def prefetch(track)
-      error = Spotify.session_player_prefetch(@pointer, track.pointer)
+      error = Spotify.session_player_prefetch(pointer, track.pointer)
       tap { Error.maybe_raise(error) }
     end
 
@@ -102,21 +106,21 @@ module Hallon
     # @return [Player]
     def play(track = nil)
       load(track) unless track.nil?
-      tap { Spotify.session_player_play(@pointer, true) }
+      tap { Spotify.session_player_play(pointer, true) }
     end
 
     # Pause playback of a Track.
     #
     # @return [Player]
     def pause
-      tap { Spotify.session_player_play(@pointer, false) }
+      tap { Spotify.session_player_play(pointer, false) }
     end
 
     # Stop playing current track and unload it.
     #
     # @return [Player]
     def stop
-      tap { Spotify.session_player_unload(@pointer) }
+      tap { Spotify.session_player_unload(pointer) }
     end
 
     # Seek to the desired position of the currently loaded Track.
@@ -124,7 +128,17 @@ module Hallon
     # @param [Numeric] seconds offset position in seconds
     # @return [Player]
     def seek(seconds)
-      tap { Spotify.session_player_seek(@pointer, seconds * 1000) }
+      tap { Spotify.session_player_seek(pointer, seconds * 1000) }
+    end
+
+    # @return [Boolean] true if libspotify is set to normalize audio volume.
+    def volume_normalization?
+      Spotify.session_get_volume_normalization(pointer)
+    end
+
+    # @param [Boolean] normalize_volume true if libspotify should normalize audio volume.
+    def volume_normalization=(normalize_volume)
+      Spotify.session_set_volume_normalization(pointer, !! normalize_volume)
     end
   end
 end

data/lib/hallon/playlist.rb

@@ -0,0 +1,291 @@
+# coding: utf-8
+module Hallon
+  # Playlists are playlists. They contain tracks and track information
+  # such as when tracks were added or by whom. They also contain some
+  # metadata such as their own name.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__playlist.html
+  class Playlist < Base
+    include Observable
+    extend Linkable
+
+    # Playlist::Track is a {Track} with additional information attached to it,
+    # that is specific to the playlist it was created from. The returned track
+    # is a snapshot of the information, so even if the underlying track moves,
+    # this Playlist::Track will still contain the same information.
+    #
+    # There is no way to refresh the information. You’ll have to retrieve the
+    # track again.
+    class Track < Hallon::Track
+      def initialize(playlist, index)
+        super Spotify.playlist_track!(playlist, index)
+
+        @index       = index
+        @create_time = Time.at Spotify.playlist_track_create_time(playlist, index)
+        @message     = Spotify.playlist_track_message(playlist, index)
+        @seen        = Spotify.playlist_track_seen(playlist, index)
+        @creator     = begin
+          creator = Spotify.playlist_track_creator!(playlist, index)
+          User.new(creator) unless creator.null?
+        end
+      end
+
+      # @note this value never changes, even if the original track is moved/removed
+      # @return [Integer] index this track was created with.
+      attr_reader :index
+
+      # @return [Time] time when track at {#index} was added to playlist.
+      def create_time
+        @create_time
+      end
+
+      # @return [User, nil] person who added track at {#index} to this playlist.
+      def creator
+        @creator
+      end
+
+      # @return [String] message attached to this track at {#index}.
+      def message
+        @message
+      end
+
+      # @see Playlist#seen
+      # @return [Boolean] true if track at {#index} has been seen.
+      def seen?
+        @seen
+      end
+    end
+
+    from_link :playlist do |pointer|
+      Spotify.playlist_create!(session.pointer, pointer)
+    end
+
+    to_link :from_playlist
+
+    # Construct a new Playlist, given a pointer.
+    #
+    # @param [String, Link, FFI::Pointer] link
+    def initialize(link)
+      callbacks = Spotify::PlaylistCallbacks.new(self, @sp_callbacks = {})
+      @pointer = to_pointer(link, :playlist)
+      Spotify.playlist_add_callbacks(pointer, callbacks, nil)
+    end
+
+    # @return [Boolean] true if the playlist is loaded
+    def loaded?
+      Spotify.playlist_is_loaded(pointer)
+    end
+
+    # @return [Boolean] true if the playlist is collaborative
+    def collaborative?
+      Spotify.playlist_is_collaborative(pointer)
+    end
+
+    # @param [Boolean] collaborative true to set the playlist to collaborative
+    def collaborative=(collaborative)
+      Spotify.playlist_set_collaborative(pointer, !!collaborative)
+    end
+
+    # @return [Boolean] true if playlist has pending changes
+    def pending?
+      Spotify.playlist_has_pending_changes(pointer)
+    end
+
+    # @return [Boolean] true if the playlist is in RAM
+    def in_ram?
+      Spotify.playlist_is_in_ram(session.pointer, pointer)
+    end
+
+    # @param [Boolean] in_ram true if you want to store the playlist in RAM
+    def in_ram=(in_ram)
+      Spotify.playlist_set_in_ram(session.pointer, pointer, !! in_ram)
+    end
+
+    # @return [Boolean] true if playlist is available offline (fully synced)
+    def available_offline?
+      offline_status == :yes
+    end
+
+    # @return [Boolean] true if playlist is currently syncing
+    def syncing?
+      offline_status == :downloading
+    end
+
+    # @return [Boolean] true if playlist is queued for offline syncing
+    def waiting?
+      offline_status == :waiting
+    end
+
+    # @return [Boolean] true if playlist is requested to be available offline
+    def offline_mode?
+      offline_status != :no
+    end
+
+    # @return [Symbol] one of :no, :yes, :downloading, :waiting
+    def offline_status
+      Spotify.playlist_get_offline_status(session.pointer, pointer)
+    end
+
+    # @param [Boolean] available_offline true if you want this playlist available offline
+    def offline_mode=(available_offline)
+      Spotify.playlist_set_offline_mode(session.pointer, pointer, !! available_offline)
+    end
+
+    # @return [String]
+    def name
+      Spotify.playlist_name(pointer)
+    end
+
+    # @note The name must not consist of only spaces and it must be shorter than 256 characters.
+    # @param [#to_s] name new name for playlist
+    # @raise [Error] if name could not be changed
+    def name=(name)
+      name = name.to_s.encode('UTF-8')
+
+      unless name.length < 256
+        raise ArgumentError, "name must be shorter than 256 characters (UTF-8)"
+      end
+
+      unless name =~ /[^ ]/u
+        raise ArgumentError, "name must not consist of only spaces"
+      end unless name.empty?
+
+      Error.maybe_raise(Spotify.playlist_rename(pointer, name))
+    end
+
+    # @return [User, nil]
+    def owner
+      user = Spotify.playlist_owner!(pointer)
+      User.new(user) unless user.null?
+    end
+
+    # @return [String]
+    def description
+      Spotify.playlist_get_description(pointer)
+    end
+
+    # @return [Image, nil]
+    def image
+      buffer = FFI::Buffer.alloc_out(20)
+      if Spotify.playlist_get_image(pointer, buffer)
+        Image.new buffer.read_bytes(20)
+      end
+    end
+
+    # @note this list might be shorter than {#total_subscribers}, as
+    #       libspotify does not store more than 500 subscriber names
+    # @return [Array<String>] list of canonical usernames
+    def subscribers
+      ptr    = Spotify.playlist_subscribers(pointer)
+      struct = Spotify::Subscribers.new(ptr)
+
+      if struct[:count].zero?
+        []
+      else
+        struct[:subscribers].map(&:read_string)
+      end
+    ensure
+      Spotify.playlist_subscribers_free(ptr)
+    end
+
+    # @return [Integer] total number of subscribers.
+    def total_subscribers
+      Spotify.playlist_num_subscribers(pointer)
+    end
+
+    # Ask libspotify to update subscriber information
+    #
+    # @return [Playlist]
+    def update_subscribers
+      Spotify.playlist_update_subscribers(session.pointer, pointer)
+    end
+
+    # @note only applicable if {#offline_status} is `:downloading`
+    # @return [Integer] percentage done of playlist offline sync
+    def sync_progress
+      Spotify.playlist_get_offline_download_completed(session.pointer, pointer)
+    end
+
+    # @param [Boolean] autolink_tracks if you want unplayable tracks to be linked to playable tracks (if possible)
+    def autolink_tracks=(autolink_tracks)
+      Spotify.playlist_set_autolink_tracks(pointer, !! autolink_tracks)
+    end
+
+    # @note Will be 0 unless {#loaded?}.
+    # @return [Integer] number of tracks in playlist
+    def size
+      Spotify.playlist_num_tracks(pointer)
+    end
+
+    # @example retrieve track at index 3
+    #   track = playlist.tracks[3]
+    #   puts track.name
+    #
+    # @return [Enumerable<Playlist::Track>] a list of playlist tracks.
+    def tracks
+      Enumerator.new(size) { |i| Playlist::Track.new(pointer, i) }
+    end
+
+    # Set seen status of the Playlist::Track at the given index.
+    #
+    # @see #tracks
+    # @raise [Error] if the operation could not be completed
+    # @param [Integer] index
+    # @param [Boolean] seen true if the track is now seen
+    # @return [Playlist::Track] track at the given index
+    def seen(index, seen)
+      error = Spotify.playlist_track_set_seen(pointer, index, !! seen)
+      Error.maybe_raise(error)
+      tracks[index]
+    end
+
+    # Add a list of tracks to the playlist starting at given position.
+    #
+    # @param [Integer] index starting index to add tracks from (between 0..{#size})
+    # @param [Track, Array<Track>] tracks
+    # @return [Playlist]
+    # @raise [Hallon::Error] if the operation failed
+    def insert(index = size, tracks)
+      tracks = Array(tracks).map(&:pointer)
+      tracks_ary = FFI::MemoryPointer.new(:pointer, tracks.size)
+      tracks_ary.write_array_of_pointer(tracks)
+
+      tap do
+        error = Spotify.playlist_add_tracks(pointer, tracks_ary, tracks.size, index, session.pointer)
+        Error.maybe_raise(error)
+      end
+    end
+
+    # Remove tracks at given indices.
+    #
+    # @param [Integer, ...] indices
+    # @return [Playlist]
+    # @raise [Error] if the operation failed
+    def remove(*indices)
+      indices_ary = FFI::MemoryPointer.new(:int, indices.size)
+      indices_ary.write_array_of_int(indices)
+
+      tap do
+        error = Spotify.playlist_remove_tracks(pointer, indices_ary, indices.size)
+        Error.maybe_raise(error)
+      end
+    end
+
+    # Move tracks at given indices to given index.
+    #
+    # @param [Integer] destination index to move tracks to
+    # @param [Integer, Array<Integer>] indices
+    # @return [Playlist]
+    # @raise [Error] if the operation failed
+    def move(destination, indices)
+      indices     = Array(indices)
+      indices_ary = FFI::MemoryPointer.new(:int, indices.size)
+      indices_ary.write_array_of_int(indices)
+
+      tap do
+        error = Spotify.playlist_reorder_tracks(pointer, indices_ary, indices.size, destination)
+        Error.maybe_raise(error)
+      end
+    end
+  end
+end