rbrainz 0.4.2 → 0.5.0

data/lib/rbrainz/webservice/includes.rb

@@ -1,4 +1,5 @@
-# $Id: includes.rb 203 2008-03-17 11:00:15Z phw $
+# -*- coding: utf-8 -*-
+# $Id: includes.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -42,6 +43,7 @@ module MusicBrainz
     
       # Includes is a hash with the following fields:
       # [:aliases]      Include aliases (boolean).
+      # [:release_groups] Include release groups (boolean).
       # [:releases]     Array of release types that should be included
       #                 in the result. All releases of the artist that match
       #                 all of those types will be included. Use the constants
@@ -55,7 +57,14 @@ module MusicBrainz
       # [:track_rels]   Include track relationships (boolean).
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
+      # [:counts]       Includes the track number (boolean).
+      # [:release_events] Includes the release events (boolean).
+      # [:discs]        Include the disc IDs (boolean).
+      # [:labels]       Include the labels under which the release
       # [:tags]         Include tags (boolean).
+      # [:user_tags]    Include user tags (boolean).
+      # [:ratings]      Include ratings (boolean).
+      # [:user_ratings] Include user ratings (boolean).
       # 
       #--
       # TODO:: Check release types. It's possible that :releases
@@ -63,8 +72,9 @@ module MusicBrainz
       #++
       def initialize(includes)
         Utils.check_options includes, 
-          :aliases, :artist_rels, :release_rels, :track_rels, 
-          :label_rels, :url_rels, :tags, :releases, :va_releases
+          :aliases, :artist_rels, :release_rels, :track_rels, :label_rels,
+          :url_rels, :tags, :release_groups, :releases, :va_releases, :counts,
+          :release_events, :discs, :labels, :user_tags, :ratings, :user_ratings
         @parameters = Array.new
         @parameters << 'aliases'      if includes[:aliases]
         @parameters << 'artist-rels'  if includes[:artist_rels]
@@ -72,7 +82,15 @@ module MusicBrainz
         @parameters << 'track-rels'   if includes[:track_rels]
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
+        @parameters << 'counts'       if includes[:counts]
+        @parameters << 'release-events' if includes[:release_events]
+        @parameters << 'release-groups' if includes[:release_groups]
+        @parameters << 'discs'        if includes[:discs]
+        @parameters << 'labels'       if includes[:labels]
         @parameters << 'tags'         if includes[:tags]
+        @parameters << 'user_tags'    if includes[:user_tags]
+        @parameters << 'ratings'      if includes[:ratings]
+        @parameters << 'user_ratings' if includes[:user_ratings]
         
         includes[:releases].each {|release_type|
           @parameters << 'sa-' + Utils.remove_namespace(release_type.to_s)
@@ -85,17 +103,36 @@ module MusicBrainz
       
     end
     
+    # A specification on how much data to return with a release group.
+    class ReleaseGroupIncludes < AbstractIncludes
+    
+      # Includes is a hash with the following fields:
+      # [:artist]       Include track artist (boolean).
+      # [:releases]     Include releases of the release group (boolean).
+      def initialize(includes)
+        Utils.check_options includes, 
+            :artist, :releases
+        @parameters = Array.new
+        @parameters << 'artist'       if includes[:artist]
+        @parameters << 'releases'       if includes[:releases]
+      end
+    
+    end
+    
     # A specification on how much data to return with a release.
     class ReleaseIncludes < AbstractIncludes
     
       # Includes is a hash with the following fields:
       # [:artist]       Include track artist (boolean).
       # [:counts]       Includes the track number (boolean).
+      # [:release_groups] Includes the release groups (boolean).
       # [:release_events] Includes the release events (boolean).
       # [:discs]        Include the disc IDs (boolean).
       # [:tracks]       Include the release tracks (boolean).
       # [:labels]       Include the labels under which the release
       #                 was published (boolean).
+      # [:isrcs]        Include the ISRCs of the tracks (boolean).
+      #                 Requires that :tracks is set, too.
       # [:artist_rels]  Include artist relationships (boolean).
       # [:release_rels] Include release relationships (boolean).
       # [:track_rels]   Include track relationships (boolean).
@@ -104,18 +141,24 @@ module MusicBrainz
       # [:track_level_rels] Include the relationships for the
       #                     single tracks as well (boolean).
       # [:tags]         Include tags (boolean).
+      # [:user_tags]    Include user tags (boolean).
+      # [:ratings]      Include ratings (boolean).
+      # [:user_ratings] Include user ratings (boolean).
       def initialize(includes)
         Utils.check_options includes, 
-            :artist, :counts, :release_events, :discs, :tracks, 
-            :labels, :artist_rels, :release_rels, :track_rels, 
-            :label_rels, :url_rels, :track_level_rels, :tags
+            :artist, :counts, :release_groups, :release_events, :discs, :tracks,
+            :labels, :isrcs, :artist_rels, :release_rels, :track_rels,
+            :label_rels, :url_rels, :track_level_rels, :tags, :user_tags,
+            :ratings, :user_ratings
         @parameters = Array.new
         @parameters << 'artist'       if includes[:artist]
         @parameters << 'counts'       if includes[:counts]
+        @parameters << 'release-groups' if includes[:release_groups]
         @parameters << 'release-events' if includes[:release_events]
         @parameters << 'discs'        if includes[:discs]
         @parameters << 'tracks'       if includes[:tracks]
         @parameters << 'labels'       if includes[:labels]
+        @parameters << 'isrcs'        if includes[:isrcs]
         @parameters << 'artist-rels'  if includes[:artist_rels]
         @parameters << 'release-rels' if includes[:release_rels]
         @parameters << 'track-rels'   if includes[:track_rels]
@@ -123,6 +166,9 @@ module MusicBrainz
         @parameters << 'url-rels'     if includes[:url_rels]
         @parameters << 'track-level-rels' if includes[:track_level_rels]
         @parameters << 'tags'         if includes[:tags]
+        @parameters << 'user_tags'    if includes[:user_tags]
+        @parameters << 'ratings'      if includes[:ratings]
+        @parameters << 'user_ratings' if includes[:user_ratings]
       end
     
     end
@@ -134,26 +180,35 @@ module MusicBrainz
       # [:artist]       Include track artist (boolean).
       # [:releases]     Includes releases the track appears on (boolean).
       # [:puids]        Include the track's PUIDs (boolean).
+      # [:isrcs]        Include the track's ISRCs (boolean).
       # [:artist_rels]  Include artist relationships (boolean).
       # [:release_rels] Include release relationships (boolean).
       # [:track_rels]   Include track relationships (boolean).
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
       # [:tags]         Include tags (boolean).
+      # [:user_tags]    Include user tags (boolean).
+      # [:ratings]      Include ratings (boolean).
+      # [:user_ratings] Include user ratings (boolean).
       def initialize(includes)
         Utils.check_options includes, 
-            :artist, :releases, :puids, :artist_rels, :release_rels, 
-            :track_rels, :label_rels, :url_rels, :tags
+            :artist, :releases, :puids, :isrcs, :artist_rels, :release_rels, 
+            :track_rels, :label_rels, :url_rels, :tags, :user_tags, :ratings,
+            :user_ratings
         @parameters = Array.new
         @parameters << 'artist'       if includes[:artist]
         @parameters << 'releases'     if includes[:releases]
         @parameters << 'puids'        if includes[:puids]
+        @parameters << 'isrcs'        if includes[:isrcs]
         @parameters << 'artist-rels'  if includes[:artist_rels]
         @parameters << 'release-rels' if includes[:release_rels]
         @parameters << 'track-rels'   if includes[:track_rels]
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
         @parameters << 'tags'         if includes[:tags]
+        @parameters << 'user_tags'    if includes[:user_tags]
+        @parameters << 'ratings'      if includes[:ratings]
+        @parameters << 'user_ratings' if includes[:user_ratings]
       end
     
     end
@@ -169,10 +224,13 @@ module MusicBrainz
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
       # [:tags]         Include tags (boolean).
+      # [:user_tags]    Include user tags (boolean).
+      # [:ratings]      Include ratings (boolean).
+      # [:user_ratings] Include user ratings (boolean).
       def initialize(includes)
         Utils.check_options includes, 
-            :aliases, :artist_rels, :release_rels, 
-            :track_rels, :label_rels, :url_rels, :tags
+            :aliases, :artist_rels, :release_rels, :track_rels, :label_rels,
+            :url_rels, :tags, :user_tags, :ratings, :user_ratings
         @parameters = Array.new
         @parameters << 'aliases'      if includes[:aliases]
         @parameters << 'artist-rels'  if includes[:artist_rels]
@@ -181,9 +239,12 @@ module MusicBrainz
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
         @parameters << 'tags'         if includes[:tags]
+        @parameters << 'user_tags'    if includes[:user_tags]
+        @parameters << 'ratings'      if includes[:ratings]
+        @parameters << 'user_ratings' if includes[:user_ratings]
       end
     
     end
     
   end
-end
+end

data/lib/rbrainz/webservice/mbxml.rb

@@ -1,4 +1,5 @@
-# $Id: mbxml.rb 218 2008-09-02 07:45:33Z phw $
+# -*- coding: utf-8 -*-
+# $Id: mbxml.rb 278 2009-06-07 21:30:51Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -22,7 +23,7 @@ module MusicBrainz
     class MBXML
     
       # Exception to be raised if a parse error occurs in MBXML.
-      class ParseError < Exception
+      class ParseError < ::Exception
       end
     
       # Create a new MBXML instance to parse a MusicBrainz metadata document.
@@ -47,10 +48,11 @@ module MusicBrainz
         # Already loaded artists, releases, tracks and labels will get cached
         # in these variables to link to them if they occure multiple times
         # inside the same document.
-        @artists  = Hash.new
-        @releases = Hash.new
-        @tracks   = Hash.new
-        @labels   = Hash.new
+        @artists        = Hash.new
+        @release_groups = Hash.new
+        @releases       = Hash.new
+        @tracks         = Hash.new
+        @labels         = Hash.new
       end
       
       # Read the XML string and create an entity model for the given entity
@@ -61,10 +63,10 @@ module MusicBrainz
         # Search for the first occuring node of type entity which is a child node
         # of the metadata element.
         entity = @document.elements["//[local-name()='metadata' and namespace-uri()='%s']/%s[1]" %
-                 [Model::NS_MMD_1, entity_type]]
+                 [Model::NS_MMD_1, Utils.entity_type_to_string(entity_type)]]
         
         unless entity.nil? or entity.is_a? REXML::Text
-          create_method = method('create_' + entity.name)
+          create_method = method('create_' + entity_type.to_s)
           create_method.call(entity) if create_method
         else
           return nil
@@ -83,7 +85,7 @@ module MusicBrainz
         # of the metadata element.
         entity_list = @document.elements[
           "//[local-name()='metadata' and namespace-uri()='%s']/[local-name()='%s-list' and namespace-uri()='%s'][1]" %
-            [Model::NS_MMD_1, entity_type, ns]]
+            [Model::NS_MMD_1, Utils.entity_type_to_string(entity_type), ns]]
         
         unless entity_list.nil? or entity_list.is_a? REXML::Text
           collection = Model::ScoredCollection.new(entity_list.attributes['count'],
@@ -121,7 +123,10 @@ module MusicBrainz
         end
         
         # Read all defined data fields
-        artist.id = node.attributes['id']
+        read_mbid(node, artist)
+        read_relationships(node, artist)
+        read_ratings(node, artist)
+        read_tag_list(node.elements['tag-list'], artist.tags)
         if node.attributes['type']
           artist.type = Utils.add_namespace(node.attributes['type'])
         end
@@ -142,20 +147,46 @@ module MusicBrainz
         read_release_list(node.elements['release-list'], artist.releases) {|release|
           release.artist = artist unless release.artist
         }
-        
-        # Read the relation list
-        if node.elements['relation-list']
-          node.elements.each('relation-list') {|relation_node|
-            read_relation_list(relation_node) {|relation|
-              artist.add_relation relation
-            }
-          }
+
+        # Read the release group list
+        read_release_group_list(node.elements['release-group-list'], artist.release_groups) {|release_group|
+          release_group.artist = artist unless release_group.artist
+        }
+
+        return artist
+      end
+      
+      # Iterate over a list of release groups and add them to the target collection.
+      # 
+      # The node must be of the type <em>release-group-list</em>.
+      def read_release_group_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'release-group', read_scores) do |a|
+          yield a if block_given?
+        end
+      end
+      
+      # Create a +ReleaseGroup+ object from the given release-group node.
+      def create_release_group(node)
+        if node.attributes['id'] and @release_groups[node.attributes['id']]
+          release_group = @release_groups[node.attributes['id']]
+        else
+          release_group = @factory.new_release_group
+          @release_groups[node.attributes['id']] = release_group
         end
         
-        # Read the tag list
-        read_tag_list(node.elements['tag-list'], artist.tags)
+        # Read all defined data fields
+        read_mbid(node, release_group)
+        release_group.title  = node.elements['title'].text if node.elements['title']
+        release_group.artist = create_artist(node.elements['artist']) if node.elements['artist']
         
-        return artist
+        read_types(node, release_group.types)
+        
+        # Read the release list
+        read_release_list(node.elements['release-list'], release_group.releases) {|release|
+          release.artist = release_group.artist unless release.artist
+        }
+        
+        return release_group
       end
       
       # Iterate over a list of releases and add them to the target collection.
@@ -179,15 +210,16 @@ module MusicBrainz
         end
         
         # Read all defined data fields
-        release.id     = node.attributes['id']
+        read_mbid(node, release)
+        read_relationships(node, release)
+        read_ratings(node, release)
+        read_tag_list(node.elements['tag-list'], release.tags)
         release.title  = node.elements['title'].text if node.elements['title']
         release.asin   = node.elements['asin'].text if node.elements['asin']
         release.artist = create_artist(node.elements['artist']) if node.elements['artist']
+        release.release_group = create_release_group(node.elements['release-group']) if node.elements['release-group']
         
-        # Read the types
-        node.attributes['type'].split(' ').each {|type|
-          release.types << Utils.add_namespace(type)
-        } if node.attributes['type']
+        read_types(node, release.types)
         
         # Read the text representation information.
         if text_representation = node.elements['text-representation']
@@ -207,18 +239,6 @@ module MusicBrainz
         # Read the disc list
         read_disc_list(node.elements['disc-list'], release.discs)
                 
-        # Read the relation list
-        if node.elements['relation-list']
-          node.elements.each('relation-list') {|relation_node|
-            read_relation_list(relation_node) {|relation|
-              release.add_relation relation
-            }
-          }
-        end
-        
-        # Read the tag list
-        read_tag_list(node.elements['tag-list'], release.tags)
-        
         return release
       end
       
@@ -241,7 +261,10 @@ module MusicBrainz
         end
         
         # Read all defined data fields
-        track.id       = node.attributes['id']
+        read_mbid(node, track)
+        read_relationships(node, track)
+        read_ratings(node, track)
+        read_tag_list(node.elements['tag-list'], track.tags)
         track.title    = node.elements['title'].text if node.elements['title']
         track.duration = node.elements['duration'].text.to_i if node.elements['duration']
         track.artist   = create_artist(node.elements['artist']) if node.elements['artist']
@@ -251,20 +274,9 @@ module MusicBrainz
           release.tracks << track
         }
         
-        # Read the PUID list
+        # Read the PUID and ISRC lists
         read_puid_list(node.elements['puid-list'], track.puids)
-        
-        # Read the relation list
-        if node.elements['relation-list']
-          node.elements.each('relation-list') {|relation_node|
-            read_relation_list(relation_node) {|relation|
-              track.add_relation relation
-            }
-          }
-        end
-        
-        # Read the tag list
-        read_tag_list(node.elements['tag-list'], track.tags)
+        read_isrc_list(node.elements['isrc-list'], track.isrcs)
         
         return track
       end
@@ -288,7 +300,10 @@ module MusicBrainz
         end
         
         # Read all defined data fields
-        label.id = node.attributes['id']
+        read_mbid(node, label)
+        read_relationships(node, label)
+        read_ratings(node, label)
+        read_tag_list(node.elements['tag-list'], label.tags)
         if node.attributes['type']
           label.type = Utils.add_namespace(node.attributes['type'])
         end
@@ -310,18 +325,6 @@ module MusicBrainz
         # Read the release list
         read_release_list(node.elements['release-list'], label.releases)
       
-        # Read the relation list
-        if node.elements['relation-list']
-          node.elements.each('relation-list') {|relation_node|
-            read_relation_list(relation_node) {|relation|
-              label.add_relation relation
-            }
-          }
-        end
-        
-        # Read the tag list
-        read_tag_list(node.elements['tag-list'], label.tags)
-        
         return label  
       end
       
@@ -400,6 +403,20 @@ module MusicBrainz
         return node.attributes['id']
       end
       
+      # Iterate over a list of ISRCs and add them to the target collection.
+      # 
+      # The node must be of the type <em>isrc-list</em>.
+      def read_isrc_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'isrc') do |a|
+          yield a if block_given?
+        end
+      end
+      
+      # Create an ISRC
+      def create_isrc(node)
+        return Model::ISRC.parse(node.attributes['id'])
+      end
+      
       # Iterate over a list of discs and add them to the target collection.
       # 
       # The node must be of the type <em>disc-list</em>.
@@ -510,6 +527,51 @@ module MusicBrainz
         return user_model
       end
       
+      # Read attributes common to all entities
+      def read_mbid(node, entity)
+        entity.id = node.attributes['id']
+      end
+      
+      # Read the relation list
+      def read_relationships(node, entity)
+        if node.elements['relation-list']
+          node.elements.each('relation-list') {|relation_node|
+            read_relation_list(relation_node) {|relation|
+              entity.add_relation relation
+            }
+          }
+        end
+      end
+      
+      # Read the type attribute
+      def read_types(node, target_collection)
+        node.attributes['type'].split(' ').each {|type|
+          target_collection << Utils.add_namespace(type)
+        } if node.attributes['type']
+      end
+      
+      # Read the ratings
+      def read_ratings(node, entity)
+        if node.elements['rating']
+          entity.rating = create_rating(node.elements['rating'])
+        end
+        
+        if node.elements['user-rating']
+          entity.user_rating = create_user_rating(node.elements['user-rating'])
+        end
+      end
+      
+      # Create a +Rating+ object from the given rating or user-rating node.
+      def create_rating(node)
+        rating = @factory.new_rating
+        rating.value = node.text.to_f
+        if node.attributes['votes-count']
+          rating.count = node.attributes['votes-count'].to_i
+        end
+        return rating
+      end
+      alias :create_user_rating create_rating
+      
       # Helper method that reads a list of a special node type.
       # There must be a method create_{child_name} which returns an
       # instance of the corresponding model.
@@ -518,7 +580,7 @@ module MusicBrainz
           target_collection.offset = list_node.attributes['offset'].to_i
           target_collection.count  = list_node.attributes['count'].to_i
           MBXML.each_element(list_node, child_name, ns) do |child|
-            model = method('create_' + child_name).call(child)
+            model = method('create_' + child_name.sub('-', '_')).call(child)
             if read_scores
               score = child.attributes['ext:score'].to_i
               entry = Model::ScoredCollection::Entry.new(model, score)
@@ -554,4 +616,4 @@ module MusicBrainz
     end
 
   end
-end
+end