hallon 0.8.0 → 0.9.0

data/.travis.yml

@@ -1,2 +1,4 @@
 rvm:
   - 1.9.2
+  - 1.9.3
+

data/CHANGELOG

@@ -1,6 +1,49 @@
 Hallon’s Changelog
 ==================
 
+v0.9.0
+------------------
+- Upgraded to libspotify *v10*
+- Improve documentation consistency
+- Link.new now raises an error if there’s no session
+- Minimal PlaylistContainer support (more to come next version)
+
+[ Added ]
+- Playlist subsystem support
+- Toplist#request_duration
+- AlbumBrowse#request_duration
+- ArtistBrowse#request_duration
+- ArtistBrowse.types
+- Player#volume_normalization(?|=)
+- Session.new accepting device_id/tracefile options
+- Session#login!/relogin!/logout! convenience methods
+- Session#starred: starred playlist for currently logged in user
+- Session#inbox: inbox for currently logged in user
+- Session.instance?
+- Image.new(image_id_in_hex) support
+- Link#to_uri
+- User.new(canonical_username)
+- User#post: posting tracks to other users’ inboxes
+- User#starred: starred playlist of a given user
+- Track#placeholder?
+- Track#offline_status
+- Track#unwrap
+- type parameter to Artist#browse
+
+[ Fixed ]
+- Moved from using FFI::Pointers to Spotify::Pointers
+- Spotify::Pointer garbage collection
+- Link#valid? using exceptions for flow control
+- Session#connection_rules= now raises an error when given invalid rule
+- Search.radio now raises an error when given invalid genres
+
+[ Changed ]
+- Playlist::Track#seen= removed in favor of Playlist#seen(index, yesno)
+- Object#error -> Object#status (AlbumBrowse, ArtistBrowse, Search, Toplist, User)
+- Album#year renamed to Album#release_year
+- Linkable.from_link/to_link and resulting #from_link are now private
+
+
 v0.8.0
 ------------------
 [ Added ]

data/Gemfile

@@ -1,4 +1,6 @@
 source :rubygems
 gemspec
 
+gem 'ruby_parser'
+gem 'pry'
 gem 'cover_me', :platform => :ruby_19

data/README.markdown

@@ -1,4 +1,4 @@
-[What is Hallon?][] [![Build Status][]](http://travis-ci.org/Burgestrand/Hallon) ([but that’s okay](https://github.com/Burgestrand/Hallon/issues/33))
+[What is Hallon?][] [![Build Status][]](http://travis-ci.org/Burgestrand/Hallon)
 ===============
 
 We rubyists have this awesome [spotify gem][] allowing us to use [libspotify][] from within Ruby, but it has a significant drawback: the `libspotify` API is very hard to use. Now, we can’t have that, so what do we do? We make Hallon!
@@ -8,12 +8,22 @@ Hallon is Swedish for “Raspberry”, and has been written to satisfy my needs
 Hallon would not have been possible if not for these people:
 
 - Per Reimers, cracking synchronization bugs with me in the deep night (4 AM) and correcting me when I didn’t know better
-- [Spotify](http://www.spotify.com/), providing a service worth attention (and my money!)
-- [Linus Oleander](https://github.com/oleander), involving me with the [radiofy.se](http://radiofy.se) project, ultimately spawning the necessity of Hallon
-- [Jesper Särnesjö][], creator of [Greenstripes][], making me think of Hallon as an achievable goal
+- [Spotify][], providing a service worth attention (and my money!)
+- [Linus Oleander][], spawning the need for Hallon by having me in the [radiofy.se](http://radiofy.se) project
+
+Also, these people are worthy of mention simply for their contribution:
+
+- [Jesper Särnesjö][], unknowingly providing me a starting point with [Greenstripes][]
+- Emil “@mrevilme” Palm, for his patience in helping me debug Hallon deadlock issues
 
 Code samples can be found under `examples/` directory.
 
+You have any questions?
+-----------------------
+If you need to discuss issues or feature requests you can use [Hallons issue tracker](http://github.com/Burgestrand/Hallon/issues). For *anything* else you have to say or ask I can also be reached via [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand).
+
+In fact, you can contact me via email or twitter even if it’s about features or issues. I’ll probably put them in the issue tracker myself after the discussion ;)
+
 This is awesome! I want to help!
 --------------------------------
 Sweet! You contribute in more than one way!
@@ -24,15 +34,8 @@ Sweet! You contribute in more than one way!
 ### [Send me feedback and requests](http://github.com/Burgestrand/Hallon/issues)
 Really, I ❤ feedback! Suggestions on how to improve the API, tell me what is delicious about Hallon, tell me what is yucky about Hallon… anything! All feedback is useful in one way or another.
 
-You have any questions?
------------------------
-If you need to discuss issues or feature requests you can use [Hallons issue tracker](http://github.com/Burgestrand/Hallon/issues). For *anything* else you have to say or ask I can also be reached via [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand).
-
-In fact, you can contact me via email or twitter even if it’s about features or issues. I’ll probably put them in the issue tracker myself after the discussion ;)
-
-What’s the catch?
------------------
-There are several!
+Finally, here’s some important notes
+------------------------------------
 
 ### Hallon is unstable
 The API is unstable, my code is likely unstable. Everything should be considered unstable!
@@ -43,6 +46,9 @@ You can only keep one session with Spotify alive at a time in the same process,
 ### You still have to worry about threads
 I have been doing my best at hiding the complexity in `libspotify`, but it’s still a work in progress. Despite my efforts, you’ll need to be familiar with concurrent programming to use Hallon properly.
 
+### When forking, you need to be extra careful
+If you fork, you need to instantiate the session in 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.
+
 Versioning policy
 -----------------
 Hallon uses [semantic versioning](http://semver.org) as of v0.0.0. As long
@@ -57,5 +63,7 @@ Hallon is licensed under a 2-clause (Simplified) BSD license. More information c
 [libspotify]:      http://developer.spotify.com/en/libspotify/overview/
 [Greenstripes]:    http://github.com/sarnesjo/greenstripes
 [Jesper Särnesjö]: http://jesper.sarnesjo.org/
+[Linus Oleander]:  https://github.com/oleander
+[Spotify]:         http://spotify.com/
 [What is Hallon?]: http://burgestrand.se/articles/hallon-delicious-ruby-bindings-to-libspotify.html
 [Build Status]:    https://secure.travis-ci.org/Burgestrand/Hallon.png

data/Rakefile

@@ -9,12 +9,12 @@ YARD::Rake::YardocTask.new
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new('spec') do |task|
-  task.skip_bundler = true
   task.ruby_opts = '-W2'
 end
 
 desc "Run the full test suite and generate a coverage report"
 task 'spec:cov' => ['clean', 'spec'] do
+  require 'bundler/setup'
   require 'cover_me'
   require './spec/support/cover_me'
 
@@ -24,6 +24,8 @@ end
 
 desc "Process the Hallon codebase, finding out which Spotify methods are being used"
 task 'spotify:coverage' do
+  require 'bundler/setup'
+
   require 'set'
   require 'spotify'
 
@@ -34,18 +36,39 @@ task 'spotify:coverage' do
     abort
   end
 
+  # 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 << Spotify
+    def lookup_return_value(name)
+      @function_to_return_type[name.to_s]
+    end
+
+    def define_singleton_method(name, &block)
+      return_type = block.binding.eval("return_type")
+      @function_to_return_type ||= {}
+      @function_to_return_type[name.to_s] = return_type
+
+      super
+    end
+  end
+  require 'hallon/ext/spotify'
+
   methods = Spotify.methods(false).map(&:to_s)
+  auto_gc = Set.new(methods.grep(/!\z/))
   covered = Set.new(methods)
+  warning = []
   ignored = [
     'session_release',  # segfaults on libspotify <= 9
     'session_userdata', # wont support this
     'link_as_track',    # using link_as_track_and_offset instead
-    'toplistbrowse_add_ref', # toplistbrowse creates its’ own pointer
-    'artistbrowse_add_ref',  # artistbrowse creates its’ own pointer
-    'albumbrowse_add_ref',   # albumbrowse creates its’ own pointer
-    'link_add_ref',          # all creation of links has +1 ref
-    'image_add_ref',         # all creation of image has +1 ref
-    'search_add_ref',        # search creates its’ own pointer
+    '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
+    'image_remove_load_callback', # cleared when Image is GCd
+    'playlist_remove_callbacks', # cleared when Playlist is GCd
   ]
 
   covered -= ignored
@@ -56,28 +79,43 @@ task 'spotify:coverage' do
   handlers = Hash.new(Hash.new(silencer))
 
   # Direct calls
-  handlers[Sexp.new(:const, :Spotify)] = Hash.new(proc { |_, meth, _| meth })
-
-  # Spotify Pointer
-  pointer = handlers[Sexp.new(:colon2, [:const, :Spotify], :Pointer)] = Hash.new(printer)
-  pointer[:new] = proc do |recv, meth, (_, ptr, name, release)|
-    name = name.value
-    release &&= release.value != :false
-    ["#{name}_release", "#{name if release}_add_ref"]
-  end
+  handlers[Sexp.new(:const, :Spotify)] = Hash.new(proc do |_, meth, _|
+    if auto_gc.include?("#{meth}!")
+      warning << meth
+    end
+
+    result = [meth]
+
+    # if it’s auto-GC’d, we can also account for _release and _add_ref
+    if meth =~ /(.+)!\z/
+      return_type = Spotify.lookup_return_value(meth)
+
+      result << $1
+      result << "#{return_type}_release"
+      result << "#{return_type}_add_ref"
+    end
+
+    result
+  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"
-    "%s_%s" % [prefix, name.value]
+    method = "%s_%s" % [prefix, name.value]
+    [method, "#{method}!"]
   end
 
+  fails = {}
   FileList['lib/**/*.rb'].each do |file|
-    ast   = RubyParser.new.parse File.read(file)
-    ast.each_of_type(:call) do |_, recv, meth, args, *rest|
-      name = handlers[recv][meth].call(recv, meth, args)
-      covered.subtract Array(name).map(&:to_s)
+    begin
+      ast   = RubyParser.new.parse File.read(file)
+      ast.each_of_type(:call) do |_, recv, meth, args, *rest|
+        name = handlers[recv][meth].call(recv, meth, args)
+        covered.subtract Array(name).map(&:to_s)
+      end
+    rescue => e
+      fails[file] = e.message.strip + " (#{e.class.name})"
     end
   end
 
@@ -91,15 +129,38 @@ task 'spotify:coverage' do
 
   puts "Ignored:"
   ignored.each_slice(3) do |slice|
-    puts "\t#{slice.join(', ')}"
+    puts "  #{slice.join(', ')}"
   end
   puts
 
+  unless fails.empty?
+    puts "Failures:"
+    fails.each_pair do |file, fail|
+      puts "  #{file}: #{fail}"
+    end
+    puts
+  end
+
+  unless warning.empty?
+    puts "Warnings (use auto-gc methods instead!):"
+    warning.each do |method|
+      puts "  #{method}"
+    end
+    puts
+  end
+
   puts "Coverage: %.02f%%" % (100 * (1 - covered.size.fdiv(methods.size)))
 end
 
+desc "Download mockspotify submodule"
+task 'mock:fetch' do
+  unless File.exists?('./spec/mockspotify/libmockspotify/src/libmockspotify.h')
+    sh 'git submodule update --init'
+  end
+end
+
 desc "Compile mockspotify"
-task 'mock:compile' do
+task 'mock:compile' => 'mock:fetch' do
   Dir.chdir 'spec/mockspotify' do
     sh 'ruby extconf.rb'
     sh 'make'

data/dev/login.rb

@@ -0,0 +1,16 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require File.expand_path('../../spec/support/config', __FILE__)
+
+require 'bundler/setup'
+require 'hallon'
+require 'pry'
+
+session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
+  on(:log_message) do |message|
+    puts "[LOG] #{message}"
+  end
+end
+
+session.login! ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD']
+
+binding.pry

data/examples/adding_tracks_to_playlist.rb

@@ -0,0 +1,49 @@
+# coding: utf-8
+require 'hallon'
+require './spec/support/config'
+
+##
+# Configuration
+#
+# uri to the playlist you wish to add tracks to
+playlist_uri = "spotify:user:burgestrand:playlist:07AX9IY9Hqmj1RqltcG0fi"
+
+# array of track uris you wish to add to the playlist
+track_uris = %w[spotify:track:6GHrP1i3vQo1e8VkEHRnvz spotify:track:2t7u74OJXHf0qQxXHpnb2R spotify:track:24q7a0Bo5MFLJUslg1lsS5]
+
+# index to add the tracks to in the playlist
+position = 0
+
+session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
+  on(:log_message) do |message|
+    puts "[LOG] #{message}"
+  end
+end
+
+session.login!(ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD'])
+puts "Successfully logged in!"
+
+# First, we load the playlist. This is necessary for libspotify
+# to know if we have write access to it or not. Not doing it might
+# end us up getting permission denied errors later.
+puts "Loading playlist #{playlist_uri}"
+playlist = Hallon::Playlist.new(playlist_uri)
+session.wait_for { playlist.loaded? }
+
+# Convert all track URIs to actual Tracks.
+puts "Loading #{track_uris.length} tracks"
+tracks = track_uris.map { |x| Hallon::Track.new(x) }
+
+# … insert the tracks at the desired position into the playlist.
+playlist.insert(position, tracks)
+
+# finally, wait for the updates to the playlist to be acknowledged by the
+# Spotify back-end. Once they have, we’ll see the tracks in our desktop
+# client as well.
+puts "Uploading playlist changes to Spotify back-end!"
+
+state_changed = false
+playlist.on(:playlist_state_changed) { state_changed = true }
+session.wait_for { state_changed && ! playlist.pending? }
+
+puts "We’re done!"

data/examples/logging_in.rb

@@ -8,11 +8,6 @@ session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   end
 end
 
-session.login ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD']
-
-session.wait_for(:logged_in) { |error| Hallon::Error.maybe_raise(error) }
-session.wait_for(:connection_error) do |error|
-  session.logged_in? or Hallon::Error.maybe_raise(error)
-end
+session.login!(ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD'])
 
 puts "Successfully logged in!"

data/examples/show_published_playlists_of_user.rb

@@ -39,12 +39,7 @@ session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   end
 end
 
-session.login ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD']
-
-session.wait_for(:logged_in) { |error| Hallon::Error.maybe_raise(error) }
-session.wait_for(:connection_error) do |error|
-  session.logged_in? or Hallon::Error.maybe_raise(error)
-end
+session.login!(ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD'])
 
 puts "Successfully logged in!"
 
@@ -55,7 +50,7 @@ while username = prompt("Enter a Spotify username: ")
     username  = nil if username.empty?
 
     puts "Fetching container for #{username || "current user"}..."
-    container = Spotify::session_publishedcontainer_for_user_create(session.pointer, username)
+    container = Spotify::session_publishedcontainer_for_user_create!(session.pointer, username)
     if container.null?
       puts "Failed (unknown reason)."
       next
@@ -67,26 +62,21 @@ while username = prompt("Enter a Spotify username: ")
     puts "Listing #{num_playlists} playlists."
 
     num_playlists.times do |i|
-      playlist = Spotify::playlistcontainer_playlist(container, i)
-      session.wait_for { Spotify::playlist_is_loaded(playlist) }
+      playlist = Spotify::playlistcontainer_playlist!(container, i)
+      playlist = Hallon::Playlist.new(playlist)
+      session.wait_for { playlist.loaded? }
 
       puts
-      puts Spotify::playlist_name(playlist) << ": "
+      puts playlist.name << ": "
 
-      num_tracks = Spotify::playlist_num_tracks(playlist)
-      num_tracks.times do |j|
-        # Here we go back into Hallon API, passing the raw pointer
-        # to Hallon::Track.new; this means all of Hallon::Track API
-        # is supported on “track” here!
-        track = Hallon::Track.new(Spotify::playlist_track(playlist, j))
+      num_tracks = playlist.tracks.size
+      playlist.tracks.each_with_index do |track, i|
         session.wait_for { track.loaded? }
 
-        puts "\t (#{j+1}/#{num_tracks}) #{track.name}"
+        puts "\t (#{i+1}/#{num_tracks}) #{track.name}"
       end
     end
   rescue Interrupt
     # do nothing, continue with loop
-  ensure
-    Spotify::playlistcontainer_release(container) unless container.nil?
   end
 end

data/hallon.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |gem|
   gem.platform    = Gem::Platform::RUBY
   gem.required_ruby_version = '~> 1.8'
 
-  gem.add_dependency 'spotify', '~> 9.0.0'
+  gem.add_dependency 'spotify', '~> 10.1.0'
   gem.add_development_dependency 'bundler', '~> 1.0'
   gem.add_development_dependency 'rake', '~> 0.8'
   gem.add_development_dependency 'rspec', '~> 2'

data/lib/hallon.rb

@@ -3,7 +3,6 @@ require 'spotify'
 require 'hallon/ext/spotify'
 require 'hallon/ext/ffi'
 
-require 'hallon/synchronizable'
 require 'hallon/observable'
 require 'hallon/linkable'
 
@@ -11,6 +10,7 @@ require 'hallon/version'
 require 'hallon/error'
 require 'hallon/base'
 require 'hallon/enumerator'
+
 require 'hallon/session'
 require 'hallon/link'
 require 'hallon/user'
@@ -19,7 +19,8 @@ require 'hallon/track'
 require 'hallon/album'
 require 'hallon/artist'
 require 'hallon/toplist'
-
+require 'hallon/playlist'
+require 'hallon/playlist_container'
 require 'hallon/album_browse'
 require 'hallon/artist_browse'
 require 'hallon/player'