rscrobbler 0.0.6 → 0.1.0

data/lib/lastfm/geo.rb

@@ -4,59 +4,120 @@ module LastFM
 
       TYPE = 'geo'
 
+      # Get all events in a specific location by country or city name.
+      #
+      # @option params [String, optional] :location   location to retrieve events for
+      # @option params [String, optional] :lat        latitude value to retrieve events for
+      # @option params [String, optional] :long       longitude value to retrieve events for
+      # @option params [Fixnum, optional] :distance   find events within a specified radius (in kilometres)
+      # @option params [Fixnum, optional] :page       the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit      the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=270
-      def get_events( location = nil, lat = nil, long = nil, distance = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getEvents", !:secure, 'location'=>location, 'lat'=>lat, 'long'=>long, 'distance'=>distance, 'limit'=>limit, 'page'=>page )
+      def get_events( params )
+        LastFM.get( "#{TYPE}.getEvents", !:secure, params )
       end
-    
+
+      # Get a chart of artists for a metro.
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=421
-      def get_metro_artist_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroArtistChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_artist_chart( params )
+        LastFM.get( "#{TYPE}.getMetroArtistChart", params )
       end
-    
+
+      # Get a chart of hyped (up and coming) artists for a metro.
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=420
-      def get_metro_hype_artist_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroHypeArtistChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_hype_artist_chart( params )
+        LastFM.get( "#{TYPE}.getMetroHypeArtistChart", params )
       end
-    
+
+      # Get a chart of hyped (up and coming) tracks for a metro.
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=422
-      def get_metro_hype_track_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroHypeTrackChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_hype_track_chart( params )
+        LastFM.get( "#{TYPE}.getMetroHypeTrackChart", params )
       end
-    
+
+      # Get a chart of tracks for a metro.
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=423
-      def get_metro_track_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroTrackChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_track_chart( params )
+        LastFM.get( "#{TYPE}.getMetroTrackChart", params )
       end
-    
+
+      # Get a chart of the artists which make that metro unique
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=424
-      def get_metro_unique_artist_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroUniqueArtistChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_unique_artist_chart( params )
+        LastFM.get( "#{TYPE}.getMetroUniqueArtistChart", params )
       end
-    
+
+      # Get a chart of the tracks which make that metro unique
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, required] :metro      the metro's name
+      # @option params [Time,   optional] :start      beginning timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
+      # @option params [Time,   optional] :end        ending timestamp of the weekly range requested (see: Geo.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=425
-      def get_metro_unique_track_chart( country, metro, time_start = nil, time_end = nil )
-        LastFM.get( "#{TYPE}.getMetroUniqueTrackChart", !:secure, 'country'=>country, 'metro'=>metro, 'start'=>time_start, 'end'=>time_end )
+      def get_metro_unique_track_chart( params )
+        LastFM.get( "#{TYPE}.getMetroUniqueTrackChart", params )
       end
-    
+
+      # Get a list of available chart periods for this metro, expressed as date ranges which can be sent to the chart services.
+      #
+      # @option params [String, required] :metro    metro name to fetch the charts list for
       # @see http://www.last.fm/api/show?service=426
-      def get_metro_weekly_chartlist( metro )
-        LastFM.get( "#{TYPE}.getMetroWeeklyChartlist", !:secure, 'metro'=>metro )
+      def get_metro_weekly_chartlist( params )
+        LastFM.get( "#{TYPE}.getMetroWeeklyChartlist", params )
       end
-    
+
+      # Get a list of valid countries and metros for use in the other webservices
+      #
+      # @option params [String, optional] :country    restrict results to metros from a particular country, as defined by ISO 3166-1
       # @see http://www.last.fm/api/show?service=435
-      def get_metros( country = nil )
-        LastFM.get( "#{TYPE}.getMetros", !:secure, 'country'=>country )
+      def get_metros( params )
+        LastFM.get( "#{TYPE}.getMetros", params )
       end
-    
+
+      # Get the most popular artists on Last.fm by country
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [Fixnum, optional] :page       the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit      the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=297
-      def get_top_artists( country, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopArtists", !:secure, 'country'=>country, 'limit'=>limit, 'page'=>page )
+      def get_top_artists( params )
+        LastFM.get( "#{TYPE}.getTopArtists", params )
       end
-    
+
+      # Get the most popular tracks on Last.fm by country
+      #
+      # @option params [String, required] :country    a country name, as defined by ISO 3166-1
+      # @option params [String, optional] :location   location to fetch the charts for
+      # @option params [Fixnum, optional] :page       the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit      the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=298
-      def get_top_tracks( country, location = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'country'=>country, 'location'=>location, 'limit'=>limit, 'page'=>page )
+      def get_top_tracks( params )
+        LastFM.get( "#{TYPE}.getTopTracks", params )
       end
 
     end

data/lib/lastfm/group.rb

@@ -4,34 +4,64 @@ module LastFM
 
       TYPE = 'group'
 
+      # Get the hype list for a group.
+      #
+      # @option params [String, required] :group    the last.fm group name
       # @see http://www.last.fm/api/show?service=259
-      def get_hype( group )
-        LastFM.get( "#{TYPE}.getHype", !:secure, 'group'=>group )
+      def get_hype( params )
+        LastFM.get( "#{TYPE}.getHype", params )
       end
-    
+
+      # Get the list of members for a group.
+      #
+      # @option params [String, required] :group    the last.fm group name
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show/?service=379
-      def get_members( group, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getMembers", !:secure, 'group'=>group, 'limit'=>limit, 'page'=>page )
+      def get_members( params )
+        LastFM.get( "#{TYPE}.getMembers", params )
       end
-    
+
+      # Get an album chart for a group, for a given date range. If no date range
+      # is supplied, return the most recent.
+      #
+      # @option params [String, required] :group    the last.fm group name
+      # @option params [Time,   optional] :from     date at which the chart should start from (see: Group.get_weekly_chart_list)
+      # @option params [Time,   optional] :to       date at which the chart should end on (see: Group.get_weekly_chart_list)
       # @see http://www.last.fm/api/show/?service=293
-      def get_weekly_album_chart( group, date_from = nil, date_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyAlbumChart", !:secure, 'group'=>group, 'from'=>date_from, 'to'=>date_to )
+      def get_weekly_album_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyAlbumChart", params )
       end
-    
+
+      # Get an artist chart for a group, for a given date range. If no date range
+      # is supplied, return the most recent.
+      #
+      # @option params [String, required] :group    the last.fm group name
+      # @option params [Time,   optional] :from     date at which the chart should start from (see: Group.get_weekly_chart_list)
+      # @option params [Time,   optional] :to       date at which the chart should end on (see: Group.get_weekly_chart_list)
       # @see http://www.last.fm/api/show/?service=294
-      def get_weekly_artist_chart( group, date_from = nil, date_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyArtistChart", !:secure, 'group'=>group, 'from'=>date_from, 'to'=>date_to )
+      def get_weekly_artist_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyArtistChart", params )
       end
-    
+
+      # Get the list of available charts for a group, expressed as date ranges
+      # which can be sent to the chart services.
+      #
+      # @option params [String, required] :group    the last.fm group name
       # @see http://www.last.fm/api/show/?service=295
-      def get_weekly_chart_list( group )
-        LastFM.get( "#{TYPE}.getWeeklyChartList", !:secure, 'group'=>group )
+      def get_weekly_chart_list( params )
+        LastFM.get( "#{TYPE}.getWeeklyChartList", params )
       end
-    
+
+      # Get a track chart for a group, for a given date range. If no date range
+      # is supplied, return the most recent.
+      #
+      # @option params [String, required] :group    the last.fm group name
+      # @option params [Time,   optional] :from     date at which the chart should start from (see: Group.get_weekly_chart_list)
+      # @option params [Time,   optional] :to       date at which the chart should end on (see: Group.get_weekly_chart_list)
       # @see http://www.last.fm/api/show/?service=296
-      def get_weekly_track_chart( group, date_from = nil, date_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyTrackChart", !:secure, 'group'=>group, 'from'=>date_from, 'to'=>date_to )
+      def get_weekly_track_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyTrackChart", params )
       end
 
     end

data/lib/lastfm/library.rb

@@ -4,61 +4,112 @@ module LastFM
 
       TYPE = 'library'
 
-      # see: http://www.last.fm/api/show?service=370
-      def add_album( artist, album )
+      # Add an album or collection of albums to a user's Last.fm library.
+      #
+      # @option params [Array, required] :artists   the artist or collection of artists to add
+      # @option params [Array, required] :albums    the album or collection of albums to add. the indices of the albums that you pass MUST correspond to those of the artists
+      # @see http://www.last.fm/api/show?service=370
+      def add_album( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addAlbum", 'artist'=>artist, 'album'=>album )
+        # convert :artists and :albums to individual artist[i] and album[i]
+        Array(params.delete(:artists)).each_with_index{|val, i| params["artist[#{i}]"] = val}
+        Array(params.delete(:albums)).each_with_index{|val, i| params["album[#{i}]"] = val}
+        LastFM.post( "#{TYPE}.addAlbum", params )
       end
 
-      # see: http://www.last.fm/api/show?service=371
-      def add_artist( artist )
+      # Add an artist or collection of artists to a user's Last.fm library.
+      #
+      # @option params [Array, required] :artists   the artist or collection of artists to add
+      # @see http://www.last.fm/api/show?service=371
+      def add_artist( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addArtist", 'artist'=>artist )
+        Array(params.delete(:artists)).each_with_index{|val, i| params["artist[#{i}]"] = val}
+        LastFM.post( "#{TYPE}.addArtist", params )
       end
 
-      # see: http://www.last.fm/api/show?service=372
-      def add_track( track, artist )
+      # Add a track or collection of tracks to a user's Last.fm library.
+      #
+      # @option params [Array, required] :artists   the artist or collection of artists to add
+      # @option params [Array, required] :tracks    the track or collection of tracks to add. the indices of the tracks that you pass MUST correspond to those of the artists
+      # @see http://www.last.fm/api/show?service=372
+      def add_track( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addTrack", 'track'=>track, 'artist'=>artist )
+        Array(params.delete(:artists)).each_with_index{|val, i| params["artist[#{i}]"] = val}
+        Array(params.delete(:tracks)).each_with_index{|val, i| params["track[#{i}]"] = val}
+        LastFM.post( "#{TYPE}.addTrack", params )
       end
 
-      # see: http://www.last.fm/api/show?service=321
-      def get_albums( user, artist = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getAlbums", !:secure, 'user'=>user, 'artist'=>artist, 'limit'=>limit, 'page'=>page )
+      # A paginated list of all the albums in a user's library, with play counts and tag counts.
+      #
+      # @option params [String, requried] :user     the user whose library you want to fetch
+      # @option params [String, optional] :artist   an artist by which to filter albums
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+      # @see http://www.last.fm/api/show?service=321
+      def get_albums( params )
+        LastFM.get( "#{TYPE}.getAlbums", params )
       end
 
-      # see: http://www.last.fm/api/show?service=322
-      def get_artists( user, limit = nil, page = nil )
-         LastFM.get( "#{TYPE}.getArtists", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      # A paginated list of all the artists in a user's library, with play counts and tag counts.
+      #
+      # @option params [String, requried] :user     the user whose library you want to fetch
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+      # @see http://www.last.fm/api/show?service=322
+      def get_artists( params )
+         LastFM.get( "#{TYPE}.getArtists", params )
       end
 
-      # see: http://www.last.fm/api/show?service=323
-      def get_tracks( user, artist = nil, album = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTracks", !:secure, 'user'=>user, 'artist'=>artist, 'album'=>album, 'limit'=>limit, 'page'=>page )
+      # A paginated list of all the tracks in a user's library, with play counts and tag counts.
+      #
+      # @option params [String, requried] :user     the user whose library you want to fetch
+      # @option params [String, optional] :artist   an artist by which to filter track
+      # @option params [String, optional] :album    an album by which to filter tracks (requires an associated artist)
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+      # @see http://www.last.fm/api/show?service=323
+      def get_tracks( params )
+        LastFM.get( "#{TYPE}.getTracks", params )
       end
 
-      # see: http://www.last.fm/api/show?service=523
-      def remove_album( artist, album )
+      # Remove an album from a user's Last.fm library.
+      #
+      # @option params [String, required] :artist   the artist that composed the album
+      # @option params [String, required] :album    the name of the album to remove
+      # @see http://www.last.fm/api/show?service=523
+      def remove_album( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeAlbum", 'artist'=>artist, 'album'=>album )
+        LastFM.post( "#{TYPE}.removeAlbum", params )
       end
 
-      # see: http://www.last.fm/api/show?service=524
-      def remove_artist( artist )
+      # Remove an artist from a user's Last.fm library.
+      #
+      # @option params [String, required] :artist   the name of the artist to remove
+      # @see http://www.last.fm/api/show?service=524
+      def remove_artist( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeArtist", 'artist'=>artist )
+        LastFM.post( "#{TYPE}.removeArtist", params )
       end
 
-      # see: http://www.last.fm/api/show?service=525
-      def remove_scrobble( track, artist, timestamp )
+      # Remove a scrobble from a user's Last.fm library.
+      #
+      # @option params [String, required] :artist       the artist that composed the album
+      # @option params [String, required] :track        the name of the track to remove
+      # @option params [Time,   required] :timestamp    the unix timestamp of the scrobble to remove
+      # @see http://www.last.fm/api/show?service=525
+      def remove_scrobble( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeScrobble", 'track'=>track, 'artist'=>artist, 'timestamp'=>timestamp )
+        LastFM.post( "#{TYPE}.removeScrobble", params )
       end
 
-      # see: http://www.last.fm/api/show?service=526
-      def remove_track( track, artist )
+      # Remove a track from a user's Last.fm library.
+      #
+      # @option params [String, required] :artist   the artist that composed the track
+      # @option params [String, required] :track    the name of the track to remove
+      # @see http://www.last.fm/api/show?service=526
+      def remove_track( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeTrack", 'track'=>track, 'artist'=>artist )
+        LastFM.post( "#{TYPE}.removeTrack", params )
       end
 
     end

data/lib/lastfm/playlist.rb

@@ -4,21 +4,35 @@ module LastFM
 
       TYPE = 'playlist'
 
-      # see: http://www.last.fm/api/show?service=337
-      def add_track( playlist_id, artist, track )
+      # Add a track to a Last.fm user's playlist
+      #
+      # @option params [String, required] :playlist_id    the id of the playlist (see: User.get_playlists)
+      # @option params [String, required] :track          the track name to add to the playlist
+      # @option params [String, required] :artist         the artist that corresponds to the track to be added
+      # @see http://www.last.fm/api/show?service=337
+      def add_track( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addTrack", 'playlistID'=>playlist_id, 'artist'=>artist, 'track'=>track )
+        LastFM.post( "#{TYPE}.addTrack", params )
       end
 
-      # see: http://www.last.fm/api/show?service=365
-      def create( title = nil, description = nil )
+      # Create a Last.fm playlist on behalf of a user.
+      #
+      # @option params [String, optional] :title          title for the playlist
+      # @option params [String, optional] :description    description for the playlist
+      # @see http://www.last.fm/api/show?service=365
+      def create( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.create", 'title'=>title, 'description'=>description )
+        LastFM.post( "#{TYPE}.create", params )
       end
 
-      # see: http://www.last.fm/api/show?service=271
-      def fetch( playlist_url )
-        LastFM.get( "#{TYPE}.fetch", !:secure, 'playlistURL'=>playlist_url )
+      # Fetch XSPF playlists using a lastfm playlist url.
+      #
+      # @option params [String,  required] :playlist_url    lastfm protocol playlist url (lastfm://playlist/...)
+      # @option params [Boolean, optional] :steaming        whether to return mp3 links for song previews
+      # @see http://www.last.fm/api/show?service=271
+      # @deprecated documentation removed from last.fm/api, but method calls still work
+      def fetch( params )
+        LastFM.get( "#{TYPE}.fetch", params )
       end
 
     end

data/lib/lastfm/radio.rb

@@ -4,22 +4,36 @@ module LastFM
 
       TYPE = 'radio'
 
-      # see: http://www.last.fm/api/show?service=256
-      def get_playlist( discovery = nil, rtp = nil, buylinks = nil, speed_multiplier = nil, bitrate = nil )
-        raise ArgumentError unless [1.0, 2.0].include?(speed_multiplier) && [64, 128].include?(bitrate)
+      # Fetch new radio content periodically in an XSPF format.
+      #
+      # @option params [Boolean, optional] :discovery           whether to request last.fm content in discovery mode
+      # @option params [Boolean, optional] :rtp                 whether the user is scrobbling or not during this session (helps content generation)
+      # @option params [Boolean, optional] :buylinks            whether the response should contain links for purchase/download
+      # @option params [String,  optional] :speed_multiplier    the rate at which to provide the stream (supported multipliers are 1.0 and 2.0)
+      # @option params [String,  optional] :bitrate             what bitrate to stream content at, in kbps (supported bitrates are 64 and 128)
+      # @see http://www.last.fm/api/show?service=256
+      def get_playlist( params )
         LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getPlaylist", :secure, 'discovery'=>discovery, 'rtp'=>rtp, 'buylinks'=>buylinks, 'speed_multiplier'=>speed_multiplier, 'bitrate'=>bitrate )
+        LastFM.get( "#{TYPE}.getPlaylist", params, :secure )
       end
 
-      # see: http://www.last.fm/api/show?service=418
-      def search( name )
-        LastFM.get( "#{TYPE}.search", !:secure, 'name'=>name )
+      # Resolve the name of a resource into a station depending
+      # on which resource it is most likely to represent.
+      #
+      # @option params [String, required] :name   the tag or artist name to resolve
+      # @see http://www.last.fm/api/show?service=418
+      def search( params )
+        LastFM.get( "#{TYPE}.search", params )
       end
 
-      # see: http://www.last.fm/api/show?service=160
-      def tune( station, lang = nil )
+      # Tune in to a Last.fm radio station.
+      #
+      # @option params [String, required] :station    a 'lastfm://...' radio url
+      # @option params [String, optional] :lang       the language to return the station name in, expressed as an ISO 639 alpha-2 code
+      # @see http://www.last.fm/api/show?service=160
+      def tune( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.tune", 'station'=>station, 'lang'=>lang )
+        LastFM.post( "#{TYPE}.tune", params )
       end
 
     end

data/lib/lastfm/tag.rb

@@ -4,49 +4,89 @@ module LastFM
 
       TYPE = 'tag'
 
+      # Get the metadata for a tag.
+      #
+      # @option params [String, required] :tag    the tag name
+      # @option params [String, optinoal] :lang   the language to return the summary in, expressed as an ISO 639 alpha-2 code
       # @see http://www.last.fm/api/show?service=452
-      def get_info( tag, lang = nil )
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'tag'=>tag, 'lang'=>lang )
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
       end
 
+      # Search for tags similar to this one. Returns tags ranked by similarity, based on listening data.
+      #
+      # @option params [String, required] tag   the tag name
       # @see http://www.last.fm/api/show?service=311
-      def get_similar( tag )
-        LastFM.get( "#{TYPE}.getSimilar", !:secure, 'tag'=>tag )
+      def get_similar( params )
+        LastFM.get( "#{TYPE}.getSimilar", params )
       end
 
+      # Get the top albums tagged with a tag, ordered by tag count.
+      #
+      # @option params [String, required] :tag      the tag name
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=283
-      def get_top_albums( tag, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopAlbums", !:secure, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
+      def get_top_albums( params )
+        LastFM.get( "#{TYPE}.getTopAlbums", params )
       end
 
+      # Get the top artists tagged with a tag, ordered by tag count.
+      #
+      # @option params [String, required] :tag      the tag name
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=284
-      def get_top_artists( tag, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopArtists", !:secure, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
+      def get_top_artists( params )
+        LastFM.get( "#{TYPE}.getTopArtists", params )
       end
 
+      # Fetches the top global tags on Last.fm, sorted by popularity (number of times used).
+      #
       # @see http://www.last.fm/api/show?service=276
       def get_top_tags
-        LastFM.get( "#{TYPE}.getTopTags", !:secure  )
+        LastFM.get( "#{TYPE}.getTopTags" )
       end
 
+      # Get the top tracks tagged with a tag, ordered by tag count.
+      #
+      # @option params [String, required] :tag      the tag name
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=285
-      def get_top_tracks( tag, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
+      def get_top_tracks( params )
+        LastFM.get( "#{TYPE}.getTopTracks", params )
       end
 
+      # Get an artist chart for a tag, for a given date range. If no date range is
+      # supplied, it will return the most recent artist chart for this tag.
+      #
+      # @option params [String, required] :tag      the tag name
+      # @option params [String, optional] :from     date at which the chart should start from (see: Tag.get_weekly_chart_list)
+      # @option params [String, optional] :to       date at which the chart should end on (see: Tag.get_weekly_chart_list)
+      # @option params [Fixnum, optional] :limit    the number of results to fetch. defaults to 50
       # @see http://www.last.fm/api/show?service=358
-      def get_weekly_artist_chart( tag, time_from = nil, time_to = nil, limit = nil )
-        LastFM.get( "#{TYPE}.getWeeklyArtistChart", !:secure, 'tag'=>tag, 'from'=>time_from, 'to'=>time_to, 'limit'=>limit )
+      def get_weekly_artist_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyArtistChart", params )
       end
 
+      # Get a list of available charts for this tag, expressed as date
+      # ranges which can be sent to the chart services.
+      #
+      # @option params [String, required] :tag    the tag name
       # @see http://www.last.fm/api/show?service=359
-      def get_weekly_chart_list( tag )
-        LastFM.get( "#{TYPE}.getWeeklyChartList", !:secure, 'tag'=>tag )
+      def get_weekly_chart_list( params )
+        LastFM.get( "#{TYPE}.getWeeklyChartList", params )
       end
 
+      # Search for a tag by name. Returns matches sorted by relevance.
+      #
+      # @option params [String, required] :tag      the tag name
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=273
-      def search( tag, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.search", !:secure, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
+      def search( params )
+        LastFM.get( "#{TYPE}.search", params )
       end
 
     end

data/lib/lastfm/tasteometer.rb

@@ -4,10 +4,32 @@ module LastFM
 
       TYPE = 'tasteometer'
 
+      # Get a Tasteometer score from two inputs, along with a list of shared
+      # artists. If the input is a User some additional information is returned.
+      #
+      # @option params [Array,  required] :types    two types are required for comparison. accepted types are 'user' and 'artists'
+      # @option params [Array,  required] :values   values for the corresponding types. accepted values are Last.fm usernames, or arrays of artist names (up to 100 artists)
+      # @option params [Fixnum, optional] :limit    how many shared artists to display. default is 5
       # @see http://www.last.fm/api/show?service=258
-      def compare( type_1, type_2, value_1, value_2, limit = nil )
-        raise ArgumentError unless [ 'user', 'artists', 'myspace' ].include?(type_1) && [ 'user', 'artists', 'myspace' ].include?(type_2)
-        LastFM.get( "#{TYPE}.compare", !:secure, 'type1'=>type_1, 'type2'=>type_2, 'value1'=>value_1, 'value2'=>value_2 )
+      def compare( params )
+        Array(params.delete(:types)).each_with_index{|val, i| params["type[#{i}]"] = val}
+        Array(params.delete(:values)).each_with_index{|val, i| params["value[#{i}]"] = val}
+        LastFM.get( "#{TYPE}.compare", params )
+      end
+
+      # Get the scores between every user in a group of users, plus shared artists.
+      # Cuts off any similarities below a cutoff. Also returns a list of all users
+      # in the comparison and a small amount of metadata about each. Can take the
+      # list of users from a group, or a users friends.
+      #
+      # @option params [String, required] :source             what source we're using for the comparison. accepted sources are 'user' and 'group'
+      # @option params [String, required] :value              name of the source we're using. should be either a Last.fm username or group name
+      # @option params [Float,  optional] :cutoff             the minimum level over which comparisons should be returned. default is 0.2
+      # @option params [Fixnum, optional] :connection_limit   the maximum number of connections each user should have. default is 6
+      # @see http://www.last.fm/api/show?service=500
+      # @deprecated This service has been deprecated and is no longer available
+      def compare_group(params)
+        LastFM.get( "#{TYPE}.compareGroup", params )
       end
 
     end