spot 0.1.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/run_spec.rb

data/.rspec

@@ -0,0 +1,5 @@
+--color
+-fs
+-Ilib
+-Ispec
+--require spec_helper

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/README.markdown

@@ -0,0 +1,255 @@
+# Spot
+
+A Ruby implementation of the [Spotify Meta API](http://developer.spotify.com/en/metadata-api/overview/).
+
+This gem is used internally at the [Radiofy](http://radiofy.se) project.
+
+Follow me on [Twitter](http://twitter.com/linusoleander) for more info and updates.
+
+## How to use
+
+### Find a song
+
+The `Spot.find_song` method returns the first hit.
+
+```` ruby
+Spot.find_song("Like Glue")
+````
+
+### Find all songs
+
+The `find_all_songs` method returns a list of `Song` objects.
+
+```` ruby
+Spot.find_all_songs("Like Glue")
+````
+
+### Find an artist
+
+The `Spot.find_artist` method returns the first hit.
+
+```` ruby
+Spot.find_artist("Madonna")
+````
+
+### Find all artists
+
+The `find_all_artists` method returns a list of `Artist` objects.
+
+```` ruby
+Spot.find_all_artists("Madonna")
+````
+
+### Find an album
+
+The `Spot.find_album` method returns the first hit.
+
+```` ruby
+Spot.find_album("Old Skool Of Rock")
+````
+
+### Find all albums
+
+The `find_all_albums` method returns a list of `Album` objects.
+
+```` ruby
+Spot.find_all_albums("Old Skool Of Rock")
+````
+
+### Find best match
+
+The `prime` method makes it possible to fetch the best matching result based on the ingoing argument.
+
+Here is what is being returned *without* the `prime` method.
+ 
+    >> Spot.find_song("sweet home").result
+    => Home Sweet Home - Mötley Crüe
+
+Here is what is being returned *with* the `prime` method.
+    
+    >> Spot.prime.find_song("sweet home").result
+    => Sweet Home Alabama - Lynyrd Skynyrd
+
+The `prime` method will reject data (songs, artists and albums) that contains any of the [these words](https://github.com/oleander/Spot/blob/master/lib/spot/exclude.yml).
+
+Here is the short version.
+
+- tribute
+- cover
+- remix
+- live
+- club mix
+- karaoke
+- remaster
+- club version
+- demo
+- made famous by
+- remixes
+- instrumental
+- ringtone
+
+Take a look at the [source code](https://github.com/oleander/Spot/blob/master/lib/spot.rb#L94) for more information.
+
+### Specify a territory
+
+All songs in Spotify isn't available everywhere.  
+Therefore it might be usefull to specify a location, also know as a *territory*.
+
+If you for example want to find all songs available in Sweden, then you might do something like this.
+
+```` ruby
+Spot.territory("SE").find_song("Sweet Home Alabama")
+````
+
+You can find the complete territory list [here](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+
+### Filter ingoing arguments
+
+Sometimes it may be useful to filer ingoing params.  
+You can filter the ingoing string by using the `strip` method.
+
+```` ruby
+Spot.strip.find_song("3. Who's That Chick ? feat.Rihanna [Singel Version] - (Single)")
+````
+
+This is the string that is being passed to Spot.
+
+    "who's that chick ?"
+
+Take a look at the [source code](https://github.com/oleander/Spot/blob/master/lib/spot.rb#L136) if you want to know what regexp is being used.
+
+### Specify a page
+
+You can easily select any page you want by defining the `page` method.
+
+```` ruby
+Spot.page(11).find_song("sweet home")
+````
+
+The default page is of course `1`. :)
+
+### Combine methods
+
+You can easily combine method like this.
+
+```` ruby
+Spot.page(11).territory("SE").prime.strip.find_song("sweet home")
+````
+
+## Data to work with
+
+As soon as the `result` or `results` method is applied to the query a request to Spotify is made.
+
+Here is an example using the `result` method.
+
+    >> song = Spot.find_song("sweet home").result
+    
+    >> puts song.title
+    => Home Sweet Home
+    
+    >> puts song.class
+    => SpotContainer::Song
+ 
+Here is an example using the `results` method.
+   
+    >> songs = Spot.find_all_songs("sweet home").results
+    >> puts songs.count
+    => 100
+
+### Base
+
+All classes, `Song`, `Artist` and `Album` share these methods.
+
+- **popularity** (*Float*) Popularity acording to Spotify. From `0.0` to `1.0`.
+- **href** (*String*) Url for the specific object.
+Default is a spotify url on this format: `spotify:track:5DhDGwNXRPHsMApbtVKvFb`.
+`http` may be passed as a string, which will return an Spotify HTTP Url on this format: `http://open.spotify.com/track/5DhDGwNXRPHsMApbtVKvFb`.
+- **available?** (*Boolean*) Takes one argument, a territory. Returns true if the object is accessible in the given region.
+Read more about it in the *Specify a territory* section above.
+- **to_s** (*String*) A string representation of the object.
+- **valid?** (*Boolean*) Returns true if the object is valid, a.k.a is accessible in the given territory. 
+If no territory is given, this will be true.
+- **name** (*String*) Name of the `Song`, `Artist` or `Album`. This method will return the same thing as `Song#title`.
+
+### Song
+
+Methods available for the `Song` class.
+
+- **length** (*Fixnum*) Length in seconds.
+- **title** (*String*) Song title.
+- **to_s** (*String*) String representation of the object in this format: *song - artist*.
+- **artist** (*Artist*) The artist.
+- **album** (*Album*) The album.
+
+### Artist
+
+Methods available for the `Artist` class.
+
+- **name** (*String*) Name of the artist.
+- **to_s** (*String*) Same as above.
+
+### Album
+
+Methods available for the `Album` class.
+    
+- **artist** (*Artist*) The artist.
+
+### Spot
+
+This one is easier to explain in plain code.
+
+```` ruby
+spot = Spot.find_song("kaizers orchestra")
+
+puts spot.num_results # => 188
+puts spot.limit       # => 100
+puts spot.offset      # => 0
+puts spot.query       # => "kaizers orchestra"
+````
+
+- **num_results** (*Fixnum*) The amount of hits.
+- **limit** (*Fixnum*) The amount of results on each page.
+- **offset** (*Fixnum*) Unknown.
+- **query** (*String*) The search param that was passed to Spotify.
+
+## Request limit!
+
+**Be aware**: Spotify has an request limit set for 10 requests per second.  
+Which means that you can't just use it like this.
+
+```` ruby
+["song1", "song2" ... ].each do |song|
+  Spot.find_song(song)
+  # Do something with the data.
+end
+````
+
+Instead use something like [Wire](https://github.com/oleander/Wire) to limit the amount of requests per seconds.
+
+```` ruby
+require "rubygems"
+require "wire"
+require "spot"
+
+wires = []
+["song1", "song2" ... ].each do |s|
+  wires << Wire.new(max: 10, wait: 1, vars: [s]) do |song|
+    Spot.find_song(song)
+    # Do something with the data.
+  end
+end
+
+wires.map(&:join)
+````
+
+## How do install
+
+    [sudo] gem install spot
+
+## Requirements
+
+*Spot* is tested in *OS X 10.6.7* using Ruby *1.8.7*, *1.9.2*.
+
+## License
+
+*Spot* is released under the *MIT license*.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/spot.rb

@@ -0,0 +1,214 @@
+# -*- encoding : utf-8 -*-
+require "spot/song"
+require "spot/artist"
+require "spot/album"
+require "json/pure"
+require "rest-client"
+require "uri"
+require "levenshteinish"
+require "rchardet19"
+require "iconv"
+require "yaml"
+
+class Spot
+  def initialize
+    @methods = {
+      :artists => {
+        :selector => :artists,
+        :class    => SpotContainer::Artist,
+        :url      => generate_url("artist")
+      }, 
+      :songs => {
+        :selector => :tracks,
+        :class    => SpotContainer::Song,
+        :url      => generate_url("track")
+      },
+      :albums => {
+        :selector => :albums,
+        :class    => SpotContainer::Album,
+        :url      => generate_url("album")
+      }
+    }
+    
+    @cache = {}
+    
+    @exclude = YAML.load(File.read("#{File.dirname(__FILE__)}/spot/exclude.yml"))
+    
+    @config = {
+      :exclude    => 2,
+      :popularity => 7,
+      :limit      => 0.7,
+      :offset     => 10
+    }
+    
+    @options = {}
+  end
+  
+  def self.method_missing(method, *args, &blk)
+    Spot.new.send(method, *args, &blk)
+  end
+  
+  def method_missing(method, *args, &blk)
+    if method.to_s =~ /^find(_all)?_([a-z]+)$/i 
+      find($2, !!$1, args.first)
+    elsif scrape and content["info"].keys.include?(method.to_s)
+       content["info"][method.to_s]
+    else
+      super(method, *args, &blk)
+    end
+  end
+  
+  def page(value)
+    tap { @page = value }
+  end
+  
+  def prime
+    tap { @prime = true }
+  end
+  
+  def prefix(value)
+    tap { @prefix = value }
+  end
+  
+  def find(type, all, s)
+    tap {
+      @search = s
+      @type = all ? type.to_sym : "#{type}s".to_sym
+      raise NoMethodError.new(@type) unless @methods.keys.include?(@type)
+    }
+  end
+  
+  def results
+    @_results ||= scrape
+  end
+  
+  def strip
+    tap { @strip = true }
+  end
+  
+  def territory(value)
+    tap { @options.merge!(:territory => value) }
+  end
+  
+  def result
+    @prime ? results.map do |r|
+      
+      song, artist = type_of(r)
+      
+      match = "#{song} #{artist}".split(" ")
+      raw = clean!(search).split(" ")
+
+      if raw.length < match.length
+        diff = match - raw
+        res = diff.length.to_f/match.length
+      else
+        diff = raw - match
+        res = diff.length.to_f/raw.length
+      end
+
+      if diff.length > 1 and not match.map{ |m| diff.include?(m) }.all?
+        res =+ diff.map do |value|
+          match.map do |m|
+            Levenshtein.distance(value, m)
+          end.inject(:+)
+        end.inject(:+) / @config[:offset]
+      end
+      
+      [res - r.popularity/@config[:popularity], r]
+    end.reject do |distance, value|
+      exclude?(value.to_s)
+    end.sort_by do |distance, _|
+      distance
+    end.map(&:last).first : results.first
+  end
+  
+  def type_of(r)
+    if @type == :songs
+      return r.name.to_s, r.artist.name.to_s
+    elsif @type == :artists
+      return r.song.title.to_s, r.name.to_s
+    else
+      return "", r.artist.to_s
+    end
+  end
+  
+  def clean!(string)
+    string.strip!
+    
+    # Song - A + B + C => Song - A
+    # Song - A abc/def => Song - A abc
+    # Song - A & abc def => Song - A
+    # Song - A "abc def" => Song - A
+    # Song - A [B + C] => Song - A
+    # Song A B.mp3 => Song A B
+    # Song a.b.c.d.e => Song a b c d e
+    # 10. Song => Song
+    [/\.[a-z0-9]{2,3}$/, /\[[^\]]*\]/,/".*"/, /'.*'/, /[&|\/|\+][^\z]*/, /^(\d+.*?[^a-z]+?)/i].each do |reg|
+      string = string.gsub(reg, '').strip
+    end
+    
+    [/\(.+?\)/m, /feat(.*?)\s*[^\s]+/i, /[-]+/, /[\s]+/m, /\./, /\_/].each do |reg|
+       string = string.gsub(reg, ' ').strip
+    end
+    
+    {"ä" => "a", "å" => "a", "ö" => "o"}.each do |from, to|
+      string.gsub!(/#{from}/i, to)
+    end
+    
+    string.gsub(/\A\s|\s\z/, '').gsub(/\s+/, ' ').strip.downcase
+  rescue Encoding::CompatibilityError
+    return string
+  end
+  
+  def exclude?(compare)
+    @exclude.map { |value| !! compare.match(/#{value}/i) }.any?
+  end
+  
+  private
+    def url
+      @url ||= @methods[@type][:url].
+        gsub(/<SEARCH>/, URI.escape(search)).
+        gsub(/<PAGE>/, (@page || 1).to_s)
+    end
+    
+    def search(force = false)
+      return @_search if @_search
+      @_search = ""
+      @_search = ((@strip or force) ? clean!(@prefix) + " " : @prefix + " ") if @prefix
+      @_search += ((@strip or force) ? clean!(@search) : @search)
+    end
+    
+    def scrape
+      return @cache[@type] if @cache[@type]
+      
+      @cache[@type] = []; content[@methods[@type][:selector].to_s].each do |item|
+        item = @methods[@type][:class].new(item.merge(@options)) 
+        @cache[@type] << item if item.valid?
+      end
+      @cache[@type]
+    end
+    
+    def content
+      data = download
+      cd = CharDet.detect(data)
+      data = cd.confidence > 0.6 ? Iconv.conv(cd.encoding, "UTF-8", data) : data
+      @content ||= JSON.parse(data)
+    end
+    
+    def download
+      @download ||= RestClient.get(url, :timeout => 10)
+    end
+    
+    def errors(error)
+      case error.to_s
+      when "403 Forbidden"
+        raise SpotContainer::RequestLimitError.new(url)
+      else
+        raise error
+      end
+    end
+    
+    def generate_url(type)
+      "http://ws.spotify.com/search/1/#{type}.json?q=<SEARCH>&page=<PAGE>"
+    end
+end