hallon 0.18.0 → 0.18.1

data/.rspec

@@ -1,5 +1,5 @@
 --color
--fs
+-fp
 -Ilib
 -Ispec
 --require spec_helper

data/CHANGELOG.md

@@ -4,6 +4,16 @@ Hallon’s Changelog
 [HEAD][]
 ------------------
 
+[v0.18.1][]
+------------------
+Hallon now supports spotify ~> 12.3.0. As a result, you no longer need to manually install
+libspotify except in cases where the gem does not exist for your platform. I’ve tried to be
+as liberal as possible in the gem platform choice, so manual installation should be a rare
+occurrence.
+
+This release mostly brings an internal change, and should not affect the public API, and as
+such only the patch version has been increased.
+
 [v0.18.0][]
 ------------------
 This issue is to plug a bug of libspotify on Linux (see issue #125). The reason that
@@ -396,4 +406,5 @@ easier to handle.
 [v0.16.0]: https://github.com/Burgestrand/Hallon/compare/v0.15.0...v0.16.0
 [v0.17.0]: https://github.com/Burgestrand/Hallon/compare/v0.16.0...v0.17.0
 [v0.18.0]: https://github.com/Burgestrand/Hallon/compare/v0.17.0...v0.18.0
-[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.17.0...HEAD
+[v0.18.1]: https://github.com/Burgestrand/Hallon/compare/v0.18.0...v0.18.1
+[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.18.1...HEAD

data/README.markdown

@@ -15,9 +15,7 @@ Before you start using Hallon you’ll need to complete the following steps.
 2. [Download your application key from developer.spotify.com](https://developer.spotify.com/en/libspotify/application-key/),
    and place it in a known location. You’ll have the option of downloading it either in **binary** or c-code. You want the
    **binary** one. If you do not have an application key already, you will be asked to create one.
-3. Install libspotify. Hallon always aims to support to most recent version, which is currently **v12.1.51**. Older
-   versions are not supported. For help installing libspotify, please see the wiki on [How to install libspotify][].
-4. Once the above are done, you are ready to try out Hallon.
+3. Once the above are done, you are ready to try out Hallon.
 
 ### Using Hallon
 
@@ -160,7 +158,11 @@ Finally, here are some important notes
 [Fork](http://help.github.com/forking/) Hallon, write tests for everything you do (so I don’t break your stuff during my own development) and send a pull request. If you modify existing files, please adhere to the coding standard surrounding your code.
 
 ### Hallon uses [semantic versioning](http://semver.org) as of v0.0.0
-As long as Hallon stays at major version 0, no guarantees of backwards-compatibility are made. `CHANGELOG.md` will be kept up to date with the different versions.
+As long as Hallon stays at major version 0 its API should be considered experimental. I expect it to change a lot to version v1.0.0.
+
+Hallon is not without version policy, however. As of version **v0.18.0** I aim to only increase the minor version when backwards-incompatible
+changes are made. Therefore, it should be safe to upgrade between minor versions, i.e. specify version constraints with the patch version as
+the variable version: `hallon ~> v0.18.0`.
 
 ### Hallon only supports one session per process
 You can only keep one session with Spotify alive at a time within the same process, due to a limitation of libspotify.
@@ -168,6 +170,12 @@ You can only keep one session with Spotify alive at a time within the same proce
 ### When forking, you need to be extra careful
 If you fork, you need to instantiate the session within the process you plan to use Hallon in. You want to use Hallon in the parent? Create the session in the parent. You want to use it in the child? Create the session in the child! This is a limitation of libspotify itself.
 
+### Hallon and platforms
+Hallon aims to support the available platforms of the Spotify gem, which in turn depends somewhat on the platforms that libspotify support. As of current, Hallon officially supports Mac OS and Linux distributions that libspotify supports. Windows support is possible, but is yet to have been needed.
+
+### Having trouble with libspotify missing?
+If so, it may be the case that your platform is not supported by the [libspotify gem](http://rubygems.org/gems/libspotify). Hallon’s wiki has an article on [How to install libspotify](https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify) for you. However, please also [report an issue on the libspotify gem](https://github.com/Burgestrand/libspotify/issues), I’d appreciate it, thank you!
+
 Credits
 -------
 - Per Reimers, cracking synchronization bugs with me deep in the night (4 AM), thanks. :)
@@ -180,7 +188,7 @@ License
 Hallon is licensed under a 2-clause (Simplified) BSD license. More information can be found in the `LICENSE.txt` file.
 
 [Raspberry]:        http://images.google.com/search?q=raspberry&tbm=isch
-[Spotify for Ruby]: https://github.com/Burgestrand/libspotify-ruby
+[Spotify for Ruby]: https://github.com/Burgestrand/spotify
 [spotify gem]:      https://rubygems.org/gems/spotify
 [libspotify]:       http://developer.spotify.com/en/libspotify/overview/
 [Greenstripes]:     http://github.com/sarnesjo/greenstripes

data/Rakefile

@@ -33,36 +33,6 @@ task 'spotify:coverage' do
 
   require 'pry'
   require 'set'
-
-  module Spotify
-    # Wrapped functions return pointers that are auto-GC’d by Ruby,
-    # so we ignore add_ref and release for these methods; but since
-    # we don’t know their type by mere name, we must resort to this
-    # hack to do it automatically (because we can).
-    class << self
-      def lookup_return_value(name)
-        @function_to_return_type[name.to_s]
-      end
-
-      def define_singleton_method(name, &block)
-        return_type = block.binding.eval <<-CODE
-          begin
-            return_type if __method__ == :wrap_function
-          rescue NameError
-            nil
-          end
-        CODE
-
-        if return_type
-          @function_to_return_type ||= {}
-          @function_to_return_type[name.to_s] = return_type
-        end
-
-        super
-      end
-    end
-  end
-
   require 'spotify'
 
   begin
@@ -72,19 +42,20 @@ task 'spotify:coverage' do
     abort
   end
 
-  methods = Spotify.methods(false).map(&:to_s)
-  auto_gc = Set.new(methods.grep(/!\z/).select { |m| Spotify.lookup_return_value(m) })
-  auto_err = Set.new(methods.grep(/!\z/)).difference(auto_gc)
+  methods = Spotify.methods(false).map(&:to_s).reject { |x| x =~ /_add_ref|_release/ }
   covered = Set.new(methods)
-  warning = []
+  auto_error = Set.new(methods.select { |x| x =~ /!/ })
+  inexisting = []
   ignored = [
     'attach_function',  # spotify overloads this
     'session_release',  # segfaults on libspotify <= 9, and sometimes deadlocks on libspotify <= v12
-    'session_release!', # …
     'session_userdata', # wont support this
+    'build_id',         # no use for it
+    'platform',         # not necessary yet
+    'mac?',             # has no use for it
+    'search_playlist',  # does not GC convention, dangerous to use!
     'error_message',    # supported by Hallon::Error.explain
     'link_as_track',    # using link_as_track_and_offset instead
-    'link_as_track!',   # using link_as_track_and_offset! instead
     'wrap_function',    # not a spotify function
     'lookup_return_value', # custom method
     'define_singleton_method', # overloaded by us
@@ -95,58 +66,36 @@ task 'spotify:coverage' do
   # Handlers for different AST nodes
   printer  = proc { |*args| p args }
   silencer = proc { }
+  dsl_method = proc { |recv, meth, (_, name)| name }
   handlers = Hash.new(Hash.new(silencer))
 
   # Direct calls
   handlers[Sexp.new(:const, :Spotify)] = Hash.new(proc do |_, meth, _|
-    if auto_gc.include?("#{meth}!")
-      warning << [$file, meth]
-    end
+    meth &&= meth.to_s
 
-    result = [meth]
-
-    auto_err_lookup = meth.to_s.delete('!') + '!' # just one !
-
-    # if it has auto-error, we account for both versions, just assume
-    # we are doing the right thing here
-    if auto_err.member?(auto_err_lookup)
-      result << auto_err_lookup
-      result << auto_err_lookup.delete('!')
-      result.uniq!
-    end
-
-    if meth =~ /(.+)!\z/
-      # if it’s auto-GC’d, we can also account for _release and _add_ref
-      if (return_type = Spotify.lookup_return_value(meth))
-        result << $1
-        result << "#{return_type}_release"
-        result << "#{return_type}_add_ref"
-        result << "#{return_type}_release!"
-        result << "#{return_type}_add_ref!"
+    [meth].tap do |result|
+      if meth =~ /!/ && auto_error.include?(meth)
+        result << meth.delete("!")
+      else
+        result << "#{meth}!"
       end
-    end
 
-    result
+      inexisting << meth unless Spotify.respond_to?(meth)
+    end
   end)
 
   # DSL Methods
   no_receiver = handlers[nil] = Hash.new(silencer)
   no_receiver[:from_link] = no_receiver[:to_link] = proc do |recv, meth, (_, name)|
     prefix = meth == :to_link ? "link_create" : "link"
-    method = "%s_%s" % [prefix, name]
-    [method, "#{method}!"]
+    "%s_%s" % [prefix, name]
   end
 
   # Hallon::Enumerator
-  no_receiver[:size] = proc do |recv, meth, (_, name)|
-    name
-  end
+  no_receiver[:size] = dsl_method
 
   # Hallon::Enumerator
-  no_receiver[:item] = proc do |recv, meth, (_, name)|
-    method = name.to_s
-    [method.delete("!"), method]
-  end
+  no_receiver[:item] = dsl_method
 
   fails = {}
   FileList['lib/**/*.rb'].each do |file|
@@ -186,10 +135,10 @@ task 'spotify:coverage' do
     puts
   end
 
-  unless warning.empty?
-    puts "Warnings (use auto-gc methods instead!):"
-    warning.each do |file, method|
-      puts "  #{file}: #{method}"
+  unless inexisting.empty?
+    puts "Non-existing methods (but used; remove!):"
+    inexisting.each do |fail|
+      puts "  #{fail}"
     end
     puts
   end

data/examples/example_support.rb

@@ -9,6 +9,8 @@
 # If at any point you feel lost, do not hesitate to consult with my superiors. You may
 # find them at https://github.com/Burgestrand/Hallon. Thank you!
 
+$stdout.sync = true
+
 # First, I need the power to ask you questions. You need not care much about this particular
 # piece of me; only keep in mind that it should help keep the rest of me less cluttered.
 def prompt(string, options = {})

data/hallon.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = '>= 1.9'
 
   gem.add_dependency 'ref', '~> 1.0'
-  gem.add_dependency 'spotify', '~> 12.2.0'
+  gem.add_dependency 'spotify', '~> 12.3.0'
   gem.add_development_dependency 'rake', '~> 0.8'
   gem.add_development_dependency 'rspec', '~> 2'
   gem.add_development_dependency 'yard'

data/lib/hallon.rb

@@ -49,12 +49,7 @@ Thread.abort_on_exception = true
 # be looking for the documentation on {Hallon::Session}.
 module Hallon
   # @see Spotify::API_VERSION
-  API_VERSION = Spotify::API_VERSION
-
-  # Spotify API build.
-  #
-  # @see Spotify#api_build
-  API_BUILD = Spotify.build_id
+  API_VERSION = Spotify::API_VERSION.to_i
 
   # A regex that matches all Spotify URIs
   #

data/lib/hallon/album.rb

@@ -41,9 +41,9 @@ module Hallon
     #   link = Hallon::Link.new("spotify:album:6TECAywzyJGh0kwxfeBgGc")
     #   album = Hallon::Album.new(link)
     #
-    # @param [String, Link, Spotify::Pointer] link
+    # @param [String, Link, Spotify::Album] link
     def initialize(link)
-      @pointer = to_pointer(link, :album)
+      @pointer = to_pointer(link, Spotify::Album)
     end
 
     # @return [String] name of the album.
@@ -74,7 +74,7 @@ module Hallon
 
     # @return [Artist, nil] album artist.
     def artist
-      artist = Spotify.album_artist!(pointer)
+      artist = Spotify.album_artist(pointer)
       Artist.from(artist)
     end
 
@@ -90,7 +90,7 @@ module Hallon
     # @param [Symbol] size (see {Image.sizes})
     # @return [Link, nil] album cover as a spotify URI.
     def cover_link(size = :normal)
-      cover = Spotify.link_create_from_album_cover!(pointer, size)
+      cover = Spotify.link_create_from_album_cover(pointer, size)
       Link.from(cover)
     end
 

data/lib/hallon/album_browse.rb

@@ -20,7 +20,7 @@ module Hallon
       size :albumbrowse_num_tracks
 
       # @return [Track, nil]
-      item :albumbrowse_track! do |track|
+      item :albumbrowse_track do |track|
         Track.from(track)
       end
     end
@@ -31,18 +31,18 @@ module Hallon
     # Creates an AlbumBrowse instance from an Album or an Album pointer.
     #
     # @note Also {Album#browse} to browse an Album.
-    # @param [Album, Spotify::Pointer] album
+    # @param [Album, Spotify::Album] album
     def initialize(album)
       pointer = album
       pointer = pointer.pointer if pointer.respond_to?(:pointer)
 
-      unless Spotify::Pointer.typechecks?(pointer, :album)
+      unless pointer.is_a?(Spotify::Album)
         given = pointer.respond_to?(:type) ? pointer.type : pointer.inspect
         raise TypeError, "expected album pointer, was given #{given}"
       end
 
       subscribe_for_callbacks do |callback|
-        @pointer = Spotify.albumbrowse_create!(session.pointer, pointer, callback, nil)
+        @pointer = Spotify.albumbrowse_create(session.pointer, pointer, callback, nil)
       end
 
       raise FFI::NullPointerError, "album browsing failed" if @pointer.null?
@@ -66,13 +66,13 @@ module Hallon
 
     # @return [Artist, nil] artist performing this album.
     def artist
-      artist = Spotify.albumbrowse_artist!(pointer)
+      artist = Spotify.albumbrowse_artist(pointer)
       Artist.from(artist)
     end
 
     # @return [Album, nil] album this object is browsing.
     def album
-      album = Spotify.albumbrowse_album!(pointer)
+      album = Spotify.albumbrowse_album(pointer)
       Album.from(album)
     end
 

data/lib/hallon/artist.rb

@@ -28,9 +28,9 @@ module Hallon
     #   link = Hallon::Link.new("spotify:artist:6uSKeCyQEhvPC2NODgiqFE")
     #   artist = Hallon::Artist.new(link)
     #
-    # @param [String, Link, FFI::Pointer] link
+    # @param [String, Link, Spotify::Artist] link
     def initialize(link)
-      @pointer = to_pointer(link, :artist)
+      @pointer = to_pointer(link, Spotify::Artist)
     end
 
     # @return [String] name of the artist.
@@ -55,7 +55,7 @@ module Hallon
     # @param [Symbol] size (see {Image.sizes})
     # @return [Link, nil] artist portrait as a Link.
     def portrait_link(size = :normal)
-      portrait = Spotify.link_create_from_artist_portrait!(pointer, size)
+      portrait = Spotify.link_create_from_artist_portrait(pointer, size)
       Link.from(portrait)
     end
 

data/lib/hallon/artist_browse.rb

@@ -21,7 +21,7 @@ module Hallon
       size :artistbrowse_num_portraits
 
       # @return [Link, nil]
-      item :link_create_from_artistbrowse_portrait! do |portrait|
+      item :link_create_from_artistbrowse_portrait do |portrait|
         Link.from(portrait)
       end
     end
@@ -31,7 +31,7 @@ module Hallon
       size :artistbrowse_num_tracks
 
       # @return [Track, nil]
-      item :artistbrowse_track! do |track|
+      item :artistbrowse_track do |track|
         Track.from(track)
       end
     end
@@ -41,7 +41,7 @@ module Hallon
       size :artistbrowse_num_albums
 
       # @return [Album, nil]
-      item :artistbrowse_album! do |album|
+      item :artistbrowse_album do |album|
         Album.from(album)
       end
     end
@@ -51,7 +51,7 @@ module Hallon
       size :artistbrowse_num_similar_artists
 
       # @return [Artist, nil]
-      item :artistbrowse_similar_artist! do |artist|
+      item :artistbrowse_similar_artist do |artist|
         Artist.from(artist)
       end
     end
@@ -61,7 +61,7 @@ module Hallon
       size :artistbrowse_num_tophit_tracks
 
       # @return [Track, nil]
-      item :artistbrowse_tophit_track! do |track|
+      item :artistbrowse_tophit_track do |track|
         Track.from(track)
       end
     end
@@ -77,19 +77,19 @@ module Hallon
     # Creates an ArtistBrowse instance from an Artist or an Artist pointer.
     #
     # @note Also use {Artist#browse} to browse an Artist.
-    # @param [Artist, Spotify::Pointer] artist
+    # @param [Artist, Spotify::Artist] artist
     # @param [Symbol] type (see {.types})
     def initialize(artist, type = :full)
       pointer = artist
       pointer = pointer.pointer if pointer.respond_to?(:pointer)
 
-      unless Spotify::Pointer.typechecks?(pointer, :artist)
+      unless pointer.is_a?(Spotify::Artist)
         given = pointer.respond_to?(:type) ? pointer.type : pointer.inspect
         raise TypeError, "expected artist pointer, was given #{given}"
       end
 
       subscribe_for_callbacks do |callback|
-        @pointer = Spotify.artistbrowse_create!(session.pointer, pointer, type, callback, nil)
+        @pointer = Spotify.artistbrowse_create(session.pointer, pointer, type, callback, nil)
       end
 
       raise FFI::NullPointerError, "artist browsing failed" if @pointer.null?
@@ -108,7 +108,7 @@ module Hallon
 
     # @return [Artist, nil] artist this browser is browsing.
     def artist
-      artist = Spotify.artistbrowse_artist!(pointer)
+      artist = Spotify.artistbrowse_artist(pointer)
       Artist.from(artist)
     end
 

data/lib/hallon/audio_queue.rb

@@ -40,7 +40,8 @@ module Hallon
     # @param [Integer] max_size how many frames
     def initialize(max_size)
       @max_size = max_size
-      @frames  = []
+      @frames   = []
+      @format   = nil
 
       @frames.extend(MonitorMixin)
       @condvar  = @frames.new_cond

data/lib/hallon/base.rb

@@ -57,8 +57,8 @@ module Hallon
       #   @method from_link
       #   @scope  instance
       #   @visibility private
-      #   @param  [String, Hallon::Link, Spotify::Pointer] link
-      #   @return [Spotify::Pointer] pointer representation of given link.
+      #   @param  [String, Hallon::Link, Spotify::Link] link
+      #   @return [Spotify::Link] 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
@@ -73,18 +73,18 @@ module Hallon
 
       # Convert a given object to a pointer by best of ability.
       #
-      # @param [Spotify::Pointer, String, Link] resource
-      # @return [Spotify::Pointer]
+      # @param [Spotify::ManagedPointer, String, Link] resource
+      # @return [Spotify::ManagedPointer]
       # @raise [TypeError] when the pointer is of the wrong type
       # @raise [ArgumentError] 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"
+        if resource.is_a?(FFI::Pointer) and not resource.is_a?(Spotify::ManagedPointer)
+          raise TypeError, "Hallon does not support raw FFI::Pointers, wrap it in a Spotify::ManagedPointer"
         end
 
-        pointer = if Spotify::Pointer.typechecks?(resource, type)
+        pointer = if resource.is_a?(type)
           resource
-        elsif is_linkable? and Spotify::Pointer.typechecks?(resource, :link)
+        elsif is_linkable? and resource.is_a?(Spotify::Link)
           from_link(resource, *args)
         elsif is_linkable? and Link.valid?(resource)
           from_link(resource, *args)
@@ -94,8 +94,8 @@ module Hallon
 
         if pointer.nil? or pointer.null?
           raise ArgumentError, "#{resource.inspect} could not be converted to a spotify #{type} pointer"
-        elsif not Spotify::Pointer.typechecks?(pointer, type)
-          raise TypeError, "“#{resource}” is of type #{resource.type}, #{type} expected"
+        elsif not pointer.is_a?(type)
+          raise TypeError, "“#{resource}” is a #{resource.class}, #{type} expected"
         else
           pointer
         end