hallon 0.4.0 → 0.8.0

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "spec/mockspotify/libmockspotify"]
+	path = spec/mockspotify/libmockspotify
+	url = git://github.com/Burgestrand/libmockspotify.git

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm:
+  - 1.9.2

data/CHANGELOG

@@ -1,16 +1,40 @@
 Hallon’s Changelog
 ==================
 
-NEXT
+v0.8.0
 ------------------
-- No longer uses autotest as development dependency
+[ Added ]
+- Add example for listing track information in playlists
+- Updated to (lib)Spotify v9
+- Full Track subsystem support
+- Full Album subsystem support
+- Full AlbumBrowse subsystem support
+- Full Artist subsystem support
+- Full ArtistBrowse subsystem support
+- Full Toplist subsystem support
+- Full Search subsystem support
+- Allow setting Session connection type/rules
+- Session offline query methods (offline_time_left et al)
+- Work-in-progress Player
+- Add Session relogin support
+- Add Enumerator
+- Use libmockspotify for testing (spec/mockspotify)
 - Add Hallon::Base class
-- Cleaned up specs to use same mocks everywhere
-- Album subsystem support (except for #cover and #artist)
 - Add optional parameter to have Image#id return raw id
-- Make Hallon::URI match image URIs
 - Allow Image.new to accept an image id
-- Add Album#cover
+- Add Hallon::API_BUILD
+
+[ Fixed ]
+- Improve speed of Session#wait_for for already-loaded cases
+- Error.maybe_raise no longer errors out on timeout
+- from_link now checks for null pointers
+- No longer uses autotest as development dependency
+- Cleaned up specs to use same mocks everywhere
+- Make Hallon::URI match image URIs
+
+[ Broke ]
+- Ignore Ruby v1.8.x compatibility
+
 
 v0.3.0
 ------------------

data/README.markdown

@@ -1,8 +1,6 @@
-What is Hallon?
+[What is Hallon?][] [![Build Status][]](http://travis-ci.org/Burgestrand/Hallon) ([but that’s okay](https://github.com/Burgestrand/Hallon/issues/33))
 ===============
 
-> [Hallon, delicious Ruby bindings for libspotify](http://burgestrand.se/articles/hallon-delicious-ruby-bindings-to-libspotify.html)
-
 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!
 
 Hallon is Swedish for “Raspberry”, and has been written to satisfy my needs for API simplicity. It provides you with a wrapper around the spotify gem, making the experience of using `libspotify` from Ruby much more enjoyable.
@@ -11,7 +9,7 @@ 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` project, ultimately spawning the necessity of Hallon
+- [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
 
 Code samples can be found under `examples/` directory.
@@ -55,7 +53,9 @@ License
 -------
 Hallon is licensed under a 2-clause (Simplified) BSD license. More information can be found in the `LICENSE.txt` file.
 
-[spotify gem]: https://rubygems.org/gems/spotify
-[libspotify]: http://developer.spotify.com/en/libspotify/overview/
-[Greenstripes]: http://github.com/sarnesjo/greenstripes
+[spotify gem]:     https://rubygems.org/gems/spotify
+[libspotify]:      http://developer.spotify.com/en/libspotify/overview/
+[Greenstripes]:    http://github.com/sarnesjo/greenstripes
 [Jesper Särnesjö]: http://jesper.sarnesjo.org/
+[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

@@ -27,24 +27,58 @@ task 'spotify:coverage' do
   require 'set'
   require 'spotify'
 
-  dynamicly_used = []
-  dynamicly_used << "link_create_from_track" # lib/hallon/track.rb
-  dynamicly_used << "track_add_ref"          # lib/ext/spotify.rb
-  dynamicly_used << "track_release"          # lib/ext/spotify.rb
-  dynamicly_used << "link_create_from_image" # lib/hallon/image.rb
-  dynamicly_used << "image_release"          # lib/ext/spotify.rb
-  dynamicly_used << "link_create_from_user"  # lib/hallon/user.rb
-  dynamicly_used << "user_add_ref"           # lib/ext/spotify.rb
-  dynamicly_used << "user_release"           # lib/ext/spotify.rb
-  dynamicly_used << "link_as_track"          # IGNORE
-  dynamicly_used << "link_release"           # lib/ext/spotify.rb
-
-  methods = Spotify.methods(false).map(&:to_s) - dynamicly_used
+  begin
+    require 'ruby_parser'
+  rescue LoadError
+    puts "You need ruby_parser for the spotify:coverage rake task"
+    abort
+  end
+
+  methods = Spotify.methods(false).map(&:to_s)
   covered = Set.new(methods)
-  matcher = /Spotify(?:::|\.)([\w_]+)[ \(]/
+  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
+  ]
+
+  covered -= ignored
+
+  # Handlers for different AST nodes
+  printer  = proc { |*args| p args }
+  silencer = proc { }
+  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
+
+  # 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]
+  end
 
   FileList['lib/**/*.rb'].each do |file|
-    File.read(file).scan(matcher) { |method, _| covered.delete(method) }
+    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
   end
 
   covered.group_by { |m| m[/[^_]+/] }.each_pair do |group, methods|
@@ -55,9 +89,24 @@ task 'spotify:coverage' do
     puts
   end
 
+  puts "Ignored:"
+  ignored.each_slice(3) do |slice|
+    puts "\t#{slice.join(', ')}"
+  end
+  puts
+
   puts "Coverage: %.02f%%" % (100 * (1 - covered.size.fdiv(methods.size)))
 end
 
+desc "Compile mockspotify"
+task 'mock:compile' do
+  Dir.chdir 'spec/mockspotify' do
+    sh 'ruby extconf.rb'
+    sh 'make'
+  end
+end
+
+task :spec => 'mock:compile'
 task :test => :spec
 
 #
@@ -70,7 +119,12 @@ end
 
 desc "Remove generated files"
 task :clean do
-  sh 'git clean -fdx --exclude Gemfile.lock --exclude spec/support/config.rb'
+  print "Do you really want to delete all non-git tracked files? (y/n) [n]: "
+  if STDIN.gets.chomp == 'y'
+    sh 'git clean -fdx --exclude Gemfile.lock --exclude spec/support/config.rb'
+  else
+    puts "Whew. Close one!"
+  end
 end
 
 task :default => [:spec]

data/examples/logging_in.rb

@@ -2,7 +2,7 @@
 require 'hallon'
 require './spec/support/config'
 
-session = Hallon::Session.instance IO.read(ENV['HALLON_APPKEY']) do
+session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   on(:log_message) do |message|
     puts "[LOG] #{message}"
   end
@@ -10,8 +10,8 @@ end
 
 session.login ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD']
 
-session.process_events_on(:logged_in) { |error| Hallon::Error.maybe_raise(error) }
-session.process_events_on(:connection_error) do |error|
+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
 

data/examples/printing_link_information.rb

@@ -9,7 +9,7 @@ def prompt(str)
 end
 
 # Hallon
-session = Hallon::Session.instance IO.read(ENV['HALLON_APPKEY']) do
+session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   on(:log_message) do |message|
     $stderr.puts "[LOG] #{message}"
   end

data/examples/show_published_playlists_of_user.rb

@@ -0,0 +1,92 @@
+# coding: utf-8
+#
+# DISCLAIMER:
+# This file was written without extensive testing, and is merely a proof
+# of concept. Before using this yourself, I advice you to look through
+# the code carefully.
+#
+# The below code uses the raw Spotify FFI API, and does not represent how
+# this will be done when Hallon has API support for below operations!
+#
+# Hallon API in this file is only used for:
+# - logging in
+# - querying track information
+#
+# Raw Spotify FFI API is used for:
+# - fetching playlist container
+# - fetching playlists
+# - fetching tracks from playlists
+require 'hallon'
+require './spec/support/config'
+
+# Utility
+def prompt(str)
+  print str
+  gets.chomp
+end
+
+session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
+  on(:log_message) do |message|
+    puts "[LOG] #{message}"
+  end
+
+  on(:connection_error) do |error|
+    Hallon::Error.maybe_raise(error)
+  end
+
+  on(:logged_out) do
+    abort "[FAIL] Logged out!"
+  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
+
+puts "Successfully logged in!"
+
+# Hallon does not have support for the below operations, so we resort
+# to using the raw Spotify gem and FFI for now.
+while username = prompt("Enter a Spotify username: ")
+  begin
+    username  = nil if username.empty?
+
+    puts "Fetching container for #{username || "current user"}..."
+    container = Spotify::session_publishedcontainer_for_user_create(session.pointer, username)
+    if container.null?
+      puts "Failed (unknown reason)."
+      next
+    end
+
+    session.wait_for { Spotify::playlistcontainer_is_loaded(container) }
+
+    num_playlists = Spotify::playlistcontainer_num_playlists(container)
+    puts "Listing #{num_playlists} playlists."
+
+    num_playlists.times do |i|
+      playlist = Spotify::playlistcontainer_playlist(container, i)
+      session.wait_for { Spotify::playlist_is_loaded(playlist) }
+
+      puts
+      puts Spotify::playlist_name(playlist) << ": "
+
+      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))
+        session.wait_for { track.loaded? }
+
+        puts "\t (#{j+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

@@ -1,5 +1,7 @@
 # -*- encoding: utf-8 -*-
-require './lib/hallon/version'
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+require 'hallon/version'
 
 Gem::Specification.new do |gem|
   gem.name     = "hallon"
@@ -7,9 +9,10 @@ Gem::Specification.new do |gem|
   gem.homepage = "http://github.com/Burgestrand/Hallon"
   gem.authors  = ["Kim Burgestrand"]
   gem.email    = 'kim@burgestrand.se'
-  gem.license  = 'GNU AGPL'
+  gem.license  = 'X11 License'
 
   gem.files         = `git ls-files`.split("\n")
+  gem.files        += `cd spec/mockspotify/libmockspotify && git ls-files src`.split("\n").map { |path| "spec/mockspotify/libmockspotify/#{path}" }
   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   gem.executables   = []
   gem.require_paths = ["lib"]
@@ -18,8 +21,8 @@ Gem::Specification.new do |gem|
   gem.platform    = Gem::Platform::RUBY
   gem.required_ruby_version = '~> 1.8'
 
-  gem.add_dependency 'spotify', '~> 8.0.5'
-  gem.add_development_dependency 'mockspotify', '~> 0.1.8'
+  gem.add_dependency 'spotify', '~> 9.0.0'
+  gem.add_development_dependency 'bundler', '~> 1.0'
   gem.add_development_dependency 'rake', '~> 0.8'
   gem.add_development_dependency 'rspec', '~> 2'
   gem.add_development_dependency 'yard'

data/lib/hallon.rb

@@ -2,7 +2,6 @@
 require 'spotify'
 require 'hallon/ext/spotify'
 require 'hallon/ext/ffi'
-require 'hallon/ext/object'
 
 require 'hallon/synchronizable'
 require 'hallon/observable'
@@ -11,12 +10,20 @@ require 'hallon/linkable'
 require 'hallon/version'
 require 'hallon/error'
 require 'hallon/base'
+require 'hallon/enumerator'
 require 'hallon/session'
 require 'hallon/link'
 require 'hallon/user'
 require 'hallon/image'
 require 'hallon/track'
 require 'hallon/album'
+require 'hallon/artist'
+require 'hallon/toplist'
+
+require 'hallon/album_browse'
+require 'hallon/artist_browse'
+require 'hallon/player'
+require 'hallon/search'
 
 # The Hallon module wraps around all Hallon objects to avoid polluting
 # the global namespace. To start using Hallon, you most likely want to
@@ -25,15 +32,20 @@ module Hallon
   # @see Spotify::API_VERSION
   API_VERSION = Spotify::API_VERSION
 
+  # Spotify API build.
+  #
+  # @see Spotify#api_build
+  API_BUILD = Spotify.build_id
+
   # A regex that matches all Spotify URIs
   #
   # @example
   #   Hallon::URI === "spotify:user:burgestrand" # => true
   URI = /(spotify:(?:
-    (?:artist|album|track|user:[^:]+:playlist):\h+
+    (?:artist|album|track|user:[^:]+:playlist):[a-fA-F0-9]+
     |user:[^:]+
-    |search:(?:[-\w$\.+!*'(),]+|%\h{2})+
-    |image:\h{40}
+    |search:(?:[-\w$\.+!*'(),]+|%[a-fA-F0-9]{2})+
+    |image:[a-fA-F0-9]{40}
     ))
   /x
 end

data/lib/hallon/album.rb

@@ -9,8 +9,9 @@ module Hallon
   #
   # @see http://developer.spotify.com/en/libspotify/docs/group__album.html
   class Album < Base
+    # An array of different kinds of albums. Singles, compilations etc.
     def self.types
-      Spotify.enum_type(:albumtype).to_hash
+      Spotify.enum_type(:albumtype).symbols
     end
 
     extend Linkable
@@ -63,15 +64,24 @@ module Hallon
     # Retrieve album cover art.
     #
     # @return [Image]
-    def cover(session = Session.instance)
+    def cover
       image_id = Spotify.album_cover(@pointer)
-      Hallon::Image.new(image_id.read_string(20), session) unless image_id.null?
+      Image.new(image_id.read_string(20)) unless image_id.null?
     end
 
-    # Not yet implemented.
+    # Retrieve the album Artist.
+    #
+    # @return [Artist, nil]
     def artist
-      return if (ptr = Spotify.album_artist(@pointer)).null?
-      raise NotImplementedError
+      artist = Spotify.album_artist(@pointer)
+      Artist.new(artist) unless artist.null?
+    end
+
+    # Retrieve an AlbumBrowse object for this Album.
+    #
+    # @return [AlbumBrowse]
+    def browse
+      AlbumBrowse.new(pointer)
     end
   end
 end

data/lib/hallon/album_browse.rb

@@ -0,0 +1,78 @@
+module Hallon
+  # AlbumBrowse objects are for retrieving additional data from
+  # an album that cannot otherwise be acquired. This includes
+  # tracks, reviews, copyright information.
+  #
+  # AlbumBrowse object triggers the `:load` callback on itself
+  # when it loads.
+  #
+  # @example
+  #   browse = album.browse # album is a Hallon::Album
+  #   browse.on(:load) do
+  #     puts "Album browser for #{browse.album.name} has been loaded!"
+  #   end
+  #   session.wait_for { browse.loaded? } # will eventually trigger above callback
+  #
+  # @see Album
+  # @see http://developer.spotify.com/en/libspotify/docs/group__albumbrowse.html
+  class AlbumBrowse < Base
+    include Observable
+
+    # Creates an AlbumBrowse instance from an Album or an Album pointer.
+    #
+    # @note Use {Album#browse} to browse an Album.
+    # @param [Album, FFI::Pointer] album
+    def initialize(album)
+      album   = album.pointer if album.respond_to?(:pointer)
+      @callback = proc { trigger(:load) }
+
+      albumbrowse = Spotify.albumbrowse_create(session.pointer, album, @callback, nil)
+      @pointer    = Spotify::Pointer.new(albumbrowse, :albumbrowse, false)
+    end
+
+    # @return [Boolean] true if the album is loaded
+    def loaded?
+      Spotify.albumbrowse_is_loaded(@pointer)
+    end
+
+    # @see Error
+    # @return [Symbol] album browser error status
+    def error
+      Spotify.albumbrowse_error(@pointer)
+    end
+
+    # @return [String] album review
+    def review
+      Spotify.albumbrowse_review(@pointer)
+    end
+
+    # @return [Artist] artist performing this album
+    def artist
+      pointer = Spotify.albumbrowse_artist(@pointer)
+      Artist.new(pointer) unless pointer.null?
+    end
+
+    # @return [Album] album this object is browsing
+    def album
+      pointer = Spotify.albumbrowse_album(@pointer)
+      Album.new(pointer) unless pointer.null?
+    end
+
+    # @return [Enumerator<String>] list of copyright notices
+    def copyrights
+      size = Spotify.albumbrowse_num_copyrights(@pointer)
+      Enumerator.new(size) do |i|
+        Spotify.albumbrowse_copyright(@pointer, i)
+      end
+    end
+
+    # @return [Enumerator<Track>] list of tracks
+    def tracks
+      size = Spotify.albumbrowse_num_tracks(@pointer)
+      Enumerator.new(size) do |i|
+        pointer = Spotify.albumbrowse_track(@pointer, i)
+        Track.new(pointer) unless pointer.null?
+      end
+    end
+  end
+end