rscrobbler 0.2.2 → 0.3.0

data/lib/lastfm/radio.rb

@@ -0,0 +1,39 @@
+module LastFM
+  class Radio
+    class << self
+
+      # 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( "radio.getPlaylist", params, :secure )
+      end
+
+      # 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( "radio.search", params )
+      end
+
+      # 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( "radio.tune", params )
+      end
+
+    end
+  end
+end

data/lib/lastfm/shout.rb

@@ -1,20 +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) rescue nil
-      end
-    end
-
-  end
-end
+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) rescue nil
+      end
+    end
+
+  end
+end

data/lib/lastfm/struct.rb

@@ -1,40 +1,59 @@
-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
-
-    def to_json(*a)
-      members.inject({}){|map, m|
-        map[m] = self[m]; map
-      }.to_json(*a)
-    end
-
-  end
-end
+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
+
+    def self.inherited(child)
+      child.class_eval do
+        members.each do |mem|
+          # Override member= methods to filter through parse_node when given an XML::Node
+          define_method(:"#{mem}=") do |val|
+            val = parse_node(mem, val) if val.is_a?(LibXML::XML::Node)
+            super val
+          end
+        end if public_methods.include?(:members)
+      end
+
+      super
+    end
+
+    # 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={})
+      xml = xml.find_first(self.package) if xml.is_a?(LibXML::XML::Document)
+      model = self.new(initial_attributes)
+      xml.find('*').each{|node|
+        if self.method_defined?(:update_from_node)
+          model.update_from_node(node)
+        else
+          model.send(:"#{node.name}=", node)
+        end
+      }
+      model
+    end
+
+    def to_json(*a)
+      members.inject({}){|map, m|
+        map[m] = self[m]; map
+      }.to_json(*a)
+    end
+
+  end
+end

data/lib/lastfm/tag.rb

@@ -1,29 +1,144 @@
-module LastFM
-
-  # @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
-    end
-
-  end
-end
+module LastFM
+
+  # @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
+    end
+
+    # API Methods
+    class << self
+
+      # Get the metadata for a tag.
+      #
+      # @option params [String, required] :tag    the tag name
+      # @option params [String, optional] :lang   the language to return the summary in, expressed as an ISO 639 alpha-2 code
+      # @return [LastFM::Tag] tag constructed from the metadata contained in the response
+      # @see http://www.last.fm/api/show?service=452
+      def get_info( params )
+        xml = LastFM.get( "tag.getInfo", params )
+        LastFM::Tag.from_xml( xml )
+      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
+      # @return [Array<LastFM::Tag>] similar tags, ordered by similarity
+      # @see http://www.last.fm/api/show?service=311
+      def get_similar( params )
+        xml = LastFM.get( "tag.getSimilar", params )
+        xml.find('similartags/tag').map do |tag|
+          LastFM::Tag.from_xml( tag )
+        end
+      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
+      # @return [Array[LastFM::Album]] list of albums, ordered by tag count
+      # @see http://www.last.fm/api/show?service=283
+      def get_top_albums( params )
+        xml = LastFM.get( "tag.getTopAlbums", params )
+        xml.find('topalbums/album').map do |album|
+          LastFM::Album.from_xml( album )
+        end
+      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
+      # @return [Array[LastFM::Artist]] list of artists, ordered by tag count
+      # @see http://www.last.fm/api/show?service=284
+      def get_top_artists( params )
+        xml = LastFM.get( "tag.getTopArtists", params )
+        xml.find('topartists/artist').map do |artist|
+          LastFM::Artist.from_xml( artist )
+        end
+      end
+
+      # Fetches the top global tags on Last.fm, sorted by popularity (number of times used).
+      #
+      # @return [Array<LastFM::Tag>] list of tags ordered by popularity
+      # @see http://www.last.fm/api/show?service=276
+      def get_top_tags
+        xml = LastFM.get( "tag.getTopTags" )
+        xml.find('toptags/tag').map do |tag|
+          LastFM::Tag.from_xml( tag )
+        end
+      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
+      # @return [Array[LastFM::Track]] list of tracks, ordered by tag count
+      # @see http://www.last.fm/api/show?service=285
+      def get_top_tracks( params )
+        xml = LastFM.get( "tag.getTopTracks", params )
+        xml.find('toptracks/track').map do |track|
+          LastFM::Track.from_xml( track )
+        end
+      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( "tag.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( "tag.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
+      # @return [Array<LastFM::Tag>] list of tags sorted by relevance
+      # @see http://www.last.fm/api/show?service=273
+      def search( params )
+        xml = LastFM.get( "tag.search", params )
+        xml.find('results/tagmatches/tag').map do |tag|
+          LastFM::Tag.from_xml( tag )
+        end
+      end
+
+    end
+  end
+end

data/lib/lastfm/tasteometer.rb

@@ -0,0 +1,35 @@
+module LastFM
+  class Tasteometer
+    class << self
+
+      # 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( 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( "tasteometer.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( "tasteometer.compareGroup", params )
+      end
+
+    end
+  end
+end