hallon 0.14.0 → 0.15.0

data/CHANGELOG.md

@@ -4,12 +4,31 @@ Hallon’s Changelog
 [HEAD][]
 ------------------
 
+[v0.15.0][]
+------------------
+Updated to libspotify v11.1.60 [3c810b0], and improved the examples provided within Hallon codebase significantly.
+
+__Removed__
+
+- Hallon::Search.radio (was removed in libspotify upgrade)
+
 __Added__
 
+- You can now construct Search objects from a Link! [7f87e74c]
+- Playlist#upload [479c3d20, 2a90097]
+
 __Changed__
 
+- Observable#on now returns the previous handler [7ed42c4b]
+- Default load time is now 30 seconds instead of 5 [d04440ba]
+
 __Fixed__
 
+- Hallon::URI now matches entire URIs [397cf711]
+- Image IDs with NUL-bytes now no longer raise errors [30a376eb]
+- Link#to_str/to_uri now returns a String in UTF-8 encoding [f1661736]
+- Session#login now raises an error when given empty credentials [dbc390ea]
+
 [v0.14.0][]
 ------------------
 This release brings a lot more meat added to the README, in addition to the following:
@@ -301,4 +320,5 @@ easier to handle.
 [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
 [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
+[v0.15.0]: https://github.com/Burgestrand/Hallon/compare/v0.14.0...v0.15.0
+[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.15.0...HEAD

data/README.markdown

@@ -5,13 +5,55 @@ Hallon (Swedish for “[Raspberry][]”) is _the_ ruby gem for interacting with
 
 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
-------------
+Prerequisites
+-------------
+
+Before you start using Hallon you’ll need to complete the following steps.
+
+1. Get yourself a Spotify premium account, which is required for libspotify to work. You username and password
+   (either classic Spotify, or facebook credentials) will be used to connect to Spotify later.
+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 **v10.1.16**. 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.
+
+### Using Hallon
+
+First, begin by installing the latest version of Hallon.
 
 ```bash
 gem install hallon
 ```
 
+Great! Now you’re ready to start experimenting. Everything in Hallon, from searching to looking up tracks, requires you to
+have an active Spotify session. You create it by initializing it with your application key.
+
+```ruby
+require 'hallon'
+
+session = Hallon::Session.initialize IO.read('./spotify_appkey.key')
+```
+
+Now that you have your session you may also want to login (even though you can still do a few things without logging in).
+
+```ruby
+session.login!('username', 'password')
+```
+
+You may now experiment with just about anything. For an API reference, please see [Hallon’s page at rdoc.info](http://rdoc.info/github/Burgestrand/Hallon/master/frames).
+As a starter tip, many objects can be constructed by giving it a Spotify URI, like this.
+
+```ruby
+track = Hallon::Track.new("spotify:track:1ZPsdTkzhDeHjA5c2Rnt2I").load
+artist = track.artist.load
+
+puts "#{track.name} by #{artist.name}"
+```
+
+### If you want to play audio…
+
 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:
 
 ```bash
@@ -20,6 +62,14 @@ gem install hallon-openal
 
 For more information about audio support in Hallon, see the section "Audio support" below.
 
+### Contact details
+
+- __Got questions?__ Ask on the mailing list: <https://groups.google.com/d/forum/ruby-hallon>
+- __Found a bug?__ Report an issue: <https://github.com/Burgestrand/Hallon/issues/new>
+- __Have feedback?__ I ❤ feedback! Please send it to the mailing list.
+
+If you for some reason cannot use the mailing list or GitHub issue tracker you may contact me directly. My email is found on [my GitHub profile](https://github.com/Burgestrand), and I’m also available as [@burgestrand on twitter](https://twitter.com/Burgestrand).
+
 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.
@@ -82,8 +132,17 @@ 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.
 
 ```ruby
+require 'hallon'
+require 'hallon-openal'
+
+session = Hallon::Session.initialize(IO.read('./spotify_appkey.key'))
+session.login!('username', 'password')
+
+track = Hallon::Track.new("spotify:track:1ZPsdTkzhDeHjA5c2Rnt2I")
+track.load
+
 player = Hallon::Player.new(session, Hallon::OpenAL)
-player.play(loaded_track)
+player.play!(track)
 ```
 
 Available drivers are:
@@ -97,9 +156,6 @@ For information on how to write your own audio driver, see [Hallon::ExampleAudio
 Finally, here are some important notes
 --------------------------------------
 
-### [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.
-
 ### 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.
 
@@ -112,10 +168,6 @@ 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.
 
-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. :)
@@ -135,6 +187,8 @@ 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
 
+[How to install libspotify]: https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify
+
 [API page for Hallon::Observable]: http://rubydoc.info/github/Burgestrand/Hallon/master/Hallon/Observable
 
 [Hallon::Enumerator]:         http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Enumerator

data/dev/login.rb

@@ -1,16 +1,5 @@
-$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']
+require_relative '../examples/example_support'
+session = Hallon::Session.instance
 
 binding.pry

data/examples/adding_tracks_to_playlist.rb

@@ -1,52 +1,54 @@
 # coding: utf-8
 
-$LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
+# Require support code, used by all the examples.
+require_relative 'example_support'
+session = Hallon::Session.instance
 
-require 'hallon'
-require './spec/support/config'
+puts
+puts "Hi there! I am adding_tracks_to_playlist.rb. You and me, we will manipulate some playlists today.
+We shall add a few tracks to a playlist of your choice."
 
-##
-# 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
+playlist_uri = loop do
+  uri = prompt_link("Give me a Spotify URI to a playlist to modify (e. g. spotify:playlist:…)")
+  break uri if uri
+end
 
-session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
-  on(:log_message) do |message|
-    puts "[LOG] #{message}"
-  end
+puts
+puts "Now I need the tracks we should add to it. Give them all to me. End it with a blank line."
+track_uris = []
+loop do
+  uri = prompt_link("Give me a Spotify URI to a track")
+  track_uris << uri
+  break unless uri
 end
+track_uris.compact!
 
-session.login!(ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD'])
-puts "Successfully logged in!"
+puts "Great. We’ll be adding these babies to #{playlist_uri}."
+puts track_uris.join("\n")
+puts
 
-# 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? }
+# 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
+puts "Loading playlist #{playlist_uri}."
+playlist = Hallon::Playlist.new(playlist_uri).load
+puts "(it has #{playlist.size} tracks)"
 
 # 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.
+position = 0
 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
 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? }
+# We allow a timeout of 30 seconds. These things sometimes take a long time.
+playlist.upload
 
 puts "We’re done!"

data/examples/example_support.rb

@@ -0,0 +1,100 @@
+# coding: utf-8
+
+# Hello there, and welcome!
+#
+# My name is example_support.rb, and I shall be your loyal servant. What you see here
+# is all my offerings I have for today. Of course, I shall gladly point out to you what
+# each and every one of these offers bring you.
+#
+# 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!
+
+# 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 = {})
+  print(string + ': ')
+  $stdout.flush
+  system("stty -echo") if options[:hide]
+  gets.chomp
+ensure
+  if options[:hide]
+    system("stty echo")
+    puts
+  end
+end
+
+# Like before, this piece of me is not of much important. It is only to make sure you do
+# not try to feed me propaganda. Move along.
+def prompt_link(string)
+  loop do
+    uri = prompt(string)
+    if uri.empty?
+      break
+    elsif Hallon::Link.valid?(uri)
+      break uri
+    else
+      puts "Please enter a valid Spotify URI (or just enter to quit)."
+    end
+  end
+end
+
+# Making sure you receive the latest of the latest. Hallon does not wish to
+# be replaced by older versions when showing you the shiny.
+$LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
+require 'hallon'
+
+# This is a quick sanity check, to make sure we have all the necessities in order.
+appkey_path = File.expand_path('./spotify_appkey.key')
+unless File.exists?(appkey_path)
+  abort <<-ERROR
+    Your Spotify application key could not be found at the path:
+      #{appkey_path}
+
+    Please adjust the path in examples/common.rb or put your application key in:
+      #{appkey_path}
+
+    You may download your application key from:
+      https://developer.spotify.com/en/libspotify/application-key/
+  ERROR
+end
+
+# And now, before I ask you for your jewels, I shall instill within you a sense of
+# belonging and comfort. This is in order to make you less surprised about my rude
+# questions.
+puts "Hallon’s interactive examples run live against Spotify, and as such
+they require actual login credentials before they may run."
+
+# Spotify requires a rite of passage. It’s own variant of “open sesame”, so we will
+# ask you to provide them with your information.
+hallon_username = prompt("Please enter your spotify username")
+hallon_password = prompt("Please enter your spotify password", hide: true)
+hallon_appkey   = IO.read(appkey_path)
+
+# Make sure the credentials are there. We don’t want to go without them.
+if hallon_username.empty? or hallon_password.empty?
+  abort <<-ERROR
+    Sorry, you must supply both username and password for Hallon to be able to log in.
+
+    You may also edit examples/common.rb by setting your username and password directly.
+  ERROR
+end
+
+# Finally, we log in, making sure we show you just about everything Spotify tells us
+# for the entire coming session.
+session = Hallon::Session.initialize(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!(hallon_username, hallon_password)
+
+puts "Successfully logged in!"
+# that is all for me. Thank you, I will see you again!

data/examples/playing_audio.rb

@@ -1,8 +1,8 @@
 # coding: utf-8
 
-$LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
-
-require 'hallon'
+# Require support code, used by all the examples.
+require_relative 'example_support'
+session = Hallon::Session.instance
 
 begin
   require 'hallon/openal'
@@ -11,64 +11,28 @@ rescue LoadError => e
   abort "[ERROR] Could not load gem 'hallon-openal', please install with 'gem install hallon-openal'"
 end
 
-require_relative '../spec/support/config'
-
-# Utility
-def say(string)
-  # system('say', string)
-end
-
-def tell(string)
-  puts(string)
-  say(string)
-end
-
-def prompt(string)
-  print(string + ': ')
-  $stdout.flush
-  say(string)
-  gets.chomp
-end
-
-# Hallon set-up.
-
-session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
-  on(:connection_error) do |error|
-    Hallon::Error.maybe_raise(error)
-  end
-
-  on(:logged_out) do
-    abort "[FAIL] Logged out!"
-  end
-end
-
 player = Hallon::Player.new(session, Hallon::OpenAL)
 
 # Program flow.
 
-session.login!(ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD'])
-
 search = loop do
   query  = prompt("Enter a search term for a track you’d like to play")
   search = Hallon::Search.new(query)
 
-  tell "Searching for “#{search.query}”…"
-  session.wait_for do
-    search.loaded? or Hallon::Error.maybe_raise(search.status, ignore: :is_loading)
-  end
+  puts "Searching for “#{query}”…"
+  search.load
 
   if search.tracks.size.zero?
-    tell "No results for “#{search.query}”."
+    puts "No results for “#{search.query}”."
     next
   else
     break search
   end
 end
 
-tracks = search.tracks[0...10]
-session.wait_for { tracks.all?(&:loaded?) }
+tracks = search.tracks[0...10].map(&:load)
 
-tell "Results for “#{search.query}”: "
+puts "Results for “#{search.query}”: "
 tracks.each_with_index do |track, index|
   puts "  [#{index + 1}] #{track.name} — #{track.artist.name} (#{track.to_link.to_str})"
 end
@@ -80,10 +44,10 @@ track = loop do
   if track = tracks[index - 1]
     break track
   else
-    tell "No such track."
+    puts "No such track."
   end
 end
 
-tell "Alright! Playing “#{track.name}” by “#{track.artist.name}”."
+puts "Alright! Playing “#{track.name}” by “#{track.artist.name}”."
 player.play!(track)
-tell "Done! This was “#{track.name}” by “#{track.artist.name}”. Bye bye!"
+puts "Done! This was “#{track.name}” by “#{track.artist.name}”. Bye bye!"