spotify 12.2.0 → 12.3.0

data/.gitignore

@@ -4,4 +4,6 @@
 Gemfile.lock
 pkg/*
 doc/
-.yardoc
+.yardoc
+.rbx
+*.rbc

data/.rspec

@@ -0,0 +1,5 @@
+-fp
+-Ilib
+-I.
+--colour
+--require spec/spec_helper

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+[v12.3.0][]
+-----------
+Lots of internal and external changes. You could almost say it’s a rewrite.
+
+- [0ee03487a] added a Spotify::ManagedPointer (new Spotify::AutoPointer) for every object
+- [0ee03487a] all functions now always return auto pointers
+- [a88920c22] it’s now possible to create a Spotify::Subscriber with a count
+- [aa26b1ed2] have all callbacks retain their pointer
+- [a72469b04] use new libspotify gem for attaching libspotify dynamic library
+- renamed the repository from libspotify-ruby to spotify
+- [345b47472] all structs can now be initialized with a hash
+- [e54f1c806] SessionConfig now accepts string as application key
+- [37f1f883d] Added Spotify.try(method), and removed bang-calling notation
+- [6e51b6c4e] Added a mutex around every Spotify API call
+
+I might’ve missed something. Read the commits for the nitty gritty.
+
 [v12.2.0][]
 -----------
 - fix SessionConfig missing ca_certs_filename struct field on Linux
@@ -130,30 +147,31 @@ v0.0.0
 ------
 - release to register rubygems.org name
 
-[v12.2.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.3...v12.2.0
-[v12.0.3]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.2...v12.0.3
-[v12.0.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.1...v12.0.2
-[v12.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.0...v12.0.1
-[v12.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v11.0.2...v12.0.0
-[v11.0.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v11.0.1...v11.0.2
-[v11.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v11.0.0...v11.0.1
-[v11.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.3.0...v11.0.0
-[v10.3.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.2.2...v10.3.0
-[v10.2.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.2.1...v10.2.2
-[v10.2.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.2.0...v10.2.1
-[v10.2.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.1.1...v10.2.0
-[v10.1.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.1.0...v10.1.1
-[v10.1.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v10.0.0...v10.1.0
-[v10.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v9.1.0...v10.0.0
-[v9.1.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v9.0.1...v9.1.0
-[v9.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v9.0.0...v9.0.1
-[v9.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v8.0.5...v9.0.0
-[v8.0.5]: https://github.com/Burgestrand/libspotify-ruby/compare/v8.0.2...v8.0.5
-[v8.0.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v8.0.1...v8.0.2
-[v8.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v8.0.0...v8.0.1
-[v8.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v7.0.4...v8.0.0
-[v7.0.4]: https://github.com/Burgestrand/libspotify-ruby/compare/v7.0.3...v7.0.4
-[v7.0.3]: https://github.com/Burgestrand/libspotify-ruby/compare/v7.0.2...v7.0.3
-[v7.0.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v7.0.1...v7.0.2
-[v7.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v7.0.0...v7.0.1
-[v7.0.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v0.0.0...v7.0.0
+[v12.3.0]: https://github.com/Burgestrand/spotify/compare/v12.2.0...v12.3.0
+[v12.2.0]: https://github.com/Burgestrand/spotify/compare/v12.0.3...v12.2.0
+[v12.0.3]: https://github.com/Burgestrand/spotify/compare/v12.0.2...v12.0.3
+[v12.0.2]: https://github.com/Burgestrand/spotify/compare/v12.0.1...v12.0.2
+[v12.0.1]: https://github.com/Burgestrand/spotify/compare/v12.0.0...v12.0.1
+[v12.0.0]: https://github.com/Burgestrand/spotify/compare/v11.0.2...v12.0.0
+[v11.0.2]: https://github.com/Burgestrand/spotify/compare/v11.0.1...v11.0.2
+[v11.0.1]: https://github.com/Burgestrand/spotify/compare/v11.0.0...v11.0.1
+[v11.0.0]: https://github.com/Burgestrand/spotify/compare/v10.3.0...v11.0.0
+[v10.3.0]: https://github.com/Burgestrand/spotify/compare/v10.2.2...v10.3.0
+[v10.2.2]: https://github.com/Burgestrand/spotify/compare/v10.2.1...v10.2.2
+[v10.2.1]: https://github.com/Burgestrand/spotify/compare/v10.2.0...v10.2.1
+[v10.2.0]: https://github.com/Burgestrand/spotify/compare/v10.1.1...v10.2.0
+[v10.1.1]: https://github.com/Burgestrand/spotify/compare/v10.1.0...v10.1.1
+[v10.1.0]: https://github.com/Burgestrand/spotify/compare/v10.0.0...v10.1.0
+[v10.0.0]: https://github.com/Burgestrand/spotify/compare/v9.1.0...v10.0.0
+[v9.1.0]: https://github.com/Burgestrand/spotify/compare/v9.0.1...v9.1.0
+[v9.0.1]: https://github.com/Burgestrand/spotify/compare/v9.0.0...v9.0.1
+[v9.0.0]: https://github.com/Burgestrand/spotify/compare/v8.0.5...v9.0.0
+[v8.0.5]: https://github.com/Burgestrand/spotify/compare/v8.0.2...v8.0.5
+[v8.0.2]: https://github.com/Burgestrand/spotify/compare/v8.0.1...v8.0.2
+[v8.0.1]: https://github.com/Burgestrand/spotify/compare/v8.0.0...v8.0.1
+[v8.0.0]: https://github.com/Burgestrand/spotify/compare/v7.0.4...v8.0.0
+[v7.0.4]: https://github.com/Burgestrand/spotify/compare/v7.0.3...v7.0.4
+[v7.0.3]: https://github.com/Burgestrand/spotify/compare/v7.0.2...v7.0.3
+[v7.0.2]: https://github.com/Burgestrand/spotify/compare/v7.0.1...v7.0.2
+[v7.0.1]: https://github.com/Burgestrand/spotify/compare/v7.0.0...v7.0.1
+[v7.0.0]: https://github.com/Burgestrand/spotify/compare/v0.0.0...v7.0.0

data/Gemfile

@@ -1,2 +1,6 @@
 source :rubygems
 gemspec
+
+gem 'pry'
+gem 'yard'
+gem 'redcarpet'

data/README.markdown

@@ -1,39 +1,72 @@
-Ruby FFI bindings for [libspotify][]
-====================================
+Ruby bindings for [libspotify][] ([![Build Status](https://secure.travis-ci.org/Burgestrand/spotify.png?branch=master)](http://travis-ci.org/Burgestrand/spotify))
+================================
 
     The libspotify C API package allows third party developers to write
     applications that utilize the Spotify music streaming service.
 
-[Spotify][] is a really nice music streaming service, and being able to interact with it in an API is awesome. However, because libspotify is a C library, writing applications with it is cumbersome and error-prone compared to doing it in Ruby. As I found myself needing to do this one day, knowing I’d rather not be writing it in C, this gem was born.
+[Spotify][] is a really nice music streaming service, and being able to interact
+with it in an API is awesome. libspotify itself is however written in C, making
+it unavailable or cumbersome to use for many developers.
 
-Spotify, the gem, is a thin layer of Ruby atop the [libspotify][] C library. It allows developers to use libspotify without writing a line of C, thanks to [Ruby FFI](https://rubygems.org/gems/ffi). Do note that there is no sugar-coating, and no attempts of abstraction will be made.
+This project aims to allow Ruby developers access to all of the libspotify C API,
+without needing to reach down to C. However, to use this library to it’s full extent
+you will need to learn how to use the Ruby FFI API.
 
-You want easy-to-use Ruby bindings for libspotify?
+The Spotify gem has:
+
+- [100% API coverage][], including callback support. You’ll be able to use any function from the libspotify library.
+- [Automatic garbage collection][]. Piggybacking on Ruby’s GC to manage pointer lifecycle.
+- [Parallell function call protection][]. libspotify is not thread-safe, but Spotify protects you.
+- [Type conversion][]. Special pointers for every Spotify type.
+
+[100% API coverage]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/API
+[Automatic garbage collection]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/ManagedPointer
+[Parallell function call protection]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify#method_missing-class_method
+[Type conversion]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/ManagedPointer
+
+The Spotify gem is aimed at experienced developers
 --------------------------------------------------
-Then you should check out [Hallon][]! While libspotify-ruby is just the simplest bindings to libspotify possible, Hallon works really hard to make libspotify a joy to use in Ruby.
+As the raw libspotify API is exposed, the Spotify gem is best coupled with a supporting
+library. This library would take a more focused approach to which kind of applications
+you can write using it. The Spotify gem itself, however, has very few opinions.
 
-Finally, if you, for some reason, are having trouble deciding if you should use libspotify-ruby or Hallon, you should probably use Hallon.
+Known supporting libraries:
 
-(anecdotal note: this code base was previously a part of Hallon, but I decided to extract it and make a gem out of it)
+- [Hallon](https://github.com/Burgestrand/Hallon), the original. Currently Hallon is simply
+  a more convenient Spotify gem, written on top of the Spotify gem. It is diverging from its
+  previous path, now towards a more focused and opinionated framework. If you’re unsure of
+  what to use, start with the Hallon gem!
 
-[libspotify]: http://developer.spotify.com/en/libspotify/overview/
-[Spotify]: https://www.spotify.com/
-[Hallon]: https://github.com/Burgestrand/Hallon
+Do not let this stop you! Despite my harsh words the Spotify API is well suited for experimentation,
+and it can be awfully fun to play with. If you need any assitance feel free to post a message
+on the mailing list: [ruby-hallon@googlegroups.com][] (<https://groups.google.com/d/forum/ruby-hallon>).
+
+Manually installing libspotify
+------------------------------
+By default, Spotify uses [the libspotify gem](https://rubygems.org/gems/libspotify) which means you do
+not need to install libspotify yourself. However, if your platform is not supported by the libspotify
+gem you will need to install libspotify yourself.
+
+Please note, that if your platform is not supported by the libspotify gem I’d very much appreciate it
+if you could create an issue on [libspotify gem issue tracker](https://github.com/Burgestrand/libspotify/issues)
+so I can fix the build for your platform.
 
-Need help installing libspotify?
---------------------------------
-You’re in luck! I’ve got you covered in Hallon’s wiki: [How to install libspotify](https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify)!
+While you’re waiting for the issue to resolve you could install libspotify manually. I’ve provided
+instructions on how to do this in Hallon’s wiki: [How to install libspotify](https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify)!
 
 A note about versioning scheme
 ------------------------------
 Given a version `X.Y.Z`, each segment corresponds to:
 
-- X reflects supported libspotify version (12.1.45 => 12)
-- Y is increased **only** on non-backwards-compatible bug fixes or feature additions
-- Z is increased on backwards-compatible bug fixes or feature additions
-
-When X increases (support for new libspotify versions) there are **no guarantees** of backwards-compatibility.
+- X reflects supported libspotify version (12.1.45 => 12). There are __no guarantees__ of backwards-compatibility!
+- Y(major).Z(minor) follows [semantic versioning (semver.org)][]. Y is for backwards-**incompatible** changes, Z is for backwards-**compatible** changes.
 
 License
 -------
 X11 license, see the LICENSE document for details.
+
+[semantic versioning (semver.org)]: http://semver.org/
+[ruby-hallon@googlegroups.com]: mailto:ruby-hallon@googlegroups.com
+[libspotify]: http://developer.spotify.com/en/libspotify/overview/
+[Spotify]: https://www.spotify.com/
+[Hallon]: https://github.com/Burgestrand/Hallon

data/Rakefile

@@ -5,9 +5,20 @@ rescue LoadError
   # do not require bundler rake tasks
 end
 
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new('yard:doc') do |task|
+    task.options = ['--no-stats']
+  end
+
+  task 'yard:stats' do
+    YARD::CLI::Stats.run('--list-undoc')
+  end
 
-require 'yard'
-YARD::Rake::YardocTask.new
+  task :yard => ['yard:doc', 'yard:stats']
+rescue LoadError
+  puts "WARN: YARD not available. You may install documentation dependencies via bundler."
+end
 
 desc "re-generate spec/api.h.xml"
 task :gen do
@@ -18,14 +29,12 @@ task :console do
   exec "irb", "-Ilib", "-rspotify"
 end
 
-require 'rake/testtask'
-Rake::TestTask.new(:test_mac) do |spec|
-  spec.pattern = 'spec/*_spec.rb'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:test_mac) do |spec|
   spec.ruby_opts = ['-r ./spec/mac-platform']
 end
 
-Rake::TestTask.new(:test_linux) do |spec|
-  spec.pattern = 'spec/*_spec.rb'
+RSpec::Core::RakeTask.new(:test_linux) do |spec|
   spec.ruby_opts = ['-r ./spec/linux-platform']
 end
 

data/lib/spotify.rb

@@ -1,11 +1,112 @@
-# coding: utf-8
-require 'spotify/version'
+# encoding: utf-8
 require 'ffi'
+require 'libspotify'
+require 'monitor'
+
+# Spotify module allows you to place calls against the Spotify::API.
+#
+# @see method_missing method_missing on calling the API
+# @see Spotify::API Spotify::API on available libspotify methods
+# @see http://developer.spotify.com/en/libspotify/docs/ official libspotify documentation
+module Spotify
+  # API is the class which has all libspotify functions attached.
+  #
+  # All functions are attached as both instance methods and class methods, mainly
+  # because that’s how FFI works it’s magic with attach_function. However, as this
+  # is a class it allows to be instantiated.
+  #
+  # @note The API is private because this class is an implementation detail.
+  #
+  # @note You should never call any Spotify::API.method() directly, but instead
+  #       you should call them via Spotify.method(). libspotify is not thread-safe,
+  #       but it is documented to be okay to call the API from multiple threads *if*
+  #       you only call one function at a time, which is ensured by the lock in the
+  #       Spotify module.
+  #
+  # @api private
+  class API
+    extend FFI::Library
+
+    begin
+      ffi_lib [LIBSPOTIFY_BIN, 'libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
+    rescue LoadError
+      puts <<-ERROR.gsub(/^ */, '')
+        Failed to load the `libspotify` library. It is possible that the libspotify gem
+        does not exist for your platform, in which case you’ll need to install it manually.
+
+        For manual installation instructions, please see:
+          https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify
+      ERROR
+      raise
+    end
+  end
 
-require 'spotify/types/pointer'
-require 'spotify/types/utf8_string'
-require 'spotify/types/image_id'
+  @__api__ = Spotify::API
+  @__api__.extend(MonitorMixin)
 
-require 'spotify/functions'
-require 'spotify/gc_wrappers'
-require 'spotify/error_wrappers'
+  class << self
+    # Like send, but raises an error if the method returns a non-OK error.
+    #
+    # @example calling a method that returns an error
+    #   Spotify.relogin(session) # => :invalid_indata
+    #   Spotify.try(:relogin, session) # => raises Spotify::Error
+    #
+    # @note Works for non-error returning methods as well, it just does
+    #       not do anything interesting.
+    #
+    # @param [#to_s] name
+    # @param args
+    # @raise [Spotify::Error] if an error other than :ok is returned
+    def try(name, *args, &block)
+      public_send(name, *args, &block).tap do |error|
+        error, symbol = Spotify::Error.disambiguate(error)
+        next if symbol.nil?
+        next if symbol == :ok
+        raise Error.new(symbol)
+      end
+    end
+
+    # Asks the underlying Spotify API if it responds to `name`.
+    #
+    # @example
+    #   Spotify.respond_to?(:error_message) # => true
+    #
+    # @example retrieving a method handle
+    #   Spotify.metod(:error_message) # => #<Method: Spotify.error_message>
+    #
+    # @param [Symbol, String] name
+    # @param [Boolean] include_private
+    # @return [Boolean] true if the API supports the given method.
+    def respond_to_missing?(name, include_private = false)
+      @__api__.synchronize do
+        @__api__.respond_to?(name, include_private)
+      end
+    end
+
+    # Calls the any method on the underlying {Spotify::API}.
+    #
+    # @example calling the API
+    #    Spotify.link_create_from_string("spotify:user:burgestrand") # => #<Spotify::Link address=0x0deadbeef>
+    #
+    # @note Spotify protects all calls to {Spotify::API} with a lock, so it is
+    #       considered safe to call the API from different threads. The lock
+    #       is re-entrant.
+    #
+    # @param [Symbol, String] name
+    # @param [Object, …] args
+    def method_missing(name, *args, &block)
+      @__api__.synchronize do
+        @__api__.send(name, *args, &block)
+      end
+    end
+  end
+end
+
+require 'spotify/version'
+require 'spotify/util'
+require 'spotify/types'
+require 'spotify/error'
+require 'spotify/objects'
+require 'spotify/defines'
+require 'spotify/structs'
+require 'spotify/api'

data/lib/spotify/api.rb

@@ -0,0 +1,61 @@
+module Spotify
+  class API
+    # @!macro [attach] attach_function
+    #   @!method $1(…)
+    #     @!scope class
+    #     @!scope instance
+    #     @example method signature (shows arguments)
+    #       $*
+    #     @return [${-1}]
+    #
+    # Overloaded to ensure all methods are defined as blocking,
+    # and they return a managed pointer with the correct refcount.
+    #
+    # @param [#to_s] name function name sans `sp_` prefix.
+    # @param [Array] args
+    # @param [Object] returns
+    def self.attach_function(c_name = nil, name, args, returns)
+      if returns.respond_to?(:retaining_class) && name !~ /create/
+        returns = returns.retaining_class
+      end
+
+      options  = { :blocking => true }
+      c_name ||= "sp_#{name}"
+      super(name, c_name, args, returns, options)
+    end
+
+    # Now, make sure we have the right libspotify version.
+
+    # @!group Miscellaneous
+
+    # @see Spotify::API_BUILD
+    attach_function :build_id, [], UTF8String
+
+    # @!endgroup
+  end
+
+  # @return [String] libspotify build ID.
+  API_BUILD = Spotify.build_id
+
+  # No support yet for "similar" versions, so it’s a hard requirement
+  # on the libspotify version. It *must* be the same, even patch version.
+  unless API_BUILD.include?(Spotify::API_VERSION)
+    raise LoadError, "libspotify v#{build_id} is incompatible with ruby spotify v#{VERSION}(#{API_VERSION})"
+  end
+end
+
+require 'spotify/api/album'
+require 'spotify/api/album_browse'
+require 'spotify/api/artist'
+require 'spotify/api/artist_browse'
+require 'spotify/api/error'
+require 'spotify/api/image'
+require 'spotify/api/inbox'
+require 'spotify/api/link'
+require 'spotify/api/playlist'
+require 'spotify/api/playlist_container'
+require 'spotify/api/search'
+require 'spotify/api/session'
+require 'spotify/api/toplist_browse'
+require 'spotify/api/track'
+require 'spotify/api/user'

data/lib/spotify/api/album.rb

@@ -0,0 +1,14 @@
+module Spotify
+  class API
+    # @!group Album
+    attach_function :album_is_loaded, [ Album ], :bool
+    attach_function :album_is_available, [ Album ], :bool
+    attach_function :album_artist, [ Album ], Artist
+    attach_function :album_cover, [ Album, :image_size ], ImageID
+    attach_function :album_name, [ Album ], UTF8String
+    attach_function :album_year, [ Album ], :int
+    attach_function :album_type, [ Album ], :albumtype
+    attach_function :album_add_ref, [ Album ], :error
+    attach_function :album_release, [ Album ], :error
+  end
+end

data/lib/spotify/api/album_browse.rb

@@ -0,0 +1,18 @@
+module Spotify
+  class API
+    # @!group AlbumBrowse
+    attach_function :albumbrowse_create, [ Session, Album, :albumbrowse_complete_cb, :userdata ], AlbumBrowse
+    attach_function :albumbrowse_is_loaded, [ AlbumBrowse ], :bool
+    attach_function :albumbrowse_error, [ AlbumBrowse ], :error
+    attach_function :albumbrowse_album, [ AlbumBrowse ], Album
+    attach_function :albumbrowse_artist, [ AlbumBrowse ], Artist
+    attach_function :albumbrowse_num_copyrights, [ AlbumBrowse ], :int
+    attach_function :albumbrowse_copyright, [ AlbumBrowse, :int ], UTF8String
+    attach_function :albumbrowse_num_tracks, [ AlbumBrowse ], :int
+    attach_function :albumbrowse_track, [ AlbumBrowse, :int ], Track
+    attach_function :albumbrowse_review, [ AlbumBrowse ], UTF8String
+    attach_function :albumbrowse_backend_request_duration, [ AlbumBrowse ], :int
+    attach_function :albumbrowse_add_ref, [ AlbumBrowse ], :error
+    attach_function :albumbrowse_release, [ AlbumBrowse ], :error
+  end
+end