rscrobbler 0.0.6 → 0.1.0

data/lib/lastfm/album.rb

@@ -4,58 +4,112 @@ module LastFM
 
       TYPE = 'album'
 
+      # Tag an album using a list of user supplied tags.
+      #
+      # @option params [String, required] :artist the artist name
+      # @option params [String, required] :album  the album name
+      # @option params [Array, required]  :tags   up to 10 tags to apply to this album
       # @see http://www.last.fm/api/show?service=302
-      def add_tags( artist, album, tags )
+      def add_tags( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addTags", 'artist'=>artist, 'album'=>album, 'tags'=>tags )
+        LastFM.post( "#{TYPE}.addTags", params )
       end
 
+      # Get a list of buy links for an album.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :album          the album name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the album
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [String,  optional]              :country        a country name, as defined by ISO 3166-1
       # @see http://www.last.fm/api/show?service=429
-      def get_buylinks( country, artist = nil, album = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && album || mbid
-        LastFM.get( "#{TYPE}.getBuylinks", !:secure, 'country'=>country, 'artist'=>artist, 'album'=>album, 'mbid'=>mbid, 'autocorrect'=>autocorrect  )
+      def get_buylinks( params )
+        LastFM.get( "#{TYPE}.getBuylinks", params )
       end
 
+      # Get the metadata for an album.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :album          the album name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the album
+      # @option params [String,  optional]              :lang           the language to return the biography in, expressed as an ISO 639 alpha-2 code
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [String,  optional]              :username       username whose playcount for this album is to be returned in the reponse
       # @see http://www.last.fm/api/show?service=290
-      def get_info( artist = nil, album = nil, mbid = nil, lang = nil, autocorrect = nil, username = nil )
-        raise ArgumentError unless artist && album || mbid
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'artist'=>artist, 'album'=>album, 'mbid'=>mbid, 'lang'=>lang, 'autocorrect'=>autocorrect, 'username'=>username )
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
       end
 
+      # Get shouts for an album.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :album          the album name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the album
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=450
-      def get_shouts( artist = nil, album = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist && album || mbid
-        LastFM.get( "#{TYPE}.getShouts", !:secure, 'artist'=>artist, 'album'=>album, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_shouts( params )
+        LastFM.get( "#{TYPE}.getShouts", params )
       end
 
+      # Get the tags applied by an individual user to an album.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :album          the album name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the album
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [String,  optional]              :user           if called in non-authenticated mode you must specify the user to look up
       # @see http://www.last.fm/api/show?service=317
-      def get_tags( artist = nil, album = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && album || mbid
-        LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getTags", :secure, 'artist'=>artist, 'album'=>album, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_tags( params )
+        secure = !params.include?(:user)
+        LastFM.requires_authentication if secure
+        LastFM.get( "#{TYPE}.getTags", params, secure )
       end
 
+      # Get the top tags for an album, ordered by popularity.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :album          the album name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the album
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
       # @see http://www.last.fm/api/show?service=438
-      def get_top_tags( artist = nil, album = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && album || mbid
-        LastFM.get( "#{TYPE}.getTopTags", !:secure, 'artist'=>artist, 'album'=>album, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_top_tags( params )
+        LastFM.get( "#{TYPE}.getTopTags", params )
       end
 
+      # Remove a user's tag from an album.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :album    the album name
+      # @option params [String, required] :tag      a single user tag to remove from this album
       # @see http://www.last.fm/api/show?service=314
-      def remove_tag( artist, album, tag )
+      def remove_tag( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeTag", 'artist'=>artist, 'album'=>album, 'tag'=>tag )
+        LastFM.post( "#{TYPE}.removeTag", params )
       end
 
+      # Search for an album by name. Returns album matches sorted by relevance.
+      #
+      # @option params [String, required] :album    the album 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=357
-      def search( album, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.search", !:secure, 'album'=>album, 'limit'=>limit, 'page'=>page )
+      def search( params )
+        LastFM.get( "#{TYPE}.search", params )
       end
 
+      # Share an album with one or more Last.fm users or other friends.
+      #
+      # @option params [String,  required] :artist      the artist name
+      # @option params [String,  required] :album       the album name
+      # @option params [Array,   required] :recipient   a list of email addresses or Last.fm usernames. maximum is 10
+      # @option params [String,  optional] :message     an optional message to send. if not supplied a default message will be used
+      # @option params [Boolean, optional] :public      optionally show in the sharing users activity feed. defaults to false
       # @see http://www.last.fm/api/show?service=436
-      def share( artist, album, recipient, message = nil, public = nil )
+      def share( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.share", 'artist'=>artist, 'album'=>album, 'recipient'=>recipient, 'message'=>message, 'public'=>public )
+        LastFM.post( "#{TYPE}.share", params )
       end
 
     end

data/lib/lastfm/artist.rb

@@ -4,111 +4,205 @@ module LastFM
 
       TYPE = 'artist'
 
+      # Tag an artist with one or more user supplied tags.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [Array, required]  :tags     up to 10 tags to apply to this artist
       # @see http://www.last.fm/api/show/?service=303
-      def add_tags( artist, tags )
+      def add_tags( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addTags", 'artist'=>artist, 'tags'=>tags )
+        LastFM.post( "#{TYPE}.addTags", params )
       end
 
+      # Check whether the supplied artist has a correction to a canonical artist.
+      #
+      # @option params [String, required] :artist   the artist name
       # @see http://www.last.fm/api/show/?service=446
-      def get_correction( artist )
-        LastFM.get( "#{TYPE}.getCorrection", !:secure, 'artist'=>artist )
-      end
-
+      def get_correction( params )
+        LastFM.get( "#{TYPE}.getCorrection", params )
+      end
+
+      # Get a list of upcoming events for this artist.
+      #
+      # @option params [String,  required unless :mbid] :artist           the artist name
+      # @option params [String,  optional]              :mbid             the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :festivalsonly    whether only festivals should be returned, or all events
+      # @option params [Boolean, optional]              :autocorrect      transform misspelled artist names into correct artist names to be returned in the response
+      # @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=117
-      def get_events( artist = nil, mbid = nil, autocorrect = nil, festivals_only = nil, limit = nil, page = nil)
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getEvents", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'festivalsonly'=>festivals_only, 'limit'=>limit, 'page'=>page )
-      end
-
+      def get_events( params )
+        LastFM.get( "#{TYPE}.getEvents", params )
+      end
+
+      # Get images for this artist in a variety of sizes.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Symbol,  optional]              :order          sort ordering can be either :popularity (default) or :dateadded
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=407
-      def get_images( artist = nil, mbid = nil, autocorrect = nil, order = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getImages", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'order'=>order, 'limit'=>limit, 'page'=>page )
+      def get_images( params )
+        LastFM.get( "#{TYPE}.getImages", params )
       end
 
+      # Get the metadata for an artist. Includes biography.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [String,  optional]              :lang           the language to return the biography in, expressed as an ISO 639 alpha-2 code
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [String,  optional]              :username       username whose playcount for this artist is to be returned in the reponse
       # @see http://www.last.fm/api/show/?service=267
-      def get_info( artist = nil, mbid = nil, lang = nil, autocorrect = nil, username = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'lang'=>lang, 'username'=>username )
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
       end
 
+      # Get a paginated list of all the events this artist has played at in the past.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=428
-      def get_past_events( artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getPastEvents", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_past_events( params )
+        LastFM.get( "#{TYPE}.getPastEvents", params )
       end
 
+      # Get a podcast of free mp3s based on an artist.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
       # @see http://www.last.fm/api/show/?service=118
-      def get_podcast( artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getPodcast", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_podcast( params )
+        LastFM.get( "#{TYPE}.getPodcast", params )
       end
 
+      # Get shouts for this artist.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=397
-      def get_shouts( artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getShouts", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_shouts( params )
+        LastFM.get( "#{TYPE}.getShouts", params )
       end
 
+      # Get all the artists similar to this artist.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [Fixnum,  optional]              :limit          limit the number of results to fetch
       # @see http://www.last.fm/api/show/?service=119
-      def get_similar( artist = nil, mbid = nil, autocorrect = nil, limit = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getSimilar", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit )
+      def get_similar( params )
+        LastFM.get( "#{TYPE}.getSimilar", params )
       end
 
+      # Get the tags applied by an individual user to an artist on Last.fm. If accessed as an authenticated service
+      # and you don't supply a user parameter then this service will return tags for the authenticated user.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @option params [String,  optional]              :user           if called in non-authenticated mode you must specify the user to look up
       # @see http://www.last.fm/api/show/?service=318
-      def get_tags( artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getTags", :secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
-      end
-
+      def get_tags( params )
+        secure = !params.include?(:user)
+        LastFM.requires_authentication if secure
+        LastFM.get( "#{TYPE}.getTags", params, secure )
+      end
+
+      # Get the top albums for an artist, ordered by popularity.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=287
-      def get_top_albums( artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getTopAlbums", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_top_albums( params )
+        LastFM.get( "#{TYPE}.getTopAlbums", params )
       end
 
+      # Get the top fans for an artist on Last.fm, based on listening data.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
       # @see http://www.last.fm/api/show/?service=310
-      def get_top_fans( artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getTopFans", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_top_fans( params )
+        LastFM.get( "#{TYPE}.getTopFans", params )
       end
 
+      # Get the top tags for an artist, ordered by popularity.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
       # @see http://www.last.fm/api/show/?service=288
-      def get_top_tags( artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getTopTags", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_top_tags( params )
+        LastFM.get( "#{TYPE}.getTopTags", params )
       end
 
+      # Get the top tracks by an artist, ordered by popularity.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the artist
+      # @option params [Boolean, optional]              :autocorrect    transform misspelled artist names into correct artist names to be returned in the response
+      # @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=277
-      def get_top_tracks( artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist || mbid
-        LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_top_tracks( params )
+        LastFM.get( "#{TYPE}.getTopTracks", params )
       end
 
+      # Remove a user's tag from an artist.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :tag      a single user tag to remove from this artist
       # @see http://www.last.fm/api/show/?service=315
-      def remove_tag( artist, tag )
+      def remove_tag( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeTag", 'artist'=>artist, 'tag'=>tag )
+        LastFM.post( "#{TYPE}.removeTag", params )
       end
 
+      # Search for an artist by name. Returns artist matches sorted by relevance.
+      #
+      # @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
+      # @option params [String, required] :artist   the artist name
       # @see http://www.last.fm/api/show/?service=272
-      def search( artist, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.search", !:secure, 'artist'=>artist, 'limit'=>limit, 'page'=>page )
+      def search( params )
+        LastFM.get( "#{TYPE}.search", params )
       end
 
+      # Share an artist with Last.fm users or other friends.
+      #
+      # @option params [String,  required] :artist      the artist name
+      # @option params [Array,   required] :recipient   a list of email addresses or Last.fm usernames. maximum is 10
+      # @option params [String,  optional] :message     an optional message to send. if not supplied a default message will be used
+      # @option params [Boolean, optional] :public      optionally show in the sharing users activity feed. defaults to false
       # @see http://www.last.fm/api/show/?service=306
-      def share( artist, recipient, message = nil, public = nil )
+      def share( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.share", 'artist'=>artist, 'recipient'=>recipient, 'message'=>message, 'public'=>public )
+        LastFM.post( "#{TYPE}.share", params )
       end
 
+      # Shout in this artist's shoutbox.
+      #
+      # @option params [String, required] :artist     name of the artist to shout on
+      # @option params [String, required] :message    message to post to the shoutbox
       # @see http://www.last.fm/api/show/?service=408
-      def shout( artist, message )
+      def shout( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.shout", 'artist'=>artist, 'message'=>message )
+        LastFM.post( "#{TYPE}.shout", params )
       end
 
     end

data/lib/lastfm/auth.rb

@@ -4,19 +4,30 @@ module LastFM
 
       TYPE = 'auth'
 
+      # Create a web service session for a user. Used for authenticating a user when the
+      # password can be inputted by the user. Only suitable for standalone mobile devices.
+      #
+      # @option params [String, required] :username     last.fm username
+      # @option params [String, required] :auth_token   md5 hash of the username + the password hash
       # @see http://www.last.fm/api/show?service=266
-      def get_mobile_session( username, auth_token )
-        LastFM.get( "#{TYPE}.getMobileSession", :secure, 'username' => username, 'authToken' => auth_token )
+      def get_mobile_session( params )
+        LastFM.get( "#{TYPE}.getMobileSession", params, :secure )
       end
-    
+
+      # Fetch a session key for a user. The third step in the authentication process.
+      #
+      # @option params [String, required] :token    md5 hash returned by step 1 of the authentication process
       # @see http://www.last.fm/api/show?service=125
-      def get_session( token )
-        LastFM.get( "#{TYPE}.getSession", :secure )
+      def get_session( params )
+        LastFM.get( "#{TYPE}.getSession", params, :secure )
       end
-    
+
+      # Fetch an unathorized request token for an API account. This is step 2 of
+      # the authentication process for desktop applications.
+      #
       # @see http://www.last.fm/api/show?service=265
-      def get_token()
-        LastFM.get( "#{TYPE}.getToken", :secure )
+      def get_token
+        LastFM.get( "#{TYPE}.getToken", {}, :secure )
       end
 
     end

data/lib/lastfm/chart.rb

@@ -4,34 +4,58 @@ module LastFM
 
       TYPE = 'chart'
 
+      # Get the hyped artists chart
+      #
+      # @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=493
-      def get_hyped_artists( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getHypedArtists", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_hyped_artists( params )
+        LastFM.get( "#{TYPE}.getHypedArtists", params )
       end
-    
+
+      # Get the hyped tracks chart
+      #
+      # @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=494
-      def get_hyped_tracks( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getHypedTracks", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_hyped_tracks( params )
+        LastFM.get( "#{TYPE}.getHypedTracks", params )
       end
-    
+
+      # Get the most loved tracks chart
+      #
+      # @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=495
-      def get_loved_tracks( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getLovedTracks", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_loved_tracks( params )
+        LastFM.get( "#{TYPE}.getLovedTracks", params )
       end
-    
+
+      # Get the top artists chart
+      #
+      # @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=496
-      def get_top_artists( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopArtists", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_top_artists( params )
+        LastFM.get( "#{TYPE}.getTopArtists", params )
       end
-    
+
+      # Get the top tags chart
+      #
+      # @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=497
-      def get_top_tags( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopTags", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_top_tags( params )
+        LastFM.get( "#{TYPE}.getTopTags", params )
       end
-    
+
+      # Get the top tracks chart
+      #
+      # @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=498
-      def get_top_tracks( limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'limit'=>limit, 'page'=>page )
+      def get_top_tracks( params )
+        LastFM.get( "#{TYPE}.getTopTracks", params )
       end
 
     end

data/lib/lastfm/event.rb

@@ -4,37 +4,66 @@ module LastFM
 
       TYPE = 'event'
 
+      # Set a user's attendance status for an event.
+      #
+      # @option params [Fixnum, required] :event    numeric last.fm event id
+      # @option params [Symbol, required] :status   attendance status. accepted values are :attending, :maybe_attending, and :not_attending
       # @see http://www.last.fm/api/show?service=307
-      def attend( event, status )
+      def attend( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.attend", 'event'=>event, 'status'=>status )
+        status_codes = { attending: 0, maybe_attending: 1, not_attending: 2 }
+        params[:status] = status_codes[params[:status]] if params.include?(:status)
+        LastFM.post( "#{TYPE}.attend", params )
       end
-    
+
+      # Get a list of attendees for an event.
+      #
+      # @option params [Fixnum, required] :event    numeric last.fm event id
+      # @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=391
-      def get_attendees( event, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getAttendees", !:secure, 'event'=>event, 'limit'=>limit, 'page'=>page )
+      def get_attendees( params )
+        LastFM.get( "#{TYPE}.getAttendees", params )
       end
-    
+
+      # Get the metadata for an event on Last.fm. Includes attendance and lineup information.
+      #
+      # @option params [Fixnum, required] :event    numeric last.fm event id
       # @see http://www.last.fm/api/show?service=292
-      def get_info( event )
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'event'=>event )
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
       end
-    
+
+      # Get shouts for an event.
+      #
+      # @option params [Fixnum, required] :event    numeric last.fm event id
+      # @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=399
-      def get_shouts( event, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getShouts", !:secure, 'event'=>event, 'limit'=>limit, 'page'=>page )
+      def get_shouts( params )
+        LastFM.get( "#{TYPE}.getShouts", params )
       end
-    
+
+      # Share an event with one or more Last.fm users or other friends.
+      #
+      # @option params [Fixnum,  required] :event       numeric last.fm event id
+      # @option params [Array,   required] :recipient   a list of email addresses or Last.fm usernames. maximum is 10
+      # @option params [String,  optional] :message     an optional message to send. if not supplied a default message will be used
+      # @option params [Boolean, optional] :public      optionally show in the sharing users activity feed. defaults to false
       # @see http://www.last.fm/api/show?service=350
-      def share( event, recipient, message = nil, public = nil )
+      def share( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.share", 'event'=>event, 'recipient'=>recipient, 'public'=>public, 'message'=>message )
+        LastFM.post( "#{TYPE}.share", params )
       end
-    
+
+      # Shout in an event's shoutbox.
+      #
+      # @option params [Fixnum, required] :event      numeric last.fm event id
+      # @option params [String, required] :message    message to post to the shoutbox
       # @see http://www.last.fm/api/show?service=409
-      def shout( event, message )
+      def shout( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.shout", 'event'=>event, 'message'=>message )
+        LastFM.post( "#{TYPE}.shout", params )
       end
 
     end