shortwave 0.0.1

data/lib/shortwave/facade/remote.rb

@@ -0,0 +1,86 @@
+require 'restclient'
+require 'uri'
+require 'forwardable'
+
+module Shortwave
+  # Includes thin wrapper classes around the Last.fm web services API.
+  #
+  # These classes map one-to-one to the Last.fm API, and are in fact generated from the
+  # HTML documentation the Last.fm provide. They make no attempt to OOify or XMLify the
+  # responses - the results of these methods are just the string responses from Last.fm.
+  # As such, they are a suitable base for building a "real" API on top of, which is
+  # what classes in Shortwave::Model do.
+  #
+  # The general use is:
+  #
+  #    # Create a session for your platform
+  #    session = Shortwave::Authentication::Mobile.new("api_key", "app_secret")
+  #    
+  #    # Authenticate if necessary (if you want to use write methods)
+  #    session.authenticate("user", "password")
+  #
+  #    # Create a facade, passing in the session
+  #    facade = Shortwave::Facade::Artist.new(session)
+  #
+  #    # Call methods on the facade
+  #    facade.top_tags("The feelies")
+  #    # => returns <lfm status="ok"> ... etc.
+  #
+  # Required method parameters in the web api are real method parameters - if the method
+  # has optional parameters, these appear in an options hash after all the required parameters.
+  # You do not need to provide any authentication parameters (+api_key+, +api_sig+ & +sk+) - these
+  # are merged in from the session for you automatically.
+  #
+  # If the request fails, the facade method will raise a RemoteError.
+  #
+  # Each of the facades has further documentation, taken directly from the Last.fm documentation
+  # at http://last.fm/api
+  module Facade
+    # Wraps a RestClient::RequestFailed exception, and delegates +message+, +http_code+
+    # and +response+ to the wrapped exception.
+    #
+    # This class is mainly provided for api stability in case we switch from using RestClient.
+    class RemoteError < RuntimeError
+      extend Forwardable
+      def_delegators :@cause, :message, :to_s, :http_code, :response
+
+      def initialize(cause)
+        @cause = cause
+      end
+    end
+
+    # Base class for each remote facade.
+    #
+    # Remote methods may raise a RemoteError if an http error response is returned from
+    # the Last.fm service.
+    class Remote
+      attr_reader :session
+
+      # Creates a new facade, given a user session
+      def initialize(session)
+        @session = session
+      end
+
+      protected
+      
+      BASE_URI = "http://ws.audioscrobbler.com/2.0/"
+      DISALLOWED = Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")
+      AGENT = "Shortwave 0.0.1 http://shortwave.rubyforge.org/"
+
+      def get(type, data)
+        @session.merge!(type, data)
+        uri = BASE_URI + "?" + data.map {|k,v| "#{k.to_s}=#{URI.escape(v.to_s, DISALLOWED)}"}.join("&")
+        RestClient.get uri, {"User-Agent" => AGENT}
+      rescue RestClient::RequestFailed => e
+        raise RemoteError.new(e)
+      end
+
+      def post(type, data)
+        @session.merge!(type, data, {"User-Agent" => AGENT})
+        RestClient.post BASE_URI, data
+      rescue RestClient::RequestFailed => e
+        raise RemoteError.new(e)
+      end
+    end
+  end
+end

data/lib/shortwave/model/album.rb

@@ -0,0 +1,33 @@
+module Shortwave
+  module Model
+    # An album on Last.fm
+    #
+    # === Attributes
+    #
+    # +name+:: Album name
+    # +url+:: Last.fm site url
+    # +id+:: Last.fm id
+    # +release_date+:: Release date
+    # +listeners+:: Number of listeners
+    # +play_count+:: Number of times tracks from this album have been played
+    # +images+:: An array of album images
+    # +mbid+:: Musicbrainz ID
+    # +artist_name+:: Album's artist
+    # +tags+:: Last.fm user tags
+    class Album < BaseModel
+      element :name, String, :tag => "name|title"
+      element :url, String
+      element :id, Integer
+      element :release_date, Time, :tag => "releasedate"
+      element :listeners, Integer
+      element :play_count, Integer, :tag => "playcount"
+      element :images, String, :tag => "image", :single => false
+      element :mbid, String
+      element :artist_name, String, :tag => "artist"
+      has_many :tags, "Shortwave::Model::Tag", :tag => "toptags/tag"
+
+      identified_by :artist_name, :name
+      taggable
+    end
+  end
+end

data/lib/shortwave/model/artist.rb

@@ -0,0 +1,62 @@
+module Shortwave
+  module Model
+    # An artist. Artists are taggable, shoutable and sharable by a user.
+    #
+    # === Attributes
+    #
+    # +name+:: Artist name
+    # +mbid+:: Musicbrainz ID
+    # +url+:: Url of artist page on the Last.fm site
+    # +play_count+:: The number of times this artist has been played
+    # +listeners+:: The number of listeners this artist has
+    # +biography_summary+:: Textual description of this artist
+    # +biography+:: Full textual description of this artist
+    # +images+:: Images of this artist
+    class Artist < BaseModel
+      element :name, String
+      element :mbid, String
+      element :url, String
+      element :streamable, Boolean
+      element :play_count, Integer, :tag => "stats/playcount"
+      element :listeners, Integer, :tag => "stats/listeners"
+      element :biography_summary, String, :tag => "bio/content"
+      element :biography, String, :tag => "bio/content"
+      element :images, String, :tag => "image", :single => false
+
+      identified_by :name
+      taggable
+      shoutable
+      sharable
+
+      # Events this artist is playing at.
+      def events
+        link :events, :Event, name
+      end
+
+      # Artists similar to this one.
+      def similar
+        link :similar, :Artist, name
+      end
+
+      # This artist's top albums
+      def albums
+        link :top_albums, :Album, name
+      end
+
+      # This artist's top fans
+      def fans
+        link :top_fans, :User, name
+      end
+
+      # This artist's top tags
+      def tags
+        link :top_tags, :Tag, name
+      end
+
+      # This artist's top tracks
+      def tracks
+        link :top_tracks, :Track, name
+      end
+    end
+  end
+end

data/lib/shortwave/model/base_model.rb

@@ -0,0 +1,112 @@
+module Shortwave
+  module Model
+    # Root class for all Shortwave models.
+    class BaseModel
+      # Sets the session on this model, and all nested models
+      def session=(session)
+        @session = session
+        self.class.has_ones.each do |sym| 
+          obj = send(sym)
+          obj.session = session if obj
+        end
+        self.class.has_manys.each {|s| (send(s) || []).each {|o| o.session = session } }
+        session
+      end
+
+      class << self
+        def facade_name
+          @facade_name ||= (name.split("::").last.downcase + "_facade").to_sym
+        end
+
+        def identified_by(*methods)
+          @lastfm_keys = methods
+        end
+
+        # Adds methods to a model to deal with shouts: shouts and shout
+        def shoutable
+          class_eval <<-EOV
+            def shout(message)
+              @session.#{facade_name}.shout(#{@lastfm_keys.join(",")}, message)
+            end
+
+            link_to "Shout", :shouts
+          EOV
+        end
+
+        # Adds methods to a model to deal with tags: tags, add_tags and remove_tag
+        #
+        # Up to ten tags can be added, either strings, or Tag models
+        # A single tag can be removed
+        def taggable
+          class_eval <<-EOV
+            def add_tags(*tags)
+              tag_param = tags[0...10].map {|t| t.to_s }.join(",")
+              @session.#{facade_name}.add_tags(#{@lastfm_keys.join(",")}, tag_param)
+            end
+
+            def remove_tag(tag)
+              @session.#{facade_name}.remove_tag(#{@lastfm_keys.join(",")}, tag.to_s)
+            end
+
+            link_to "Tag", :my_tags, :tags
+          EOV
+        end
+
+        def sharable
+          class_eval <<-EOV
+            def share(recipients, message=nil)
+              params = {}
+              params[:message] = message if message
+              @session.#{facade_name}.share(#{@lastfm_keys.join(",")}, recipients[0...10].map{|r| r.to_s }.join(','), params)
+            end
+          EOV
+        end
+
+        def link_to(klass, method, remote_method=nil)
+          remote_method ||= method
+          class_eval <<-EOV
+            def #{method}
+              response = @session.#{facade_name}.#{remote_method}(#{@lastfm_keys.join(',')}) 
+              #{klass}.parse(response).each {|obj| obj.session = @session }
+            end
+          EOV
+        end
+
+        def inherited(klass)
+          klass.send(:include, HappyMapper)
+          klass.send(:tag, klass.name.split("::").last.downcase)
+
+          # Store every has_one/has_many declaration and use this information
+          # to decide which attributes need a session adding
+          class << klass
+            def has_ones
+              @has_ones ||= []
+            end
+
+            def has_manys 
+              @has_manys ||= []
+            end
+
+            def has_one(sym, *args)
+              super
+              has_ones << sym
+            end
+
+            def has_many(sym, *args)
+              super
+              has_manys << sym
+            end
+          end
+        end
+      end
+      
+      protected
+
+      def link(remote_method, klass, *args)
+        response = @session.send(self.class.facade_name).send(remote_method, *args) 
+        klass = ::Shortwave::Model.const_get(klass)
+        klass.parse(response).each {|obj| obj.session = @session }
+      end
+    end
+  end
+end

data/lib/shortwave/model/chart_dates.rb

@@ -0,0 +1,15 @@
+module Shortwave
+  module Model
+    # A chart date range. This is only really used internally.
+    #
+    # === Attributes
+    #
+    # from:: the date the chart starts
+    # to:: the date the chart finishes
+    class ChartDates < BaseModel
+      tag "chart"
+      attribute :from, Time
+      attribute :to, Time
+    end
+  end
+end

data/lib/shortwave/model/comparison.rb

@@ -0,0 +1,15 @@
+module Shortwave
+  module Model
+    # A comparison between two Last.fm users
+    #
+    # === Attributes
+    # 
+    # +score+:: A number between 0 and 1 representing how similar users are.
+    # +artists+:: Artists both users have in common
+    class Comparison < BaseModel
+      tag "comparison"
+      element :score, Float, :tag => "result/score"
+      has_many :artists, "Model::Artist", :tag => "result/artists/artist"
+    end
+  end
+end

data/lib/shortwave/model/event.rb

@@ -0,0 +1,55 @@
+module Shortwave
+  module Model
+    # An event.
+    #
+    # == Attributes
+    # +id+:: Last.fm id
+    # +name+:: Event name
+    # +description+:: Event description
+    # +attendance_count+:: Number of last.fm user's attending
+    # +review_count+:: Number of reviews
+    # +starts_at+:: The start time
+    # +url+:: Last.fm site url
+    # +venue+:: Event venue
+    class Event < BaseModel
+      element :id, Integer
+      element :description, String
+      element :url, String
+      element :attendance_count, Integer, :tag => "attendance"
+      element :review_count, Integer, :tag => "reviews"
+      element :starts_at, Time, :tag => "startDate"
+      element :name, String, :tag => "title"
+      element :headliner_raw, String, :tag => "artists/headliner"
+      element :artists_raw, String, :tag => "artists/artist", :single => false
+      has_one :venue, "Model::Venue"
+
+      identified_by :id
+      shoutable
+      sharable
+
+      # Returns the list of users attending this event
+      def attendees
+        link :attendees, :User, id
+      end
+
+      # Mark the current session user's attendance at this event
+      #
+      # Possible statuses are +:yes+, +:no+ and +:maybe+
+      def attend(status=:yes)
+        i = [:yes, :maybe, :no].index(status)
+        @session.event_facade.attend(id, i)
+        true
+      end
+
+      # Returns the headline act for this event
+      def headliner
+        @headliner ||= artists.detect {|a| a.name == headliner_raw }
+      end
+
+      # Returns the list of artists playing at this event
+      def artists
+        @artists ||= artists_raw.map {|a| @session.artist.build(:name => a) }
+      end
+    end
+  end
+end

data/lib/shortwave/model/group.rb

@@ -0,0 +1,26 @@
+require File.dirname(__FILE__) + "/weekly_charts"
+
+module Shortwave
+  module Model
+    # A Last.fm user group.
+    #
+    # === Attributes
+    #
+    # name:: the group name
+    class Group < BaseModel
+      attr_accessor :name
+      identified_by :name
+      include WeeklyCharts
+
+      # Returns the group's members. Currently only 50 users are returned
+      def members
+        link :members, "User", name
+      end
+
+      # The group name
+      def to_s
+        name
+      end
+    end
+  end
+end

data/lib/shortwave/model/location.rb

@@ -0,0 +1,45 @@
+module Shortwave
+  module Model
+    # A location
+    #
+    # === Attributes
+    # +latitude+:: Latitude
+    # +longitude+:: Longitude
+    # +street_address+:: Street address
+    # +city+:: City
+    # +postcode+:: Post code
+    # +country+:: Country name
+    class Location < BaseModel
+      tag "location"
+      element :latitude, Float, :tag => "geo:point/geo:lat"
+      element :longitude, Float, :tag => "geo:point/geo:long"
+      element :city, String
+      element :country, String
+      element :street_address, String, :tag => "street"
+      element :postcode, String, :tag => "postalcode"
+
+      # Popular artists in this country. Needs country to be defined
+      def artists
+        link :top_artists, :Artist, country
+      end
+
+      # Popular tracks in this location
+      def tracks
+        args = [country]
+        args << {:location => city} if city
+        link :top_tracks, :Track, *args
+      end
+
+      # Return events near this location
+      def events
+        if latitude && longitude
+          link :events, :Event, :lat => latitude, :long => longitude
+        elsif city
+          link :events, :Event, :location => city
+        elsif country
+          link :events, :Event, :location => country
+        end
+      end
+    end
+  end
+end