rscrobbler 0.1.0 → 0.2.0

data/lib/lastfm/artist.rb

@@ -1,210 +1,48 @@
 module LastFM
-  class Artist
-    class << self
 
-      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( params )
-        LastFM.requires_authentication
-        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( 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( 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( 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( 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( 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( 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( 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( 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( params )
-        secure = !params.include?(:user)
-        LastFM.requires_authentication if secure
-        LastFM.get( "#{TYPE}.getTags", params, secure )
+  # @attr [Hash] images
+  # @attr [Fixnum] listeners
+  # @attr [String] mbid
+  # @attr [String] name
+  # @attr [Fixnum] playcount
+  # @attr [Array] similar
+  # @attr [Boolean] streamable
+  # @attr [Array] tags
+  # @attr [String]  url
+  # @attr [LastFM::Wiki] wiki
+  class Artist < Struct.new(:images, :listeners, :mbid, :name, :playcount, :similar, :streamable, :tags, :url, :wiki)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :name
+          self.name = node.content
+        when :mbid
+          self.mbid = node.content
+        when :url
+          self.url = node.content
+        when :image
+          self.images ||= {}
+          self.images.merge!({node['size'].to_sym => node.content})
+        when :streamable
+          self.streamable = (node.content == '1')
+        when :listeners
+          self.listeners = node.content.to_i
+        when :playcount
+          self.playcount = node.content.to_i
+        when :stats # nested listeners and playcount
+          node.find('*').each{|child| self.update_from_node(child)}
+        when :similar
+          self.similar = node.find('artist').map do |artist|
+            LastFM::Artist.from_xml(artist)
+          end
+        when :tags
+          self.tags = node.find('tag').map do |tag|
+            LastFM::Tag.from_xml(tag)
+          end
+        when :bio
+          self.wiki = LastFM::Wiki.from_xml(node)
       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( 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( 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( 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( 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( params )
-        LastFM.requires_authentication
-        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( 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( params )
-        LastFM.requires_authentication
-        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( params )
-        LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.shout", params )
-      end
-
     end
+
   end
 end

data/lib/lastfm/buylink.rb

@@ -0,0 +1,34 @@
+module LastFM
+
+  # @attr [Symbol] type  whether the link is for a physical purchase, or a download
+  # @attr [Hash] supplier
+  # @attr [Hash] price
+  # @attr [String] link
+  # @attr [Boolean] is_search
+  class Buylink < Struct.new(:type, :supplier, :price, :link, :is_search)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :supplierName
+          self.supplier ||= {}
+          self.supplier[:name] = node.content
+        when :supplierIcon
+          self.supplier ||= {}
+          self.supplier[:icon] = node.content
+        when :price # nested price & currency
+          node.find('*').each{|child| self.update_from_node(child)}
+        when :amount
+          self.price ||= {}
+          self.price[:amount] = node.content.to_f
+        when :currency
+          self.price ||= {}
+          self.price[:currency] = node.content
+        when :buyLink
+          self.link = node.content
+        when :isSearch
+          self.is_search = (node.content == '1')
+      end
+    end
+
+  end
+end

data/lib/lastfm/event.rb

@@ -1,71 +1,62 @@
 module LastFM
-  class Event
-    class << self
 
-      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( params )
-        LastFM.requires_authentication
-        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( 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( 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( params )
-        LastFM.get( "#{TYPE}.getShouts", params )
+  # @attr [Fixnum] id
+  # @attr [String] title
+  # @attr [String] headliner
+  # @attr [Array<String>] artists
+  # @attr [LastFM::Venue] venue
+  # @attr [Time] start_date
+  # @attr [String] description
+  # @attr [Hash] images
+  # @attr [Fixnum] attendance
+  # @attr [Fixnum] reviews
+  # @attr [String] tag
+  # @attr [String] url  Last.fm url for the event
+  # @attr [String] website  Event website (different from Last.fm url)
+  # @attr [Boolean] cancelled
+  # @attr [Array<String>] tags
+  class Event < Struct.new(:id, :title, :headliner, :artists, :venue, :start_date, :description, :images, :attendance, :reviews, :tag, :url, :website, :cancelled, :tags)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :id
+          self.id = node.content.to_i
+        when :title
+          self.title = node.content
+        when :artists # nested artists and headliner
+          node.find('*').each{|child| self.update_from_node(child)}
+        when :artist
+          self.artists ||= []
+          self.artists << node.content
+        when :headliner
+          self.headliner = node.content
+        when :venue
+          self.venue = LastFM::Venue.from_xml( node )
+        when :startDate
+          self.start_date = Time.parse(node.content)
+        when :description
+          self.description = node.content
+        when :image
+          self.images ||= {}
+          self.images.merge!({node['size'].to_sym => node.content})
+        when :attendance
+          self.attendance = node.content.to_i
+        when :reviews
+          self.reviews = node.content.to_i
+        when :tag
+          self.tag = node.content
+        when :url
+          self.url = node.content
+        when :website
+          self.website = node.content
+        when :tickets
+          # ???
+        when :cancelled
+          self.cancelled = (node.content == '1')
+        when :tags
+          self.tags = node.find('*').each{|tag| tag.content}
       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( params )
-        LastFM.requires_authentication
-        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( params )
-        LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.shout", params )
-      end
-
     end
+
   end
-end
+end

data/lib/lastfm/shout.rb

@@ -0,0 +1,20 @@
+module LastFM
+
+  # @attr [String] author
+  # @attr [String] body
+  # @attr [Time] date
+  class Shout < Struct.new(:author, :body, :date)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :author
+          self.author = node.content
+        when :body
+          self.body = node.content
+        when :date
+          self.date = Time.parse(node.content)
+      end
+    end
+
+  end
+end

data/lib/lastfm/struct.rb

@@ -0,0 +1,34 @@
+module LastFM
+
+  # Prodives modifications to Ruby's Struct class for use within the LastFM module space.
+  # Must be called 'Struct' to play nice with YARD's @attr documentation.
+  class Struct < Struct
+
+    # Override Struct's initialize method to accept a hash of members instead.
+    def initialize(h={})
+      members.each{|m| self[m] = h[m.to_sym]}
+    end
+
+    # Get the Last.fm package name for a Ruby class
+    #
+    # @return [String] the Last.fm package name
+    def self.package
+      self.to_s.downcase.split('::').last
+    end
+
+    # Construct a LastFM::Struct object from XML, using each inheritor's attr_from_node
+    # method to determine how to manipulate individual attributes.
+    #
+    # @param [LibXML::XML::Document] xml  XML obtained from a Last.fm API call
+    # @param [Hash] initial_attributes  Attributes to set before parsing the XML
+    # @return [LastFM::Struct] object contructed from attributes contained in XML
+    def self.from_xml(xml, initial_attributes={})
+      raise NotImplementedError unless self.method_defined?(:update_from_node)
+      xml = xml.find_first(self.package) if xml.is_a?(LibXML::XML::Document)
+      model = self.new(initial_attributes)
+      xml.find('*').each{|child| model.update_from_node(child)}
+      model
+    end
+
+  end
+end

data/lib/lastfm/tag.rb

@@ -1,94 +1,29 @@
 module LastFM
-  class Tag
-    class << self
 
-      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( 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( 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( params )
-        LastFM.get( "#{TYPE}.getTopAlbums", params )
+  # @attr [String] name
+  # @attr [Fixnum] count
+  # @attr [String] url
+  # @attr [Fixnum] reach
+  # @attr [Boolean] streamable
+  # @attr [LastFM::Wiki] wiki
+  class Tag < Struct.new(:name, :count, :url, :reach, :streamable, :wiki)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :name
+          self.name = node.content
+        when :url
+          self.url = node.content
+        when :reach
+          self.reach = node.content.to_i
+        when :count, :taggings
+          self.count = node.content.to_i
+        when :streamable
+          self.streamable = (node.content == '1')
+        when :wiki
+          self.wiki = LastFM::Wiki.from_xml(node)
       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( 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" )
-      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( 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( 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( 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( params )
-        LastFM.get( "#{TYPE}.search", params )
-      end
-
     end
-  end 
+
+  end
 end