hallon 0.13.0 → 0.14.0

data/CHANGELOG.md

@@ -10,6 +10,47 @@ __Changed__
 
 __Fixed__
 
+[v0.14.0][]
+------------------
+This release brings a lot more meat added to the README, in addition to the following:
+
+__Added__
+
+- Add #load to all loadable objects [acb508a, d554fb9]
+  - Album
+  - AlbumBrowse
+  - Artist
+  - ArtistBrowse
+  - Image
+  - Playlist
+  - PlaylistContainer
+  - Search
+  - Toplist
+  - Track
+  - User
+- Toplist#type [0ea8bac]
+- Playlist.invalid_name? [a516cf0]
+- User::Post#loaded? [373fd7]
+- User::Post#message and User::Post#recipient_name [e31ff68]
+- User::Post#recipient [4c6b71f]
+- User::Post#tracks [1c407b6f]
+
+__Changed__
+
+- User::Post.create and User#post now accepts a single track [542f344]
+- User::Post.new is now private, use User::Post.create instead [00ee6db]
+- Toplist#artists/albums/tracks are now just Toplist#results [0ea8bac]
+- Image#id(param) split up into Image#id and Image#raw_id [1bbd7def]
+- Album#cover(param) split up into Album#cover and Album#cover_link [1bbd7def]
+- Artist#portrait(param) split up into Artist#portrait and Artist#portrait_link [1bbd7def]
+- Default cache_path and settings_path for Session#initialize are now both "tmp/hallon" [15573a7]
+
+__Fixed__
+
+- Playlist#remove accepting invalid parameters [91ccef6]
+- Segfault in tracks_removed/tracks_moved playlist callbacks [46ac650]
+- Observable#subscribe_for_callbacks subscribing to null pointers [f9cf72d]
+
 [v0.13.0][]
 ------------------
 
@@ -259,4 +300,5 @@ easier to handle.
 [v0.11.0]: https://github.com/Burgestrand/Hallon/compare/v0.10.1...v0.11.0
 [v0.12.0]: https://github.com/Burgestrand/Hallon/compare/v0.11.0...v0.12.0
 [v0.13.0]: https://github.com/Burgestrand/Hallon/compare/v0.12.0...v0.13.0
-[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.12.0...HEAD
+[v0.14.0]: https://github.com/Burgestrand/Hallon/compare/v0.13.0...v0.14.0
+[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.14.0...HEAD

data/Gemfile

@@ -4,6 +4,4 @@ gemspec
 gem 'ruby_parser'
 gem 'pry'
 gem 'cover_me', :platform => :ruby_19
-gem 'coreaudio', :platform => :ruby_19 if RUBY_PLATFORM =~ /darwin/i
-gem 'hallon-openal'
 gem 'rb-readline'

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2011 Kim Burgestrand. All rights reserved.
+Copyright 2012 Kim Burgestrand. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are
 permitted provided that the following conditions are met:

data/README.markdown

@@ -1,32 +1,82 @@
 [What is Hallon?][] [![Build Status][]](http://travis-ci.org/Burgestrand/Hallon)
 ===================
 
-Hallon — which is Swedish for “[Raspberry][]” — is a ruby gem for interacting with the official Spotify C API. It is written on top of [Spotify for Ruby][], with the goal of making the experience of using `libspotify` as enjoyable as it can be.
-
-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, providing a service worth attention (and my money!)
-- Linus Oleander, originally inspiring me to write Hallon (for the 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
+Hallon (Swedish for “[Raspberry][]”) is _the_ ruby gem for interacting with the official Spotify C API. It is the only ruby gem for libspotify that is up-to-date and usable. My goal with Hallon is to make libspotify a joy to use.
 
 Code samples can be found under the `examples/` directory. An explanation on how to run them can be found on the [Hallon wiki on GitHub](https://github.com/Burgestrand/Hallon/wiki).
 
 Installation
 ------------
 
-    gem install hallon
+```bash
+gem install hallon
+```
 
 If you want to play audio you’ll need to install an audio driver. As of current writing there is only one driver in existence. You can install it with:
 
-    gem install hallon-openal
+```bash
+gem install hallon-openal
+```
 
 For more information about audio support in Hallon, see the section "Audio support" below.
 
+Hallon and Spotify objects
+--------------------------
+All objects from libspotify have a counterpart in Hallon, and just like in libspotify the objects are populated with information as it becomes available. All objects that behave in this way respond to `#loaded?`, which’ll return true if the object has been populated with data.
+
+To ease loading objects, all loadable objects also respond to [#load][]. This method simply polls on the target object, repeatedly calling [Session#process_events][] until either a time limit is reached or the object has finished loading.
+
+```ruby
+user = Hallon::User.new("spotify:user:burgestrand").load
+puts user.loaded? # => true
+```
+
+As far as usage of the library goes, what applies to libspotify also applies to Hallon, so I would suggest you also read [the libspotify library overview](http://developer.spotify.com/en/libspotify/docs/) and related documentation.
+
+### Callbacks
+Some objects may fire callbacks, most of the time as a direct result of [Session#process_events][]. In libspotify the callbacks are only fired once for every object, but in Hallon you may have more than one object attached to the same libspotify object. As a result, callbacks are handled individually for each Hallon object.
+
+```ruby
+imageA = Hallon::Image.new("spotify:image:548957670a3e9950e87ce61dc0c188debd22b0cb")
+imageB = Hallon::Image.new("spotify:image:548957670a3e9950e87ce61dc0c188debd22b0cb")
+
+imageA.pointer == imageB.pointer # => true, same spotify pointer
+imageA.object_id == imageB.object_id # => false, different objects
+
+imageA.on(:load) do
+  puts "imageA loaded!"
+end
+
+imageB.on(:load) do
+  puts "imageB loaded!"
+end
+
+imageA.load # might load imageB as well, we don’t know
+imageB.load # but the callbacks will both fire on load
+```
+
+A list of all objects that may fire callbacks can be found on the [API page for Hallon::Observable][].
+
+### Errors
+On failed libspotify API calls, a [Hallon::Error][] will be raised with a message explaining the error. Methods that might fail in this way (e.g. [Session.initialize][]) should have this clearly stated in its’ documentation.
+
+For a full list of possible errors, see [the official libspotify documentation on error handling](http://developer.spotify.com/en/libspotify/docs/group__error.html).
+
+### Enumerators
+Some methods (e.g. [Track#artists][]) return a [Hallon::Enumerator][] object. Enumerators are lazily loaded, which means that calling `track.artists` won’t create any artist objects until you try to retrieve one of the records out of the returned enumerator. If you want to load all artists for a track you should retrieve them all then load them in bulk.
+
+```ruby
+artists = track.artists.to_a # avoid laziness, instantiate all artist objects
+artists.map(&:load)
+```
+
+An additional note is that the size of an enumerator may change, and its contents may move as libspotify updates its information.
+
+For the API reference and existing subclasses, see [Hallon::Enumerator][].
+
+### Garbage collection
+Hallon makes use of Ruby’s own garbage collection to automatically release libspotify objects when they are no longer in use. There is no need to retain or release the spotify objects manually.
+
 Audio support
 -------------
 Hallon supports streaming audio from Spotify via [Hallon::Player][]. When you create the player you give it your current session and an audio driver, which the player will then use for audio playback.
@@ -40,47 +90,38 @@ Available drivers are:
 
 - [Hallon::OpenAL](https://rubygems.org/gems/hallon-openal)
 
-        gem install hallon-openal
-
-For information on how to write your own audio driver, see [Hallon::ExampleAudioDriver].
-
-You have any questions?
------------------------
-I can be reached at my [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand). I’d be extremely happy to discuss Hallon with
-you if you have any feedback or thoughts.
-
-For issues and feature requests, please use use [Hallons issue tracker](http://github.com/Burgestrand/Hallon/issues).
+      gem install hallon-openal
 
-This is awesome! I want to help!
---------------------------------
-Sweet! You contribute in more than one way!
-
-### Write code!
-[Fork](http://help.github.com/forking/) Hallon, [write tests for everything](http://relishapp.com/rspec) 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!
-
-### [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.
+For information on how to write your own audio driver, see [Hallon::ExampleAudioDriver][].
 
 Finally, here are some important notes
 --------------------------------------
 
-### Hallon is unstable
-The API is unstable, my code is likely unstable. Everything should be considered unstable!
+### [Please tell me your feedback and requests!](https://github.com/Burgestrand/Hallon/issues/new)
+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 issues with Hallon? Just ask, and I’ll answer if I can.
 
-### 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`.
+### Contributing to Hallon
+[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.
 
-### 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.
+### 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.
+
+### 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.
 
 ### 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.
 
-Versioning policy
------------------
-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.
+You have more questions?
+------------------------
+I can be reached at my [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand). I’d be extremely happy to discuss Hallon with you if you have any feedback or thoughts.
+
+Credits
+-------
+- Per Reimers, cracking synchronization bugs with me deep in the night (4 AM), thanks. :)
+- Jesper Särnesjö, unknowingly providing me a starting point with [Greenstripes][]
+- Linus Oleander, originally inspiring me to write Hallon (for the radiofy.se project)
+- Emil “@mrevilme” Palm, for his patience in helping me debug Hallon deadlock issues
 
 License
 -------
@@ -94,5 +135,14 @@ Hallon is licensed under a 2-clause (Simplified) BSD license. More information c
 [What is Hallon?]:  http://burgestrand.se/articles/hallon-delicious-ruby-bindings-to-libspotify.html
 [Build Status]:     https://secure.travis-ci.org/Burgestrand/Hallon.png
 
+[API page for Hallon::Observable]: http://rubydoc.info/github/Burgestrand/Hallon/master/Hallon/Observable
+
+[Hallon::Enumerator]:         http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Enumerator
+[Hallon::Error]:              http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Error
 [Hallon::Player]:             http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Player
 [Hallon::ExampleAudioDriver]: http://rubydoc.info/github/Burgestrand/Hallon/Hallon/ExampleAudioDriver
+
+[Session#process_events]:     http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Session:process_events
+[Session.initialize]:         http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Session.initialize
+[Track#artists]:              http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Track:artists
+[#load]:                      http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Loadable:load

data/examples/playing_audio.rb

@@ -2,13 +2,13 @@
 
 $LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
 
-require 'bundler/setup'
 require 'hallon'
 
 begin
   require 'hallon/openal'
-rescue LoadError
-  require_relative 'audio_driver'
+rescue LoadError => e
+  puts e.message
+  abort "[ERROR] Could not load gem 'hallon-openal', please install with 'gem install hallon-openal'"
 end
 
 require_relative '../spec/support/config'
@@ -42,8 +42,7 @@ session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   end
 end
 
-driver = defined?(Hallon::OpenAL) ? Hallon::OpenAL : Hallon::CoreAudio
-player = Hallon::Player.new(session, driver)
+player = Hallon::Player.new(session, Hallon::OpenAL)
 
 # Program flow.
 

data/lib/hallon.rb

@@ -5,6 +5,7 @@ require 'hallon/ext/ffi'
 
 require 'hallon/observable'
 require 'hallon/linkable'
+require 'hallon/loadable'
 
 require 'hallon/version'
 require 'hallon/error'
@@ -64,4 +65,23 @@ module Hallon
     |image:[a-fA-F0-9]{40}
     ))
   /x
+
+  # Thrown by {Loadable#load} on failure.
+  TimeoutError = Class.new(Hallon::Error)
+
+  class << self
+    # @return [Numeric] default load timeout in seconds, used in {Loadable#load}.
+    attr_reader :load_timeout
+
+    # @param [Numeric] sets the default load_timeout in seconds for {Loadable#load}.
+    def load_timeout=(new_timeout)
+      if new_timeout < 0
+        raise ArgumentError, "timeout cannot be negative"
+      end
+
+      @load_timeout = new_timeout
+    end
+  end
+
+  self.load_timeout = 5 # seconds
 end

data/lib/hallon/album.rb

@@ -24,6 +24,7 @@ module Hallon
     end
 
     extend Linkable
+    include Loadable
 
     to_link   :from_album
 
@@ -77,18 +78,18 @@ module Hallon
       Artist.from(artist)
     end
 
-    # Retrieves album cover art as an {Image} or a {Link}.
-    #
-    # @param [Boolean] as_image true if you want it as an {Image}.
-    # @return [Image, Link, nil] album cover, the link to it, or nil.
-    def cover(as_image = true)
-      if as_image
-        cover = Spotify.album_cover(pointer)
-        Image.from(cover)
-      else
-        cover = Spotify.link_create_from_album_cover!(pointer)
-        Link.from(cover)
-      end
+    # @see cover_link
+    # @return [Image, nil] album cover as an Image.
+    def cover
+      cover = Spotify.album_cover(pointer)
+      Image.from(cover)
+    end
+
+    # @see cover
+    # @return [Link, nil] album cover as a spotify URI.
+    def cover_link
+      cover = Spotify.link_create_from_album_cover!(pointer)
+      Link.from(cover)
     end
 
     # Browse the Album by creating an {AlbumBrowse} instance from it.

data/lib/hallon/album_browse.rb

@@ -26,6 +26,7 @@ module Hallon
     end
 
     extend Observable::AlbumBrowse
+    include Loadable
 
     # Creates an AlbumBrowse instance from an Album or an Album pointer.
     #

data/lib/hallon/artist.rb

@@ -12,6 +12,7 @@ module Hallon
   # @see http://developer.spotify.com/en/libspotify/docs/group__artist.html
   class Artist < Base
     extend Linkable
+    include Loadable
 
     from_link :as_artist
     to_link   :from_artist
@@ -42,18 +43,18 @@ module Hallon
       Spotify.artist_is_loaded(pointer)
     end
 
-    # Retrieve artist portrait as an {Image} or a {Link}.
-    #
-    # @param [Boolean] as_image true if you want it as an Image
-    # @return [Image, Link, nil] artist portrait, the link to it, or nil.
-    def portrait(as_image = true)
-      if as_image
-        portrait = Spotify.artist_portrait(pointer)
-        Image.from(portrait)
-      else
-        portrait = Spotify.link_create_from_artist_portrait!(pointer)
-        Link.from(portrait)
-      end
+    # @see portrait_link
+    # @return [Image, nil] artist portrait as an Image.
+    def portrait
+      portrait = Spotify.artist_portrait(pointer)
+      Image.from(portrait)
+    end
+
+    # @see portrait
+    # @return [Link, nil] artist portrait as a Link.
+    def portrait_link
+      portrait = Spotify.link_create_from_artist_portrait!(pointer)
+      Link.from(portrait)
     end
 
     # Browse the Artist, giving you the ability to explore its’

data/lib/hallon/artist_browse.rb

@@ -56,6 +56,7 @@ module Hallon
     end
 
     extend Observable::ArtistBrowse
+    include Loadable
 
     # @return [Array<Symbol>] artist browsing types for use in {#initialize}
     def self.types

data/lib/hallon/base.rb

@@ -1,4 +1,6 @@
 # coding: utf-8
+require 'timeout'
+
 module Hallon
   # All objects in Hallon are mere representations of Spotify objects.
   # Hallon::Base covers basic functionality shared by all of these.

data/lib/hallon/image.rb

@@ -13,6 +13,7 @@ module Hallon
     to_link :from_image
 
     extend Observable::Image
+    include Loadable
 
     # Create a new instance of an Image.
     #
@@ -54,11 +55,16 @@ module Hallon
       Spotify.image_format(pointer)
     end
 
-    # @param [Boolean] raw true if you want the image id as a hexadecimal string
-    # @return [String] image ID as a string.
-    def id(raw = false)
-      id = Spotify.image_image_id(pointer)
-      raw ? id : to_hex(id)
+    # @see raw_id
+    # @return [String] image ID as a sequence of hexadecimal digits.
+    def id
+      to_hex(raw_id)
+    end
+
+    # @see id
+    # @return [String] image ID as a binary string.
+    def raw_id
+      Spotify.image_image_id(pointer)
     end
 
     # @return [String] raw image data as a binary encoded string.
@@ -75,19 +81,21 @@ module Hallon
     # @return [Boolean]
     def ==(other)
       super or if other.is_a?(Image)
-        id(true) == other.id(true)
+        raw_id == other.raw_id
       end
     end
 
     protected
-      # @param [String]
-      # @return [String]
+      # @see to_id
+      # @param [String] id an image id as a binary string
+      # @return [String] image id as a hexadecimal string
       def to_hex(id)
         id.unpack('H40')[0]
       end
 
-      # @param [String]
-      # @return [String]
+      # @see to_hex
+      # @param [String] hex an image id as a hexadecimal string
+      # @return [String] image id as a binary string
       def to_id(hex)
         [hex].pack('H40')
       end