rockstar 0.6.3 → 0.6.4

data/README.md

@@ -14,12 +14,16 @@ Please initialize your api key and secret before using the api:
 Here is an example lastfm.yml:
 
     api_key: "API"
-    api_secret: "SECRET"    
+    api_secret: "SECRET"
 
 If you want to use the api in an rails app, you could add an initializer in config/initializers/lastm.rb and load a config/lastfm.yml file.
 
     rails_root = ENV['RAILS_ROOT'] || File.dirname(__FILE__) + '/../..'
     Rockstar.lastfm =  YAML.load_file(rails_root + '/config/lastfm.yml')
+    
+Alternatively you can provide a hash with the api key and secret:
+
+    Rockstar.lastfm = {:api_key => "API", :api_secret => "SECRET"}
 
 ## Users
 
@@ -35,9 +39,9 @@ If you want to use the api in an rails app, you could add an initializer in conf
     puts "#{user.username}'s Top Tracks"
     puts "=" * (user.username.length + 13)
     user.top_tracks.each { |t| puts "(#{t.playcount}) #{t.name}" }
-    
+
 ## Albums
-    
+
     album = Rockstar::Album.new('Carrie Underwood', 'Some Hearts', :include_info => true)
 
     puts "Album: #{album.name}"
@@ -46,8 +50,13 @@ If you want to use the api in an rails app, you could add an initializer in conf
     puts "Release Date: #{album.release_date.strftime('%m/%d/%Y')}"
 
 ## Artists
-    
-    artist = Rockstar::Artist.new('Carrie Underwood')
+
+If you want to load all informations about an artist or any other
+object, you have to add `:include_info => true` .
+
+    artist = Rockstar::Artist.new('Carrie Underwood', :include_info => true)
+
+    puts artist.url
 
     puts 'Top Tracks'
     puts "=" * 10
@@ -58,9 +67,9 @@ If you want to use the api in an rails app, you could add an initializer in conf
     puts 'Similar Artists'
     puts "=" * 15
     artist.similar.each { |a| puts "(#{a.match}%) #{a.name}" }
-    
-## Tags    
-    
+
+## Tags
+
     tag = Rockstar::Tag.new('country')
 
     puts 'Top Albums'
@@ -70,28 +79,17 @@ If you want to use the api in an rails app, you could add an initializer in conf
 
     puts 'Top Tracks'
     tag.top_tracks.each { |t| puts "(#{t.count}) #{t.name} by #{t.artist}" }
-    
-## Tracks
-    
-    track = Rockstar::Track.new('Carrie Underwood', 'Before He Cheats')
-    puts 'Fans'
-    puts "=" * 4
-    track.fans.each { |u| puts "(#{u.weight}) #{u.username}" }
-    
-    # Love a song, session_key is returned by Rockstar::Auth. See Rockstar::TokenAuth or
-    # examples/scrobble.rb for a complete example
-    track.love(session_key)
 
 ## Geo
 
     geo = Rockstar::Geo.new
-      
-    # Get events for a lat/long  
+
+    # Get events for a lat/long
     geo.events(:lat => 50.0, :long => 12.3).each{|e| p "#{e.title} at #{e.venue.name}"}
-    
+
     # Get events for a location
     geo.events(:location => 'london').each{|e| p "#{e.title} at #{e.venue.name}"}
-    
+
     # To get a list of possible locations use
     geo.metros("germany").each{|m| p m.name}
 
@@ -100,17 +98,27 @@ If you want to use the api in an rails app, you could add an initializer in conf
 
     a = Rockstar::Auth.new
     token = a.token
-    
+
     puts
     puts "Please open http://www.last.fm/api/auth/?api_key=#{Rockstar.lastfm_api_key}&token=#{token}"
     puts
     puts "Press enter when done."
-    
+
     gets
-    
+
     session = a.session(token)
 
-You can store the session.key somewhere and use it from now on to identify the user.
+You can store the session.key somewhere and use it from now on to identify the user. More
+details can be found in Rockstar::Auth or examples/scrobble.rb
+
+## Tracks
+
+    track = Rockstar::Track.new('Carrie Underwood', 'Before He Cheats')
+    puts 'Fans'
+    puts "=" * 4
+    track.fans.each { |u| puts "(#{u.weight}) #{u.username}" }
+
+    track.love(session.key)
 
 ## Scrobbling
 
@@ -123,7 +131,7 @@ You can store the session.key somewhere and use it from now on to identify the u
     track.updateNowPlaying(Time.now, session.key)
 
 ## Note on Patches/Pull Requests
- 
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
@@ -135,3 +143,7 @@ You can store the session.key somewhere and use it from now on to identify the u
 ## Copyright
 
 Copyright (c) 2007-2011 John Nunemaker, Bodo "Bitboxer" Tasche, Nick "zapnap" Plante. See LICENSE for details.
+
+## Acknowledgements
+
+Thanks to [putpat.tv](http://www.putpat.tv) for sponsering the work on the rockstar gem.

data/VERSION

@@ -1 +1 @@
-0.6.3
+0.6.4

data/examples/artist.rb

@@ -4,7 +4,9 @@ require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'rocksta
 # You can find them here : http://www.lastfm.de/api/account
 Rockstar.lastfm = YAML.load_file(File.join(File.dirname(__FILE__), 'lastfm.yml'))
 
-artist = Rockstar::Artist.new('Metallica')
+artist = Rockstar::Artist.new('Metallica', :include_info => true)
+
+puts artist.url
 
 puts 'Top Tracks'
 puts "=" * 10

data/lib/rockstar.rb

@@ -23,27 +23,22 @@ require 'rockstar/tag'
 require 'rockstar/track'
 require 'rockstar/venue'
 
-require 'rockstar/simpleauth'
 require 'rockstar/auth'
 require 'rockstar/session'
-require 'rockstar/tokenauth'
-require 'rockstar/scrobble'
-require 'rockstar/playing'
-
 require 'rockstar/rest'
 
 module Rockstar
   extend self
-  
+
   def lastfm=(args)
-    @api_key    = args["api_key"]
-    @api_secret = args["api_secret"]
+    @api_key    = args["api_key"] || args[:api_key]
+    @api_secret = args["api_secret"] || args[:api_secret]
   end
-  
+
   def lastfm_api_key
     @api_key
   end
-  
+
   def lastfm_api_secret
     @api_secret
   end

data/lib/rockstar/album.rb

@@ -1,35 +1,35 @@
 # Getting information about an album such as release date and the summary or description on it is very easy.
-# 
+#
 #   album = Rockstar::Album.new('Carrie Underwood', 'Some Hearts', :include_info => true)
-# 
+#
 #   puts "Album: #{album.name}"
 #   puts "Artist: #{album.artist}"
 #   puts "URL: #{album.url}"
 #   puts "Release Date: #{album.release_date.strftime('%m/%d/%Y')}"
-# 
+#
 # Would output:
 #
 #   Album: Some Hearts
 #   Artist: Carrie Underwood
 #   URL: http://www.last.fm/music/Carrie+Underwood/Some+Hearts
 #   Release Date: 11/15/2005
-# 
+#
 module Rockstar
   class Album < Base
     attr_accessor :artist, :artist_mbid, :name, :mbid, :playcount, :rank, :url, :release_date
     attr_accessor :image_large, :image_medium, :image_small, :summary, :content, :images
-    
+
     # needed on top albums for tag
     attr_accessor :count, :streamable
-    
+
     # needed for weekly album charts
     attr_accessor :chartposition
-    
+
     class << self
       def find(artist, name, o={})
         new(artist, name, o)
       end
-      
+
       def new_from_xml(xml, doc=nil)
         name             = (xml).at(:name).inner_html                  if (xml).at(:name)
         name             = xml['name']                                 if name.nil? && xml['name']
@@ -53,7 +53,7 @@ module Rockstar
       options = {:include_info => false}.merge(o)
       load_info if options[:include_info]
     end
-    
+
     def load_info(xml=nil)
       unless xml
         doc = self.class.fetch_and_parse("album.getInfo", {:artist => @artist, :album =>@name})
@@ -61,7 +61,7 @@ module Rockstar
       end
 
       return self if xml.nil?
-    
+
       self.artist_mbid    = (xml).at(:artist)['mbid']                   if (xml).at(:artist) && (xml).at(:artist)['mbid']
       self.artist_mbid    = (xml).at(:artist).at(:mbid).inner_html      if artist_mbid.nil? && (xml).at(:artist) && (xml).at(:artist).at(:mbid)
       self.mbid           = (xml).at(:mbid).inner_html                  if (xml).at(:mbid)
@@ -75,16 +75,16 @@ module Rockstar
 
       self.release_date   = Base.parse_time((xml).at(:releasedate).inner_html.strip) if (xml).at(:releasedate)
       self.chartposition  = rank
-      
+
       self.images = {}
       (xml/'image').each {|image|
         self.images[image['size']] = image.inner_html if self.images[image['size']].nil?
       }
-      
+
       self.image_large    = images['large']
       self.image_medium   = images['medium']
       self.image_small    = images['small']
-      
+
       # needed on top albums for tag
       self.count          = xml['count'] if xml['count']
       self.streamable     = xml['streamable'] if xml['streamable']
@@ -92,17 +92,12 @@ module Rockstar
       self
     end
 
-    def tracks
-      warn "[DEPRECATION] `tracks` is deprecated. The current api doesn't offer this function"
-      []
-    end
-    
     def image(which=:small)
       which = which.to_s
-      raise ArgumentError unless ['small', 'medium', 'large', 'extralarge'].include?(which)  
+      raise ArgumentError unless ['small', 'medium', 'large', 'extralarge'].include?(which)
       if (self.images.nil?)
         load_info
-      end    
+      end
       self.images[which]
     end
   end

data/lib/rockstar/artist.rb

@@ -1,19 +1,19 @@
 # Below are examples of how to find an artists top tracks and similar artists.
-# 
+#
 #   artist = Rockstar::Artist.new('Carrie Underwood')
-# 
+#
 #   puts 'Top Tracks'
 #   puts "=" * 10
 #   artist.top_tracks.each { |t| puts "#{t.name}" }
-# 
+#
 #   puts
-# 
+#
 #   puts 'Similar Artists'
 #   puts "=" * 15
 #   artist.similar.each { |a| puts "(#{a.match}%) #{a.name}" }
-# 
+#
 # Would output something similar to:
-# 
+#
 #   Top Tracks
 #   ==========
 #   (8797) Before He Cheats
@@ -31,7 +31,7 @@
 #   (1854) That's Where It Is
 #   (1786) I Ain't in Checotah Anymore
 #   (1596) The Night Before (Life Goes On)
-#   
+#
 #   Similar Artists
 #   ===============
 #   (100%) Rascal Flatts
@@ -61,10 +61,10 @@ module Rockstar
     attr_accessor :name, :mbid, :listenercount, :playcount, :rank, :url, :thumbnail
     attr_accessor :summary, :content, :images, :count, :streamable
     attr_accessor :chartposition
-    
+
     # used for similar artists
     attr_accessor :match
-    
+
     class << self
       def new_from_xml(xml, doc=nil)
         # occasionally name can be found in root of artist element (<artist name="">) rather than as an element (<name>)
@@ -76,7 +76,7 @@ module Rockstar
         artist
       end
     end
-    
+
     def initialize(name, o={})
       raise ArgumentError, "Name or mbid is required" if name.blank? && o[:mbid].blank?
       @name = name
@@ -89,7 +89,7 @@ module Rockstar
     def load_info(xml=nil)
       unless xml
         params = @mbid.blank? ? {:artist => @name} : {:mbid => @mbid}
-        
+
         doc = self.class.fetch_and_parse("artist.getInfo", params)
         xml = (doc / :artist).first
       end
@@ -112,10 +112,10 @@ module Rockstar
       (xml/'image').each {|image|
         self.images[image['size']] = image.inner_html if self.images[image['size']].nil?
       }
-      
+
       self.thumbnail      = self.images['small']
       self.match          = (xml).at(:match).inner_html          if (xml).at(:match)
-       
+
       # in top artists for tag
       self.count          = xml['count']                         if xml['count']
       self.streamable     = xml['streamable']                    if xml['streamable']
@@ -124,32 +124,27 @@ module Rockstar
 
       self
     end
-    
-    def current_events(format=:ics)
-      warn "[DEPRECATION] the `current_events` method is deprecated. Please use artist.events"
-      events
-    end
 
     def events(force=false)
       get_instance("artist.getEvents", :events, :event, {:artist => @name}, force)
     end
-    
+
     def similar(force=false)
       get_instance("artist.getSimilar", :similar, :artist, {:artist => @name}, force)
     end
-    
+
     def top_fans(force=false)
       get_instance("artist.getTopFans", :top_fans, :user, {:artist => @name}, force)
     end
-    
+
     def top_tracks(force=false)
       get_instance("artist.getTopTracks", :top_tracks, :track, {:artist => @name}, force)
     end
-    
+
     def top_albums(force=false)
       get_instance("artist.getTopAlbums", :top_albums, :album, {:artist => @name}, force)
     end
-    
+
     def top_tags(force=false)
       get_instance("artist.getTopTags", :top_tags, :tag, {:artist => @name}, force)
     end

data/lib/rockstar/auth.rb

@@ -1,17 +1,34 @@
 module Rockstar
-  
+
+  # = Authentification
+  #
+  # There are 2 ways to get an auth token :
+  #
+  # == Desktop-App
+  # 1. Get a new token to request authorisation:
+  #     token = Rockstar::Auth.new.token
+  # 2. Open a webbrowser with http://www.last.fm/api/auth/?api_key=xxxxxxxxxxx&token=xxxxxxxx
+  # 3. Wait for the User to confirm that he accepted your request.
+  # 4. Continue with "Get the session token"
+  #
+  # == Web-App
+  # 1. Redirect the user to http://www.last.fm/api/auth/?api_key={YOUR_API_KEY}&cb={YOUR_RETURN_URL}
+  # 2. If the user accepts, lastfm will redirect to YOUR_RETURN_URL?token=TOKEN
+  #     token = params[:token]
+  # 3. Continue with "Get the session token"
+  #
+  # == Get the session token
+  # 1. Use the previous token and call
+  #     session = Rockstar::Auth.new.session(token)
+  # 2. Store the session.key and session.username returned. The session.key will not
+  #    expire. It is save to store it into your database.
   class Auth < Base
-    # Returns the token for a session. You have to use
-    # TokenAuth first and then use this class with the token
-    # that is given by last.fm to create a session token
-    # This session token can be stored in your database, it is
-    # not expiring.
-    # See Rockstar::TokenAuth for a detailed example
+
     def session(token)
       doc = self.class.fetch_and_parse("auth.getSession", {:token => token}, true)
       Rockstar::Session.new_from_xml(doc)
     end
-    
+
     def token
       doc = self.class.fetch_and_parse("auth.getToken", {}, true)
       token = (doc).at(:token).inner_html if (doc).at(:token)

data/lib/rockstar/base.rb

@@ -1,30 +1,30 @@
-module Rockstar 
-  
+module Rockstar
+
   API_URL     = 'http://ws.audioscrobbler.com/'
   API_VERSION = '2.0'
-  
+
   class Base
     class << self
       def connection
         @connection ||= REST::Connection.new(API_URL + API_VERSION + "/")
       end
-      
+
       def fetch_and_parse(resource, params = {}, sign_request = false)
         Hpricot::XML(connection.get(resource, sign_request, params))
       end
-      
+
       def get_instance(api_method, instance_name, element, params, sign_request = false)
         rockstar_class = "rockstar/#{element.to_s}".camelize.constantize
         doc      = self.fetch_and_parse(api_method, params, sign_request)
         (doc/element).inject([]) { |elements, el| elements << rockstar_class.new_from_xml(el, doc); elements }
       end
     end
-    
+
     private
       # in order for subclass to use, it must have api_path method
       def get_instance(api_method, instance_name, element, params, force = false, sign_request = false)
         rockstar_class = "rockstar/#{element.to_s}".camelize.constantize
-        
+
         if instance_variable_get("@#{instance_name}").nil? || force
           doc      = self.class.fetch_and_parse(api_method, params, sign_request)
           elements = (doc/element).inject([]) { |elements, el| elements << rockstar_class.new_from_xml(el, doc); elements }
@@ -32,7 +32,7 @@ module Rockstar
         end
         instance_variable_get("@#{instance_name}")
       end
-      
+
       def self.fix_url(url)
         if (!url.blank? && !url.match("^http://"))
           url = "http://#{url}"