scrobbler-ng 2.0.0 → 2.0.1

data/lib/scrobbler/base.rb

@@ -5,64 +5,109 @@ $KCODE = 'u'
 include LibXML
 
 module Scrobbler
-  
+ 
   API_URL     = 'http://ws.audioscrobbler.com/'
   
-class Base
+  class Base
+    # Set the default API key.
+    #
+    # This key will be used by all Scrobbler classes and objects.
+    #
+    # @param [String] api_key The default API key.
+    # @return [nil]
     def Base.api_key=(api_key) 
-        @@api_key = api_key
+      @@api_key = api_key
     end
-
+  
+    # Set the default API secret.
+    #
+    # This secret will be used by all Scrobbler classes and objects.
+    #
+    # @param [String] secret The default API secret.
+    # @return [nil]
     def Base.secret=(secret)
-        @@secret = secret
+      @@secret = secret
     end
-
+  
+    # Get a HTTP/REST connection to the webservice.
+    #
+    # @return [REST::Connection]
     def Base.connection
-        @connection ||= REST::Connection.new(API_URL)
+      @connection ||= REST::Connection.new(API_URL)
     end
     
+    # Clean up a URL parameter.
+    #
+    # @param [String, Symbol] param The parameter which needs cleanup.
+    # @return [String]
     def Base.sanitize(param)
       URI.escape(param.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
     end
-
-    def Base.camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
-      if first_letter_in_uppercase
-        lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
-      else
-        lower_case_and_underscored_word.first.downcase + camelize(lower_case_and_underscored_word)[1..-1]
-      end
-    end
-
-    def Base.constanize(camel_cased_word)
-      names = camel_cased_word.split('::')
+  
+    # Camelize and Constanize a string.
+    #
+    # @param [String,Symbol] word The word which should be camelized and
+    #   constanized.
+    # @return [Constant]
+    def Base.constanize(word)
+      names = word.to_s.gsub(/\/(.?)/) do
+        "::#{$1.upcase}"
+      end.gsub(/(?:^|_)(.)/) { $1.upcase }.split('::')
       names.shift if names.empty? || names.first.empty?
-
+  
       constant = Object
       names.each do |name|
         constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
       end
       constant
     end
-    
+
+    # Initiate a API and parse it.
+    #
+    # @param [String,Symbol] api_method The API method to call.
+    # @param [String,Symbol] parent The parent node to inspect.
+    # @param [Class,String,Symbol] element The name of the node to turn into objects.
+    # @param [Hash<String,Symbol>] parameters The parameters for the method call.
+    # @return [Array<Scrobbler::Base>]
     def Base.get(api_method, parent, element, parameters = {})
-        scrobbler_class = constanize(camelize("scrobbler/#{element.to_s}"))
-        doc = request(api_method, parameters)
-        elements = []
-        doc.root.children.each do |child|
-            next unless child.name == parent.to_s
-            child.children.each do |child2|
-                next unless child2.name == element.to_s
-                elements << scrobbler_class.new_from_libxml(child2)
-            end
-        end
-        elements
+      if (element.is_a?(Class))
+        scrobbler_class = element
+        element = element.to_s.sub("Scrobbler::","").downcase
+      else
+        element = element.to_s
+        scrobbler_class = constanize("scrobbler/#{element}")
+      end
+      doc = request(api_method, parameters)
+      elements = []
+      doc.root.children.each do |child|
+          next unless child.name == parent.to_s
+          child.children.each do |child2|
+              next unless child2.name == element
+              elements << scrobbler_class.new_from_libxml(child2)
+          end
+      end
+      elements
     end
 
-    def Base.post_request(api_method, parameters = {}, request_method = 'get')
+    # Execute a request to the Audioscrobbler webservice
+    #
+    # @param [String,Symbol] api_method The method which shall be called.
+    # @param [Hash] parameter The parameters passed as URL params.
+    # @return [LibXML::XML::Document]
+    def Base.post_request(api_method, parameters = {})
       Base.request(api_method, parameters, 'post')
     end
-
+  
+    # Execute a request to the Audioscrobbler webservice
+    #
+    # @param [String,Symbol] api_method The method which shall be called.
+    # @param [Hash] parameter The parameters passed as URL params.
+    # @param [String] request_method The HTTP verb to be used.
+    # @return [LibXML::XML::Document]
     def Base.request(api_method, parameters = {}, request_method = 'get')
+      raise ArgumentError unless [String, Symbol].member?(api_method.class)
+      raise ArgumentError unless parameters.kind_of?(Hash)
+  
       parameters = {:signed => false}.merge(parameters)
       parameters['api_key'] = @@api_key
       parameters['method'] = api_method.to_s
@@ -70,7 +115,7 @@ class Base
       # Check if we want a signed call and pop :signed
       if parameters.delete :signed
         #1: Sort alphabetically
-        params = parameters.sort{|a,b| a[0].to_s<=>b[0].to_s}
+        params = parameters.sort{|a,b| a.at(0).to_s<=>b.at(0).to_s}
         #2: concat them into one string
         str = params.join('')
         #3: Append secret
@@ -79,7 +124,7 @@ class Base
         md5 = Digest::MD5.hexdigest(str)
         params << [:api_sig, md5]
         params.each do |a|
-          paramlist << "#{sanitize(a[0])}=#{sanitize(a[1])}"
+          paramlist << "#{sanitize(a.at(0))}=#{sanitize(a.at(1))}"
         end
       else
         parameters.each do |key, value|
@@ -90,35 +135,40 @@ class Base
       XML::Document.string(self.connection.send(request_method,url))
     end
     
-    
-    private
-      
-    def Base.mixins(*args)
-      args.each do |arg|
-        if arg == :image
-          extend Scrobbler::ImageClassFuncs
-          include Scrobbler::ImageObjectFuncs
-        elsif arg == :streamable
-          attr_reader :streamable
-          extend StreamableClassFuncs
-          include StreamableObjectFuncs
-        else
-          raise ArgumentError, "#{arg} is not a known mixin"
-        end
-      end
+    # @deprecated
+    def get_response(api_method, instance_name, parent, element, params, force=true)
+      Base.get(api_method, parent, element, params)
     end
-    
-      def populate_data(data = {})
-        data.each do |key, value|
-          instance_variable_set("@#{key.to_s}", value)
-        end
-      end
-
-      def get_response(api_method, instance_name, parent, element, params, force=false)
-        if instance_variable_get("@#{instance_name}").nil? || force
-            instance_variable_set("@#{instance_name}", Base.get(api_method, parent, element, params))
-        end
-        instance_variable_get("@#{instance_name}")
+  
+    # Load information into instance variables.
+    #
+    # @param [Hash<String,Symbol>] data Each entry will be stored as a variable.
+    # @return [nil]
+    def populate_data(data = {})
+      data.each do |key, value|
+        instance_variable_set("@#{key.to_s}", value)
       end
-end # class Base
+    end
+  
+    # Execute a request to the Audioscrobbler webservice
+    #
+    # @param [String,Symbol] api_method The method which shall be called.
+    # @param [Hash] parameter The parameters passed as URL params.
+    # @return [LibXML::XML::Document]
+    def request(api_method, parameters = {}, request_method = 'get')
+      Base.request(api_method, parameters, request_method)
+    end
+  
+    # Call a API method
+    #
+    # @param [String,Symbol] api_method The method which shall be called.
+    # @param [Hash] params The parameters passed as URL params.
+    # @param [String,Symbol] parent the parent XML node to look for.
+    # @param [Class,String,Symbol] element The xml node name which shall
+    #   be converted into an object.
+    # @return [Array]
+    def call(api_method, parent, element, params)
+      Base.get(api_method, parent, element, params)
+    end
+  end # class Base
 end # module Scrobbler

data/lib/scrobbler/basexml.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require File.expand_path('base.rb', File.dirname(__FILE__))
+
+module Scrobbler
+  class BaseXml < Base
+    # Load data out of a XML node
+    def initialize(data = {})
+      raise ArgumentError unless data.kind_of?(Hash)
+      super()
+      unless data[:xml].nil?
+        load_from_xml(data[:xml])
+        data.delete(:xml)
+      end
+    end
+  end
+end

data/lib/scrobbler/event.rb

@@ -1,81 +1,125 @@
+# encoding: utf-8
+
+require File.expand_path('basexml.rb', File.dirname(__FILE__))
+
 module Scrobbler
-  class Event < Base
+  class Event < BaseXml
     # Load Helper modules
     include ImageObjectFuncs
-    extend  ImageClassFuncs
     
-    attr_accessor :id, :title, :start_date, :start_time, :description
-    attr_accessor :reviews, :tag, :url, :artists, :headliner, :image_small
-    attr_accessor :image_medium, :image_large, :attendance, :venue
+    attr_reader :id, :title, :start_date, :start_time, :description
+    attr_reader :reviews, :tag, :url, :artists, :headliner
+    attr_reader :attendance, :venue, :website, :end_date
     
-    class << self
-
-      def update_or_create_from_xml(xml, event=nil)
-        data = {}
-        artists = []
-        headliner = nil
-        venue = nil
+    # Alias for Event.new(:xml => xml)
+    #
+    # @deprecated
+    def self.new_from_libxml(xml)
+      Event.new(:xml => xml)
+    end
 
-        xml.children.each do |child|
-          data[:id] = child.content.to_i if child.name == 'id'
-          data[:title] = child.content if child.name == 'title'
+    # Create a new Scrobbler::Event instance
+    #
+    # @param [Hash] data The options to initialize the class
+    def initialize(data = {})
+      raise ArgumentError unless data.kind_of?(Hash)
+      super(data)
+      data = {:include_info => false}.merge(data)
+      # Load data given as method-parameter
+      load_info() if data.delete(:include_info)
+      populate_data(data)
 
-          if child.name == 'artists'
-            child.children.each do |artist_element|
-              artists << Artist.new(artist_element.content) if artist_element.name == 'artist'
-              headliner = Artist.new(artist_element.content) if artist_element.name == 'headliner'
+      raise ArgumentError, "ID is required" if @id.nil?
+    end
+    
+    # Load the data for this object out of a XML-Node
+    #
+    # @param [LibXML::XML::Node] node The XML node containing the information
+    # @return [nil]
+    def load_from_xml(node)
+      # Get all information from the root's children nodes
+      node.children.each do |child|
+        case child.name.to_s
+          when 'id'
+            @id = child.content.to_i
+          when 'title'
+            @title = child.content.to_s
+          when 'artists'
+            @artists = [] if @artists.nil?
+            child.children.each do |artist|
+              @artists << Artist.new(:name => artist.content) if artist.name == 'artist'
+              @headliner = Artist.new(:name => artist.content) if artist.name == 'headliner'
             end
-            artists << headliner unless headliner.nil? || headliner_alrady_listed_in_artist_list?(artists,headliner)
-          end
-
-          maybe_image_node(data, child)
-          data[:url] = child.content if child.name == 'url'
-          data[:description] = child.content if child.name == 'description'
-          data[:attendance] = child.content.to_i if child.name == 'attendance'
-          data[:reviews]    = child.content.to_i if child.name == 'reviews'
-          data[:tag]        = child.content if child.name == 'tag'
-          data[:start_date] = Time.parse(child.content) if child.name == 'startDate'
-          data[:start_time] = child.content if child.name == 'startTime'
-          venue = Venue.new_from_xml(child) if child.name == 'venue'
-        end
-
-        if event.nil?
-          event = Event.new(data[:id],data)
-        else
-          event.send :populate_data, data
-        end
-
-        event.artists = artists.uniq
-        event.headliner = headliner
-        event.venue = venue
-        event
-      end
-
-      def headliner_alrady_listed_in_artist_list?(artists,headliner)
-        artists.each do |artist|
-          return true if artist.name == headliner.name
-        end
-        false
-      end
-
-      def new_from_libxml(xml)
-        update_or_create_from_xml(xml)
+            @artists << @headliner unless @headliner.nil? || headliner_alrady_listed_in_artist_list?
+          when 'image'
+            check_image_node(child)
+          when 'url'
+            @url = child.content
+          when 'description'
+            @description = child.content
+          when 'attendance'
+            @attendance = child.content.to_i
+          when 'reviews'
+            @reviews = child.content.to_i
+          when 'tag'
+            @tag = child.content
+          when 'startDate'
+            @start_date = Time.parse(child.content)
+          when 'startTime'
+            @start_time = child.content
+          when 'endDate'
+            @end_date = Time.parse(child.content)
+          when 'tickets'
+            # @todo Handle tickets
+          when 'venue'
+            @venue = Venue.new_from_xml(child)
+          when 'website'
+            @website = child.content.to_s
+          when 'text'
+            # ignore, these are only blanks
+          when '#text'
+            # libxml-jruby version of blanks
+          else
+            raise NotImplementedError, "Field '#{child.name}' not known (#{child.content})"
+        end #^ case
+      end #^ do |child|
+      @artists.uniq!
+    end #^ load_from_xml
+    
+    def headliner_alrady_listed_in_artist_list?
+      @artists.each do |artist|
+        return true if artist.name == @headliner.name
       end
+      false
     end
 
-    def initialize(id,input={})
-      raise ArgumentError if id.nil?
-      @id = id
-      populate_data(input)
-      load_info() if input[:include_info]
+    # Indicates if the info was already loaded
+    @info_loaded = false 
+    
+    # Load additional information about this album
+    #
+    # Calls "album.getinfo" REST method
+    #
+    # @todo Parse wiki content
+    # @todo Add language code for wiki translation
+    def load_info
+      return nil if @info_loaded
+      xml = Base.request('event.getinfo', {:event => @id})
+      unless xml.root['status'] == 'failed'
+        xml.root.children.each do |childL1|
+          next unless childL1.name == 'event'
+          load_from_xml(childL1)
+        end # xml.children.each do |childL1|
+        @info_loaded  = true
+      end
     end
 
-    def shouts(force = false)
-      get_response('event.getshouts', :shouts, 'shouts', 'shout', {'event'=>@id}, force)
+    def shouts
+      call('event.getshouts', :shouts, Shout, {:event => @id})
     end
 
-    def attendees(force = false)
-      get_response('event.getattendees', :attendees, 'attendees', 'user', {'event'=>@id}, force)
+    def attendees
+      call('event.getattendees', :attendees, User, {:event  => @id})
     end
 
     def shout
@@ -84,22 +128,13 @@ module Scrobbler
     end
 
     def attend(session, attendance_status)
-      doc = Base.post_request('event.attend',{:event => @id, :signed => true, :status => attendance_status, :sk => session.key})
+      Base.post_request('event.attend',{:event => @id, :signed => true, :status => attendance_status, :sk => session.key})
     end
 
     def share
-      # This function require authentication, but SimpleAuth is not yet 2.0
+      # This function requires authentication, but SimpleAuth is not yet 2.0
       raise NotImplementedError
     end
 
-    # Load additional informatalbumion about this event
-    #
-    # Calls "event.getinfo" REST method
-    def load_info
-      doc = Base.request('event.getinfo', {'event' => @id})
-      doc.root.children.each do |child|        
-        Event.update_or_create_from_xml(child, self) if child.name == 'event'
-      end      
-    end
   end
 end

data/lib/scrobbler/geo.rb

@@ -4,24 +4,16 @@ module Scrobbler
     # Gets a list of events based on the location that
     # the Geo object is set to
     def events(options={})
-      options = set_default_options(options)
-      get_response('geo.getevents', :events, 'events', 'event', options, options[:force])
+      call('geo.getevents', :events, Event, options)
     end
 
     def top_artists(options={})
-      options = set_default_options(options)
-      get_response('geo.gettopartists', :artists, 'topartists', 'artist', options, options[:force])
+      call('geo.gettopartists', :topartists, Artist, options)
     end
 
     def top_tracks(options={})
-      options = set_default_options(options)
-      get_response('geo.gettoptracks', :tracks, 'toptracks', 'track', options, options[:force])
+      call('geo.gettoptracks', :toptracks, Track, options)
     end
 
-    private
-
-    def set_default_options(options={})
-      {:force => false, :page => 1}.merge options
-    end
   end
 end

data/lib/scrobbler/helper/image.rb

@@ -7,14 +7,28 @@ module Scrobbler
   module ImageClassFuncs
     # Check if the given libxml node is an image referencing node and in case
     # of, read it into that given hash of data 
+    #
+    # @param [Hash<Symbol, String>] data The data extracted from an API response
+    # @param [LibXML::XML::Node] node XML node, part of the API response
     def maybe_image_node(data, node)
+      raise ArgumentError unless data.kind_of?(Hash)
+      raise ArgumentError unless node.kind_of?(LibXML::XML::Node)
       if node.name == 'image'
-        data[:image_small] = node.content if node['size'] == 'small'
-        data[:image_medium] = node.content if node['size'] == 'medium'
-        data[:image_large] = node.content if node['size'] == 'large'
-        data[:image_extralarge] = node.content if node['size'] == 'extralarge'
-      end
-    end
+        case node['size'].to_s # convert to string to fix libxml-ruby bug
+          when 'small'
+            data[:image_small] = node.content
+          when 'medium'
+            data[:image_medium] = node.content
+          when 'large'
+            data[:image_large] = node.content
+          when 'extralarge'
+            data[:image_extralarge] = node.content
+          else
+            raise NotImplementedError, "Image size '#{node['size'].to_s}' not supported."
+        end #^ case
+      end #^ if
+    end #^ maybe_ ...
+
   end
   
   # Defines some functions that are used nearly all Scrobbler classes which
@@ -27,10 +41,20 @@ module Scrobbler
     # of, read it into the object
     def check_image_node(node)
       if node.name == 'image'
-        @image_small = node.content if node['size'] == 'small'
-        @image_medium = node.content if node['size'] == 'medium'
-        @image_large = node.content if node['size'] == 'large'
-        @image_extralarge = node.content if node['size'] == 'extralarge'
+        case node['size'].to_s # convert to string to fix libxml-ruby bug
+          when 'small'
+            @image_small = node.content
+          when 'medium'
+            @image_medium = node.content
+          when 'large'
+            @image_large = node.content
+          when 'extralarge'
+            @image_extralarge = node.content
+          when 'mega'
+            @image_mega = node.content
+          else
+            raise NotImplementedError, "Image size '#{node['size'].to_s}' not supported."
+        end #^ case
       end
     end
     
@@ -40,7 +64,8 @@ module Scrobbler
     # 'load_info'-function is defined, it will be called.
     def image(which=:small)
       which = which.to_s
-      raise ArgumentError unless ['small', 'medium', 'large', 'extralarge'].include?(which)      
+      raise ArgumentError unless ['small', 'medium', 'large', 'extralarge',
+        'mega'].include?(which)      
       img_url = instance_variable_get("@image_#{which}")
       if img_url.nil? && responds_to?(:load_info) 
         load_info 
@@ -49,4 +74,4 @@ module Scrobbler
       img_url
     end
   end
-end
+end

data/lib/scrobbler/helper/streamable.rb

@@ -7,7 +7,7 @@ module Scrobbler
   module StreamableClassFuncs
     # Check if the given libxml node is defining if the given content is 
     # streamable. If so, set the flag in the given hash
-    def Base.maybe_streamable_node(data, node)
+    def maybe_streamable_node(data, node)
       if node.name == 'streamable'
         data[:streamable] = ['1', 'true'].include?(node.content)
       end
@@ -15,7 +15,7 @@ module Scrobbler
     
     # Check if the given libxml node has a streamable attribute defining if the
     # given content is streamable. If so, set the flag in the given hash
-    def Base.maybe_streamable_attribute(data, node)
+    def maybe_streamable_attribute(data, node)
       if node['streamable']
         data[:streamable] = ['1', 'true'].include?(node['streamable'])
       end
@@ -36,5 +36,13 @@ module Scrobbler
         @streamable = ['1', 'true'].include?(node.content)
       end
     end
+
+    # Check if the given libxml node has a streamable attribute defining if the
+    # given content is streamable. If so, set the flag in the given hash
+    def maybe_streamable_attribute(node)
+      if node['streamable']
+        @streamable = ['1', 'true'].include?(node['streamable'])
+      end
+    end
   end
-end
+end