shortwave 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,10 @@
+*~
+\#*
+.\#*
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+tmp
+doc

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/happymapper"]
+	path = vendor/happymapper
+	url = git://github.com/knaveofdiamonds/happymapper.git

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Roland Swingler
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,74 @@
+= Shortwave
+
+Shortwave aims to be a complete API wrapper for the Last.fm web service.
+
+Shortwave is split into two: the Facade, which provides a low-level thin wrapper around the
+remote api, and the Model (which uses the Facade) which provides a more OO view of the api.
+It would be possible to build your own api on top of the Facade if you don't like the Model
+api provided - the two are fairly separate. See the docs for the Facade model if you want to
+use it directly.
+
+<b>Shortwave is currently pre-alpha. This means both the API and dependencies may change quite 
+a bit over forthcoming releases.</b>
+
+== Advantages over other libraries.
+
+* Shortwave aims to be complete. The facade is autogenerated from the Last.fm api documentation
+  so as the last.fm api evolves it should be possible to keep it in sync relatively easily
+* No enforced opinions - the Facade is a very thin layer, so you can use it directly and treat
+  the returned XML as you please.
+* Supports all 3 authentication types Last.fm provide.
+* Doesn't rely on static/class properties for things like session keys. This means you can build
+  applications which have multiple users signed in.
+
+== Examples
+
+You need to create a session using one of the Authentication mechanisms:
+
+    session = Shortwave::Authentication::Mobile.new("your_api_key", "your_app_secret")
+    session.authenticate("user","password")
+
+See the documentation for each of the Session types for how to authenticate for your
+platform. Once you have a session, you can get model objects from it:
+
+    session.artist.search("The feelies") # => returns a list of Artists
+    session.user.logged_in_user # => the current user
+    session.tag.popular # => the most popular tags
+
+See the Provider docs for more details of how you can access models. Models have attributes
+and links to other models.
+
+    venue = session.venue.search("Koko").first
+    venue.city # => "London"
+    venue.events # => "list of events"
+    venue.events.first.artist # => an Artist
+
+== Current limiations & TODOs
+
+* Paged methods only provide the first page of results when accessed through the model. The goal
+  is to make it transparent that you may have to make n remote calls to get a certain number of
+  results. You can, of course, access arbitrary numbers of results through the Facade methods.
+* Not all attributes will be populated on Models when accessed from different method calls. This
+  is down to the set of data Last.fm returns. The goal is to have missing attributes be populated
+  as needed by further api calls.
+* Might be nice to have Playlists use another ruby XSPF library for more functionality.
+* Radio tuning not done yet.
+* HTTP caching
+* in-built request throttling
+
+== Contributions
+
+Contributions are welcome. Source is on github at http://github.com/knaveofdiamonds/shortwave
+
+== Dependencies & Credits
+
+Shortwave depends on the following gems:
+
+* Nokogiri
+* Restclient
+
+Shortwave also includes a version of HappyMapper (under vendor) copyright John Nunemaker, hacked about to work directly with Nokogiri documents and fix some bugs. See vendor/happymapper/License for details.
+
+== Copyright
+
+Copyright (c) 2009 Roland Swingler. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,133 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require "lib/shortwave/facade/build/facade_builder"
+
+  include Shortwave::Facade::Build
+  namespace :facade do
+    directory "tmp/lastfm"
+
+    task :scrape_method_index => "tmp/lastfm" do
+      REMOTE_METHOD_DEFINITIONS = FacadeBuilder.new.remote_method_definitions("tmp/lastfm/intro.yml")
+    end
+
+    task :scrape => :scrape_method_index do
+      methods = REMOTE_METHOD_DEFINITIONS.values.inject {|a, b| a.merge(b) }
+      methods.each do |name, uri|
+        if ! File.exists?("tmp/lastfm/#{name}.html")
+          response = DocumentationRemote.get(uri)
+          File.open("tmp/lastfm/#{name}.html", "w") {|fh| fh.write(response) }
+          warn "Got HTML documentation for #{name}"
+        end
+      end
+    end
+
+    task :parse => :scrape do
+      REMOTE_METHODS = {}
+      REMOTE_METHOD_DEFINITIONS.each do |klass_name, methods|
+        REMOTE_METHODS[klass_name] = []
+        methods.keys.each do |method_name|
+          warn "parsing #{method_name}"
+          REMOTE_METHODS[klass_name] << RemoteMethod.new( File.read("tmp/lastfm/#{method_name}.html"))
+        end
+      end
+    end
+
+    # Fixes any ommissions or mistakes in the HTML documentation
+    task :patch => :parse do
+      patch_methods "Tag", :top_artists, :top_tracks, :top_albums do |method|
+        method.parameters << Parameter.new(:tag, true, "Last.fm tag")
+      end
+      patch_methods "Group", :weekly_album_chart do |method|
+        method.parameters.delete_if {|p| p.name == :user}
+        method.parameters << Parameter.new(:group, true, "Group name")
+      end
+    end
+
+    def patch_methods(klass, *methods, &block)
+      REMOTE_METHODS[klass].select {|m| methods.include?(m.name) }.each do |method|
+        yield method
+      end
+    end
+
+    task :build => :patch do
+      KLASSES = REMOTE_METHODS.map do |klass_name, methods|
+        warn "Building #{klass_name}"
+        methods.inject(RubyClass.new(klass_name)) do |klass, method|
+          klass.methods << RubyMethod.new(method)
+          klass
+        end
+      end
+    end
+
+    desc "Scrapes the HTML documentation from the Last.FM site and uses it to construct ruby facade objects"
+    task :compile => :build do
+      klasses = KLASSES
+      File.open("lib/shortwave/facade/lastfm.rb", "w") do |fh|
+        fh.write ERB.new(File.read("lib/shortwave/facade/build/facade_template.erb")).result(binding)
+      end
+    end
+  end
+
+rescue LoadError
+  warn "Cannot build a fresh Facade::Remote - missing gems (nokogiri)?"
+end
+
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "shortwave"
+    gem.summary = "A Last.fm API wrapper"
+    gem.email = "roland.swingler@gmail.com"
+    gem.homepage = "http://shortwave.rubyforge.org"
+    gem.authors = ["Roland Swingler"]
+    gem.add_dependency("rest-client", ">= 0.9.2")
+    gem.add_dependency("nokogiri", ">= 1.2.3")
+    gem.rubyforge_project = "shortwave"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "shortwave #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/*.rb')
+  rdoc.rdoc_files.include('lib/shortwave/*.rb')
+  rdoc.rdoc_files.include('lib/shortwave/facade/*.rb')
+  rdoc.rdoc_files.include('lib/shortwave/model/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/shortwave.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/shortwave")
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/../vendor/happymapper/lib")
+require 'happymapper'
+require 'authentication'
+require 'facade'
+require 'providers'
+require 'model/base_model'
+Dir[File.dirname(__FILE__) + "/shortwave/model/*.rb"].each {|model| require model }
+
+module Shortwave
+  Authentication::Session.send(:include, Provider::ProviderMethods)
+end

data/lib/shortwave/authentication.rb

@@ -0,0 +1,107 @@
+require 'nokogiri'
+require 'digest/md5'
+include Digest
+
+module Shortwave
+  # Authentication classes.
+  #
+  # See http://www.last.fm/api/authentication for more details on how Last.fm expects
+  # you to authenticate. The Sessions take care of method signatures and so on for
+  # you.
+  module Authentication
+    # Indicates that you have tried to call a remote method that require authentication,
+    # but have not authenticated yet.
+    class NotAuthenticated < StandardError
+    end
+
+    # Base functionality for session-based authentication mechanisms. Don't use this
+    # directly - use one of its subclasses: Web, Desktop or Mobile.
+    class Session
+      attr_reader :session_key
+      
+      # Creates a new session with your api account key and secret. If you have already
+      # authenticated and stored a session key, you can provide it to save having to
+      # authenticate again.
+      def initialize(api_key, secret, session_key=nil)
+        @api_key, @secret, @session_key = api_key, secret, session_key
+        @facade = Facade::Auth.new(self)
+      end
+
+      # Is the user signed in to Last.fm?
+      def signed_in?
+        ! @session_key.nil?
+      end
+      
+      # Merges relevant authentication details with method parameters.
+      def merge!(type, params)
+        raise NotAuthenticated.new("Requires authentication!") if type == :session && @session_key.nil?
+
+        params.merge!(:api_key => @api_key)
+        params.merge!(:sk => @session_key) if type == :session
+        params.merge!(:api_sig => signature(params)) if type == :session || type == :signed
+        params
+      end
+
+      # Generates a method signature for method parameters.
+      def signature(params)
+        sorted_params = params.map {|k,v| [k.to_s, v.to_s] }.sort_by {|a| a[0] }
+        MD5.hexdigest(sorted_params.flatten.join("") + @secret)
+      end
+
+      protected
+
+      # Parses the response to Auth.getSession
+      def parse_session_response(response)
+        doc = Nokogiri::XML(response)
+        if doc.root['status'] = 'ok'
+          @session_key = doc.css("key").text.strip 
+        else
+          raise doc.css("error").text
+        end
+      end
+    end
+
+    # Authentication for mobile applications. Don't use this for web/desktop applications
+    # use either Authentication::Web or Authentication::Desktop instead
+    class Mobile < Session
+      # Authenticates with a user's username and password
+      def authenticate(username, password)
+        response = @facade.mobile_session(username, MD5.hexdigest(username + MD5.hexdigest(password)))
+        parse_session_response(response)
+      end
+    end
+
+    # Authentication for web applications. Send your user to the page given by +uri+
+    # and use the token provided to your callback url as an argument to +authenticate+
+    class Web < Session
+      # The uri you should direct users to in their web browser, so they can authenticate. If successful,
+      # the callback url defined in your api account will be called, with a token parameter. Pass this
+      # token to the authenticate method.
+      def uri
+        "http://www.last.fm/api/auth/?api_key=#{@api_key}"
+      end
+
+      # Gets an authenticated session key. Call after the user has logged in at +uri+ with the
+      # token returned to your callback uri.
+      def authenticate(token)
+        parse_session_response(@facade.session(token))
+      end
+    end
+
+    # Authentication for destop applications. Send your user to the page given by +uri+
+    # and then call +authenticate+.
+    class Desktop < Session
+      # A uri the user should log in at.
+      def uri
+        response = @facade.token
+        @token = Nokogiri::XML(response).css("token").text.strip
+        "http://www.last.fm/api/auth/?api_key=#{@api_key}&token=#{@token}"
+      end
+
+      # Gets an authenticated session key. Call after the user has logged in at +uri+.
+      def authenticate
+        parse_session_response(@facade.session(token))
+      end
+    end
+  end
+end

data/lib/shortwave/facade.rb

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + '/authentication'
+require File.dirname(__FILE__) + '/facade/remote'
+require File.dirname(__FILE__) + '/facade/lastfm'

data/lib/shortwave/facade/build/facade_builder.rb

@@ -0,0 +1,199 @@
+require 'nokogiri'
+require 'httparty'
+require 'yaml'
+
+module Shortwave
+  module Facade
+    module Build
+      METHOD_NAME_CSS = "#wstitle ~ h1"
+      PARAMETER_CSS   = "#wsdescriptor h2 ~ .param"
+      SAMPLE_CSS      = "#sample pre"
+      DESCRIPTION_CSS = ".wsdescription"
+      METHOD_TYPE_CSS = "#wsdescriptor"
+      REMOTE_CLASS    = "li.package"
+
+      COMBINED_PARAMS = /^(.+)\[(.+)\]$/
+      PARAMETER_TEXT  = /\s*\(([^\)]+)\)\s*:\s*(.*)/
+      IN_WORD_CAPS    = /(.)([A-Z])/
+      STARTS_WITH_GET = /^.+\.(get)?/
+
+
+      # Various Helper methods that belong on String
+      module StringExtensions
+        # Convert a string like FooBar to foo_bar
+        def camel_to_snake
+          gsub(IN_WORD_CAPS,"\\1_\\2").tr('A-Z','a-z')
+        end
+      end
+      String.send(:include, StringExtensions)
+
+
+      # Helper methods for constructing the Facades
+      class FacadeBuilder
+        def remote_method_definitions(location)
+          return @method_definitions if @method_definitions
+          if File.exists?( location )
+            @method_definitions = YAML.load(File.read(location))
+          else
+            response = Build::DocumentationRemote.scrape_remote_method_index
+            File.open(location, "w") {|fh| fh.write(response.to_yaml) }
+            @method_definitions = response
+          end
+        end
+      end
+
+      # A remote facade for the Last FM html documentation
+      class DocumentationRemote
+        include HTTParty
+        base_uri "http://last.fm"
+
+        def self.scrape_remote_method_index
+          html = get("/api/intro")
+          Nokogiri::HTML(html).css(REMOTE_CLASS).inject({}) do |hsh, node|
+            hsh[node.text] = node.next.next.css("a").inject({}) do |h, anchor|
+              h[anchor.text] = anchor["href"]
+              h
+            end
+            hsh
+          end
+        end
+      end
+
+
+      # The class of a RemoteFacade to be generated
+      class RubyClass
+        attr_reader :name, :methods
+
+        def initialize(name)
+          @name = name
+          @methods = []
+        end
+      end
+
+
+      # A ruby method in a RemoteFacade that will be generated
+      class RubyMethod
+        attr_accessor :signature
+        attr_reader   :comment, :body, :name
+
+        def initialize(node)
+          @comment = []
+          @body = []
+          @node = node
+          @parameters = node.parameters || []
+          @required, @optional = (@parameters).partition {|p| p.required? }
+          @required.reject! {|p| [:api_key, :api_sig, :sk].include?(p.name) }
+
+          build_comment
+          build_signature
+          build_body
+          self
+        end
+
+        private
+
+        def build_body
+          mode = if @parameters.any? {|p| p.name == :sk }
+                   :session
+                 elsif @parameters.any? {|p| p.name == :api_sig }
+                   :signed
+                 else
+                   :standard
+                 end
+
+          get_line = "#{@node.http_method}(:#{mode}, {:method => \"#{@node.remote_name}\""
+          @required.each {|p| get_line << ", :#{p.name} => #{p.name}" }
+          get_line << "}"
+          get_line << ".merge(options)" unless @optional.empty?
+          get_line << ")"
+          @body << get_line
+        end
+
+        def build_signature
+          @signature = "#{@node.name}"
+          unless @node.parameters.nil? || @node.parameters.empty?
+            params = @required.map {|p| p.name }
+            params << "options={}" unless @optional.empty?
+            @signature << "(" << params.join(", ") << ")"
+          end
+        end
+
+        def build_comment
+          comment << "# #{@node.description}" if @node.description
+
+          unless @required.empty?
+            comment << "#"
+            @required.each {|p| comment << "# +#{p.name}+:: #{p.description}" }
+          end
+
+          unless @optional.empty?
+            comment << "#"
+            comment << "# <b>Options</b>"
+            @optional.each {|p| comment << "# +#{p.name}+:: #{p.description}" }
+          end
+        end
+      end
+
+
+      # A parameter used in a Last FM api method call.
+      class Parameter
+        attr_reader :name, :description
+
+        def initialize(name, required, description)
+          @name, @required, @description = name, required, description.gsub(/\s+/, ' ')
+        end
+
+        # Returns an array of Parameters, given an HTML page from the Last FM API 
+        # method documentation
+        def self.parse(html)
+          doc = html.kind_of?(Nokogiri::HTML::Document) ? html : Nokogiri::HTML(html)
+
+          doc.css(PARAMETER_CSS).map do |node|
+            name = node.text.strip
+            unless name.nil? || name.empty?
+              if match = name.match(COMBINED_PARAMS)
+                match[2].split("|").map {|v| make_parameter(node, match[1] + v) }
+              else
+                make_parameter(node, name)
+              end
+            end
+          end.flatten.compact
+        end
+
+        # Returns true if this parameter is required
+        def required?
+          @required
+        end
+
+        private
+
+        def self.make_parameter(node, name)
+          if match = node.next.text.match(PARAMETER_TEXT)
+            self.new(name.to_sym, match[1].start_with?("Required"), match[2])
+          else
+            self.new(name.to_sym, true, "")
+          end
+        end
+      end
+
+
+      # Represents an available method in the Last FM 'rest' api. Provides information
+      # about how to call the method.
+      class RemoteMethod
+        attr_reader :name, :remote_name, :parameters, :description, :http_method, :sample_response
+
+        # Creates a RemoteMethod, given an html page from the Last FM API documentation.
+        def initialize(html)
+          doc = Nokogiri::HTML(html)
+
+          @remote_name     = doc.css(METHOD_NAME_CSS).text.strip
+          @name            = @remote_name.sub(STARTS_WITH_GET,'').camel_to_snake.to_sym
+          @parameters      = Parameter.parse(doc)
+          @description     = doc.css(DESCRIPTION_CSS).text.strip.gsub(/\s+/, ' ')
+          @http_method     = doc.css(METHOD_TYPE_CSS).text.include?("HTTP POST") ? :post : :get
+          @sample_response = doc.css(SAMPLE_CSS).text.strip
+        end
+      end
+    end
+  end
+end