scrobbler-ng 2.0.5 → 2.0.6

data/.gitignore

@@ -12,3 +12,5 @@ catalog.xml
 tmp
 .project
 .loadpath
+view*.sh
+.chomrium/

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
-:patch: 5
+:patch: 6
 :major: 2
 :build: 
 :minor: 0

data/lib/scrobbler/base.rb

@@ -19,6 +19,10 @@ module Scrobbler
     # By default, there is no cache
     @@cache = []
     
+    # Add a cache provider to the caching system
+    #
+    # @param [CacheProvider] cache A instance of a cache provider.
+    # @return [void]
     def Base.add_cache(cache)
       @@cache << cache
     end
@@ -28,7 +32,7 @@ module Scrobbler
     # This key will be used by all Scrobbler classes and objects.
     #
     # @param [String] api_key The default API key.
-    # @return [nil]
+    # @return [void]
     def Base.api_key=(api_key) 
       @@api_key = api_key
     end
@@ -38,7 +42,7 @@ module Scrobbler
     # This secret will be used by all Scrobbler classes and objects.
     #
     # @param [String] secret The default API secret.
-    # @return [nil]
+    # @return [void]
     def Base.secret=(secret)
       @@secret = secret
     end
@@ -85,7 +89,7 @@ module Scrobbler
     # Load a request from cache if possible
     #
     # @param [Hash] parameters The parameters passed as URL params.
-    # @return [String,nil]
+    # @return [String]
     def Base.load_from_cache(parameters)
       @@cache.each do |cache|
         if cache.has?(parameters)
@@ -99,7 +103,7 @@ module Scrobbler
     #
     # @param [String] xml The answer from the Last.fm API
     # @param [Hash] parameters The parameters passed as URL params.
-    # @return [nil]
+    # @return [void]
     def Base.save_to_cache(xml, parameters)
       @@cache.each do |cache|
         if cache.writable? then
@@ -184,7 +188,7 @@ module Scrobbler
     # Load information into instance variables.
     #
     # @param [Hash<String,Symbol>] data Each entry will be stored as a variable.
-    # @return [nil]
+    # @return [void]
     def populate_data(data = {})
       data.each do |key, value|
         instance_variable_set("@#{key.to_s}", value)
@@ -199,6 +203,40 @@ module Scrobbler
     def request(api_method, parameters = {}, request_method = 'get')
       Base.request(api_method, parameters, request_method)
     end
+    
+    # Generic request method for the most Library funtions
+    #
+    # @param [String,Symbol] api_method The method which shall be called.
+    # @param [Hash] options The parameters passed as URL params.
+    # @param [String,Symbol] parent the parent XML node to look for.
+    # @param [Class] element The xml node name which shall be converted
+    #   into an object.
+    # @return [Array]
+    def call_pageable(method, parent, element, options={})
+      options = {:all => true}.merge options
+      result = []
+      if options.delete(:all)
+        doc = Base.request(method, options)
+        root = nil
+        doc.root.children.each do |child|
+          next unless child.name == parent.to_s
+          root = child
+        end
+        total_pages = root['totalPages'].to_i
+        root.children.each do |child|
+          next unless child.name == element.to_s.sub("Scrobbler::","").downcase
+          result << element.new_from_libxml(child)
+        end
+        (2..total_pages).each do |i|
+          options[:page] = i
+          result.concat call(method, parent, element, options)
+        end
+      else
+        result = call(method, parent, element, options)
+      end
+      result
+    end
+
   
     # Call a API method
     #

data/lib/scrobbler/library.rb

@@ -40,8 +40,10 @@ module Scrobbler
     
     # A list of all the albums in a user's library, with play counts and tag 
     # counts. 
+    # @param [Hash<Symbol>] options The options to configure this API call.
+    # @return [Array<Scrobbler::Tracks>] The artists included in this library.
     def albums(options={})
-      request_library('library.getalbums', :albums, Album, options)
+      call_pageable('library.getalbums', :albums, Album, {:user => @user.name}.merge(options))
     end
 
     # A list of all the artists in a user's library, with play counts and tag
@@ -50,47 +52,17 @@ module Scrobbler
     # @param [Hash<Symbol>] options The options to configure this API call.
     # @return [Array<Scrobbler::Artist>] The artists included in this library.
     def artists(options={})
-      request_library('library.getartists', :artists, Artist, options)
+      call_pageable('library.getartists', :artists, Artist, {:user => @user.name}.merge(options))
     end
     
     # A list of all the tracks in a user's library, with play counts and tag
     # counts. 
+    # @param [Hash<Symbol>] options The options to configure this API call.
+    # @return [Array<Scrobbler::Track>] The tracks included in this library.
     def tracks(options={})
-        request_library('library.gettracks', :tracks, Track, options)
+      call_pageable('library.gettracks', :tracks, Track, {:user => @user.name}.merge(options))
     end
     
-    # Generic request method for the most Library funtions
-    #
-    # @param [String,Symbol] api_method The method which shall be called.
-    # @param [Hash] options The parameters passed as URL params.
-    # @param [String,Symbol] parent the parent XML node to look for.
-    # @param [Class] element The xml node name which shall be converted
-    #   into an object.
-    # @return [Array]
-    def request_library(method, parent, element, options={})
-      options = {:all => true, :user => @user.name}.merge options
-      result = []
-      if options.delete(:all)
-        doc = Base.request(method, options)
-        root = nil
-        doc.root.children.each do |child|
-          next unless child.name == parent.to_s
-          root = child
-        end
-        total_pages = root['totalPages'].to_i
-        root.children.each do |child|
-          next unless child.name == element.to_s.sub("Scrobbler::","").downcase
-          result << element.new_from_libxml(child)
-        end
-        (2..total_pages).each do |i|
-          options[:page] = i
-          result.concat call(method, parent, element, options)
-        end
-      else
-        result = call(method, parent, element, options)
-      end
-      result
-    end
     
   end
 end

data/lib/scrobbler/user.rb

@@ -2,7 +2,7 @@
 
 require File.expand_path('basexmlinfo.rb', File.dirname(__FILE__))
 
-module Scrobbler  
+module Scrobbler
   class User < BaseXmlInfo
     # Load Helper modules
     include ImageObjectFuncs
@@ -26,7 +26,7 @@ module Scrobbler
     # Load the data for this object out of a XML-Node
     #
     # @param [LibXML::XML::Node] node The XML node containing the information
-    # @return [nil]
+    # @return [void]
     def load_from_xml(node)
       # Get all information from the root's children nodes
       node.children.each do |child|
@@ -53,6 +53,9 @@ module Scrobbler
       end #^ do |child|
     end
     
+    # Create a new Scrobbler:User instance
+    #
+    # @param [Hash] data The options to initialize the class
     def initialize(data={})
       raise ArgumentError unless data.kind_of?(Hash)
       super(data)
@@ -67,32 +70,12 @@ module Scrobbler
       call('user.getevents', :events, Event, {:user => @name})
     end
 
-    # Get a list of the user's friends on Last.fm.    
+    # Get a list of the user's friends on Last.fm.
+    #
+    # @param [Hash] opts Parameters for the API request
+    # @return [Array<Scrobbler::User>]
     def friends(opts={})
-      result = []
-      if opts.delete :all
-        params = {:page => 1, :limit => 50, :user => @name}.merge(opts)
-        doc = Base.request('user.getfriends', params)
-        root = nil
-        doc.root.children.each do |child|
-          next unless child.name == 'friends'
-          root = child
-        end
-        total_pages = root['totalPages'].to_i
-        root.children.each do |child|
-          next unless child.name == 'user'
-          result << Scrobbler::User.new_from_libxml(child)
-        end
-        puts total_pages
-        (2..total_pages).each do |i|
-          params[:page] = i
-          result.concat call('user.getfriends', :friends, User, params)
-        end
-      else
-        params = {:page => 1, :limit => 50, :user => @name}.merge(opts)
-        result = call('user.getfriends', :friends, User, params)
-      end
-      result
+      call_pageable('user.getfriends', :friends, User, {:user => @name}.merge(opts))
     end
     
     # Get information about a user profile.
@@ -102,22 +85,28 @@ module Scrobbler
     end
     
     # Get the last 50 tracks loved by a user.
+    #
+    # @return [Array<Scrobbler::Track>]
     def loved_tracks
         call('user.getlovedtracks', :lovedtracks, Track, {:user => @name})
     end
 
     # Get a list of a user's neighbours on Last.fm.
+    #
+    # @return [Array<Scrobbler::Track>]
     def neighbours
       call('user.getneighbours', :neighbours, User, {:user => @name})
     end
 
-    # Get a paginated list of all events a user has attended in the past. 
+    # Get a paginated list of all events a user has attended in the past.
     def past_events(format=:ics)
       # This needs a Event class, which is yet not available
       raise NotImplementedError
     end
     
     # Get a list of a user's playlists on Last.fm. 
+    #
+    # @return [Array<Scrobbler::Playlist>]
     def playlists
       call('user.getplaylists', :playlists, Playlist, {:user => @name})
     end
@@ -125,14 +114,15 @@ module Scrobbler
     # Get a list of the recent tracks listened to by this user. Indicates now 
     # playing track if the user is currently listening.
     #
-    # Possible parameters:
-    #   - limit: An integer used to limit the number of tracks returned.
+    # @param [Hash] parameters
+    # @return [Array<Scrobbler::Track>]
     def recent_tracks(parameters={})
-      parameters.merge!({:user => @name})
-      call('user.getrecenttracks', :recenttracks, Track, parameters)
+      call('user.getrecenttracks', :recenttracks, Track, {:user => @name}.merge(parameters))
     end
     
     # Get Last.fm artist recommendations for a user
+    #
+    # @return [Array<Scrobbler::Artist>]
     def recommended_artists
         # This function require authentication, but SimpleAuth is not yet 2.0
         raise NotImplementedError
@@ -152,50 +142,69 @@ module Scrobbler
     end
     
     # Get the top albums listened to by a user. You can stipulate a time period. 
-    # Sends the overall chart by default. 
+    # Sends the overall chart by default.
+    #
+    # @return [Array<Scrobbler::Album>] 
     def top_albums(period=:overall)
       call('user.gettopalbums', :topalbums, Album, {:user => @name, :period => period})
     end
 
     # Get the top artists listened to by a user. You can stipulate a time 
-    # period. Sends the overall chart by default. 
+    # period. Sends the overall chart by default.
+    #
+    # @return [Array<Scrobbler::Artist>] 
     def top_artists(period=:overall)
       call('user.gettopartists', :topartists, Artist, {:user => @name, :period => period})
     end
 
-    #  Get the top tags used by this user.
+    # Get the top tags used by this user.
+    #
+    # @return [Array<Scrobbler::Tag>]
     def top_tags
       call('user.gettoptags', :toptags, Tag, {:user => @name})
     end
 
     # Get the top tracks listened to by a user. You can stipulate a time period. 
-    # Sends the overall chart by default. 
+    # Sends the overall chart by default.
+    #
+    # @return [Array<Scrobbler::Track>] 
     def top_tracks(period=:overall)
       call('user.gettoptracks', :toptracks, Track, {:user => @name, :period => period})
     end
 
     # Setup the parameters for a *chart API call
-    def setup_chart_params(from=nil, to=nil)
+    #
+    # @param [Class] type 
+    # @return [Array]
+    def get_chart(type, from, to)
       parameters = {:user => @name}
       parameters[:from] = from unless from.nil?
       parameters[:to] = to unless to.nil?
-      parameters
+      downType = type.to_s.sub("Scrobbler::","").downcase
+      call('user.getweekly'+ downType + 'chart', 
+        'weekly' + downType + 'chart', type, parameters)
     end
 
     # Get an album chart for a user profile, for a given date range. If no date 
     # range is supplied, it will return the most recent album chart for this 
     # user. 
+    #
+    # @param [int] from Starttime
+    # @param [int] to Endtime
+    # @return [Array<Scrobbler::Album>]
     def weekly_album_chart(from=nil, to=nil)
-      parameters = setup_chart_params(from, to)
-      call('user.getweeklyalbumchart', :weeklyalbumchart, Album, parameters)
+      get_chart(Album, from, to)
     end
     
     # Get an artist chart for a user profile, for a given date range. If no date
     # range is supplied, it will return the most recent artist chart for this 
     # user. 
+    #
+    # @param [int] from Starttime
+    # @param [int] to Endtime
+    # @return [Array<Scrobbler::Artist>]
     def weekly_artist_chart(from=nil, to=nil)
-      parameters = setup_chart_params(from, to)
-      call('user.getweeklyartistchart', :weeklyartistchart, Artist, parameters)
+      get_chart(Artist, from, to)
     end
     
     # Get a list of available charts for this user, expressed as date ranges 
@@ -208,9 +217,12 @@ module Scrobbler
     # Get a track chart for a user profile, for a given date range. If no date 
     # range is supplied, it will return the most recent track chart for this 
     # user. 
+    #
+    # @param [int] from Starttime
+    # @param [int] to Endtime
+    # @return [Array<Scrobbler::Track>]
     def weekly_track_chart(from=nil, to=nil)
-      parameters = setup_chart_params(from, to)
-      call('user.getweeklytrackchart', :weeklytrackchart, Track, parameters)
+      get_chart(Track, from, to)
     end
     
     # Shout on this user's shoutbox

data/scrobbler-ng.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{scrobbler-ng}
-  s.version = "2.0.5"
+  s.version = "2.0.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Nunemaker", "Jonathan Rudenberg", "Uwe L. Korn"]
-  s.date = %q{2010-07-30}
+  s.date = %q{2010-08-05}
   s.description = %q{A ruby library for accessing the Last.fm 2.0 API. It is higly optimized so that it uses less memory and parses XML (through Nokogiri) than other implementations.}
   s.email = %q{uwelk@xhochy.org}
   s.extra_rdoc_files = [

data/test/mocks/rest.rb

@@ -103,7 +103,7 @@ register_fw('user=jnunemaker&period=overall&api_key=foo123&method=user.gettopalb
   'user', 'topalbums.xml')
 register_fw('user=jnunemaker&api_key=foo123&method=user.getneighbours',
   'user', 'neighbours.xml')
-register_fw('user=jnunemaker&page=1&limit=50&api_key=foo123&method=user.getfriends',
+register_fw('user=jnunemaker&api_key=foo123&method=user.getfriends',
   'user', 'friends.xml')
 register_fw('user=jnunemaker&api_key=foo123&method=user.getrecenttracks',
   'user', 'recenttracks.xml')

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: scrobbler-ng
 version: !ruby/object:Gem::Version 
-  hash: 5
+  hash: 3
   prerelease: false
   segments: 
   - 2
   - 0
-  - 5
-  version: 2.0.5
+  - 6
+  version: 2.0.6
 platform: ruby
 authors: 
 - John Nunemaker
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-30 00:00:00 +02:00
+date: 2010-08-05 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency