hallon 0.0.0 → 0.1.0

data/.autotest

@@ -0,0 +1,6 @@
+require 'autotest/rspec2'
+require 'autotest/growl'
+require 'autotest/fsevent' rescue nil
+
+Autotest::add_discovery { 'rspec2' }
+Autotest::Growl::image_dir = 'ampelmaennchen'

data/.gitignore

@@ -0,0 +1,29 @@
+# Private files
+*.key
+spec/support/config.rb
+tmp/
+libspotify-*
+core.*
+Gemfile.lock
+
+# Extension files
+*.bundle
+
+# Generated by:
+## rcov/cover_me
+coverage/
+coverage.data
+
+## yardoc
+doc/
+.yardoc
+
+## bundler
+.bundle
+
+## jeweler
+pkg
+*.gem
+
+## Mac OS
+.DS_Store

data/.rspec

@@ -0,0 +1,7 @@
+--color
+-fs
+-Ilib
+-Ispec
+--fail-fast
+--require cover_me
+--require spec_helper

data/.yardopts

@@ -0,0 +1,8 @@
+--title "Hallon"
+--list-undoc
+--charset UTF-8
+--readme README.markdown
+--markup markdown
+--private
+lib/**/*.rb
+ext/**/*.c

data/CHANGELOG

@@ -0,0 +1,20 @@
+Hallon’s Changelog
+==================
+
+v0.1.0
+------------------
+Initial, first, release! This version is merely made to
+have a starting point, a point of reference, for future
+releases soon to come.
+
+- Error subsystem is covered (`sp_error_message(error_code)`)
+- Image subsystem is complete, however you can only create images
+  from links at this moment.
+- Session API is partial. Currently you can login, logout, retrieve
+  the logged in user and query user relations.
+- User API is complete, but you can only create users from your
+  currently logged in user (through Session) or from links.
+
+The API is still very young, and I expect a lot of changes to
+happen to it, to make the asynchronous nature of libspotify
+easier to handle.

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2011 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:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY KIM BURGESTRAND ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL KIM BURGESTRAND OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/QUIRKS

@@ -0,0 +1,11 @@
+# Quirks, oddities and general notes about libspotify
+
+## Session
+- `sp_session_release` will segfault (rare)
+- `login` callback fires even if the login fails; instead,
+  `connection_error` will fire a few moments later
+- creating a session, releasing it, and then creating one again
+  will segfault
+
+## Link
+- segfaults if created before a session

data/README.markdown

@@ -0,0 +1,58 @@
+What is 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!
+
+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.
+
+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
+- [Jesper Särnesjö][], creator of [Greenstripes][], making me think of Hallon as an achievable goal
+
+Code samples can be found under `examples/` directory.
+
+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.
+
+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!
+
+### Hallon is unstable
+The API is unstable, my code is likely unstable. Everything should be considered unstable!
+
+### Hallon only supports one session per process
+You can only keep one session with Spotify alive at a time in the same process, due to a limitation of `libspotify`.
+
+### 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.
+
+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 will be kept up to date with the different versions.
+
+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
+[Jesper Särnesjö]: http://jesper.sarnesjo.org/

data/Rakefile

@@ -0,0 +1,75 @@
+# coding: utf-8
+require 'rake'
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+require 'rspec/core/rake_task'
+
+desc "Run all specs (even those requiring logging in to Spotify)"
+RSpec::Core::RakeTask.new('spec:full')
+
+desc "Run all specs like spec:full, but with debug mode and full warnings enabled"
+RSpec::Core::RakeTask.new('spec:debug') do |task|
+  task.skip_bundler = true
+  task.ruby_opts    = '-d -W2'
+end
+
+desc "Run all offline specs"
+RSpec::Core::RakeTask.new('spec') do |task|
+  task.pattern = 'spec/hallon/*_spec.rb'
+  task.rspec_opts = '--tag ~logged_in'
+end
+
+desc "Run the full test suite and generate a coverage report"
+task 'spec:cov' => ['clean', 'spec:full'] do
+  require 'cover_me'
+  require './spec/support/cover_me'
+
+  CoverMe.config.at_exit = proc { `open coverage/index.html` }
+  CoverMe.complete!
+end
+
+desc "Process the Hallon codebase, finding out which Spotify methods are being used"
+task 'spotify:coverage' do
+  require 'set'
+  require 'spotify'
+
+  methods = Spotify.methods(false).map(&:to_s)
+  covered = Set.new(methods)
+  matcher = /Spotify::([\w_]+)[ \(]/
+
+  FileList['lib/**/*.rb'].each do |file|
+    File.read(file).scan(matcher) { |method, _| covered.delete(method) }
+  end
+
+  covered.group_by { |m| m[/[^_]+/] }.each_pair do |group, methods|
+    puts "#{group.capitalize}:"
+    methods.each do |m|
+      puts "  #{m}"
+    end
+    puts
+  end
+
+  puts "Coverage: %.02f%%" % (100 * (1 - covered.size.fdiv(methods.size)))
+end
+
+task :test => :spec
+
+#
+# Custom tasks
+#
+desc "Generates YARD documentation and open it."
+task :doc => :yard do
+  sh 'open doc/index.html'
+end
+
+desc "Remove generated files"
+task :clean do
+  sh 'git clean -fdx --exclude Gemfile.lock --exclude spec/support/config.rb'
+end
+
+task :default => [:spec]

data/Termfile

@@ -0,0 +1,7 @@
+# You wonder what this is?
+# 
+# This is a Termfile, and is used by a gem named “terminitor” that
+# allows me to set up the work environment for Hallon much easier.
+
+run 'bundle exec autotest'
+tab '$EDITOR .'

data/examples/logging_in.rb

@@ -0,0 +1,26 @@
+# coding: utf-8
+require 'hallon'
+require './spec/support/config'
+
+session = Hallon::Session.instance IO.read(ENV['HALLON_APPKEY']) do
+  on(:log_message) do |message|
+    puts "[LOG] #{message}"
+  end
+end
+
+session.login ENV['HALLON_USERNAME'], ENV['HALLON_PASSWORD']
+logged_in  = session.process_events_on(:logged_in) { |error| error }
+
+unless logged_in == :ok
+  abort "[ERROR] (:logged_in) #{Hallon::Error.explain(logged_in)}"
+end
+
+conn_error = session.process_events_on(:connection_error) do |error|
+  session.logged_in? or error
+end
+
+unless conn_error == true
+  abort "[ERROR] (:connection_error) #{Hallon::Error.explain(conn_error)}"
+end
+
+puts "Successfully logged in!"

data/examples/printing_link_information.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+require 'hallon'
+require './spec/support/config'
+
+# Utility
+def prompt(str)
+  print str
+  gets.chomp
+end
+
+# Hallon
+session = Hallon::Session.instance IO.read(ENV['HALLON_APPKEY']) do
+  on(:log_message) do |message|
+    $stderr.puts "[LOG] #{message}"
+  end
+end
+
+while url = prompt("Enter a Spotify URI: ")
+  begin
+    p (link = Hallon::Link.new(url))
+    puts "\tHTTP URL: #{link.to_url}"
+    puts "\tSpotify URI: #{link.to_str}"
+    puts "\tLink type: #{link.type}"
+  rescue ArgumentError => e
+    puts e
+  end
+end

data/hallon.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+require './lib/hallon/version'
+
+Gem::Specification.new do |gem|
+  gem.name     = "hallon"
+  gem.summary  = %Q{Delicious Ruby bindings to the official Spotify API}
+  gem.homepage = "http://github.com/Burgestrand/Hallon"
+  gem.authors  = ["Kim Burgestrand"]
+  gem.email    = 'kim@burgestrand.se'
+  gem.license  = 'GNU AGPL'
+
+  gem.description = IO.read('./README.markdown', encoding: 'utf-8')
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables   = []
+  gem.require_paths = ["lib"]
+
+  gem.version     = Hallon::VERSION
+  gem.platform    = Gem::Platform::RUBY
+  gem.required_ruby_version = '~> 1.9'
+
+  gem.add_dependency 'spotify', '~> 8.0.5'
+  gem.add_development_dependency 'rake', '~> 0.8'
+  gem.add_development_dependency 'rspec', '~> 2'
+  gem.add_development_dependency 'autotest-standalone'
+  gem.add_development_dependency 'autotest-growl'
+  gem.add_development_dependency 'cover_me'
+  gem.add_development_dependency 'yard'
+  gem.add_development_dependency 'rdiscount'
+end

data/lib/hallon.rb

@@ -0,0 +1,34 @@
+# coding: utf-8
+require 'spotify'
+require 'hallon/ext/spotify'
+require 'hallon/ext/ffi'
+
+require 'hallon/synchronizable'
+require 'hallon/observable'
+require 'hallon/linkable'
+
+require 'hallon/version'
+require 'hallon/error'
+require 'hallon/session'
+require 'hallon/link'
+require 'hallon/user'
+require 'hallon/image'
+
+# The Hallon module wraps around all Hallon objects to avoid polluting
+# the global namespace. To start using Hallon, you most likely want to
+# be looking for the documentation on {Hallon::Session}.
+module Hallon
+  # @see Spotify::API_VERSION
+  API_VERSION = Spotify::API_VERSION
+
+  # A regex that matches all Spotify URIs
+  #
+  # @example
+  #   Hallon::URI === "spotify:user:burgestrand" # => true
+  URI = /(spotify:(?:
+    (?:artist|album|track|user:[^:]+:playlist):[a-zA-Z0-9]+
+    |user:[^:]+
+    |search:(?:[-\w$\.+!*'(),]+|%[a-fA-F0-9]{2})+
+    ))
+  /x
+end

data/lib/hallon/error.rb

@@ -0,0 +1,54 @@
+# coding: utf-8
+module Hallon
+  # Thrown by Hallon on libspotify errors.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__error.html
+  class Error < RuntimeError
+    class << self
+      # Given a number or a symbol, find both the symbol and the error
+      # number it represents.
+      #
+      # @param [Symbol, Fixnum] error
+      # @return [[Fixnum, Symbol]] (error code, error symbol)
+      def disambiguate(error)
+        @enum ||= Spotify::enum_type(:error)
+
+        if error.is_a? Symbol
+          error = @enum[symbol = error]
+        else
+          symbol = @enum[error]
+        end
+
+        if error.nil? || symbol.nil?
+          [-1, nil]
+        else
+          [error, symbol]
+        end
+      end
+
+      # Explain a Spotify error with a string message.
+      #
+      # @param [Fixnum, Symbol]
+      # @return [String]
+      def explain(error)
+        Spotify::error_message disambiguate(error)[0]
+      end
+
+      # Raise an {Error} with the given errno, unless it is `0` or `:ok`.
+      #
+      # @param [Fixnum, Symbol] error
+      # @return [nil]
+      def maybe_raise(error)
+        error, symbol = disambiguate(error)
+
+        unless symbol == :ok
+          message = []
+          message << "[#{symbol.upcase}]"
+          message << explain(error)
+          message << "(#{error})"
+          raise Hallon::Error, message.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/hallon/ext/ffi.rb

@@ -0,0 +1,26 @@
+# Custom extensions to the FFI gem.
+#
+# @see https://github.com/ffi/ffi
+module FFI
+  # FFI::Pointer is the underlying class used to read
+  # and write data to pointers. For more information
+  # see the FFI gem.
+  class Pointer
+    type, _ = begin
+      type = FFI.find_type(:size_t)
+      FFI::TypeDefs.find do |(name, t)|
+        method_defined? "read_#{name}" if t == type
+      end
+    end
+
+    unless type.nil?
+      # Read N `size_t` from the start of the pointer.
+      #
+      # @param [Integer] count how many to read
+      # @return a type of appropriate size
+      define_method(:read_size_t) do |*args|
+        public_send("read_#{type}", *args)
+      end
+    end
+  end
+end