rbrainz 0.4.2 → 0.5.0

data/lib/rbrainz/model/incomplete_date.rb

@@ -1,4 +1,5 @@
-# $Id: incomplete_date.rb 154 2007-07-24 12:39:02Z phw $
+# -*- coding: utf-8 -*-
+# $Id: incomplete_date.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -93,4 +94,4 @@ module MusicBrainz
     end
     
   end    
-end
+end

data/lib/rbrainz/model/individual.rb

@@ -1,4 +1,5 @@
-# $Id: individual.rb 151 2007-07-24 08:36:27Z phw $
+# -*- coding: utf-8 -*-
+# $Id: individual.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -6,7 +7,11 @@
 #             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'rbrainz/model/entity'
+require 'rbrainz/model/alias'
 require 'rbrainz/model/incomplete_date'
+require 'rbrainz/model/rateable'
+require 'rbrainz/model/relateable'
+require 'rbrainz/model/taggable'
 
 module MusicBrainz
   module Model
@@ -16,6 +21,10 @@ module MusicBrainz
     # Aggregates the common attributes of artists and labels.
     class Individual < Entity
     
+      include Rateable
+      include Relateable
+      include Taggable
+      
       # The name of the artist or label.
       attr_accessor :name
       
@@ -100,4 +109,4 @@ module MusicBrainz
     end
 
   end
-end
+end

data/lib/rbrainz/model/isrc.rb

@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+# $Id: isrc.rb 263 2009-05-24 22:15:12Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2009, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
+
+module MusicBrainz
+  module Model
+
+    # The format of a ISRC was wrong.
+    # 
+    # See:: ISRC
+    class InvalidISRCError < Exception
+    end
+
+    #
+    # Represents an International Standard Recording Code (ISRC).
+    # 
+    # The International Standard Recording Code or short ISRC is an identification
+    # system for audio and music video recordings. It is standarized by the IFPI
+    # in ISO 3901:2001 and used by IFPI members to assign unique identifiers to
+    # every distinct recording they release. 
+    # 
+    # See:: http://wiki.musicbrainz.org/ISRC
+    class ISRC
+      
+      ISRC_PATTERN = /^([0-9A-Z]{2})-?([0-9A-Z]{3})-?([0-9A-Z]{2})-?([0-9A-Z]{5})$/i
+      
+      # 2-letter country code according to the ISO 3166-1-Alpha-2 standard.
+      attr_reader :country
+      
+      # The Registrant Code identifies the entity assigning the Designation Code in an ISRC.
+      attr_reader :registrant
+      
+      # Year of reference (2 digits).
+      attr_reader :year
+      
+      # Designation code (5 digits)
+      attr_reader :designation
+      
+      # Tries to convert _obj_ into an ISRC object.
+      # 
+      # If _obj_ is an ISRC it is returned. Otherwise a new ISRC object
+      # is created by converting _obj_ into a string and parsing it.
+      # 
+      # Raises:: InvalidISRCError
+      def self.parse(obj)
+        if obj.is_a? ISRC
+          return obj
+        else
+          return ISRC.new(obj)
+        end
+      end
+      
+      # Create a new ISRC object from the given string.
+      #
+      # Raises:: InvalidISRCError
+      def initialize(isrc)
+        unless isrc.to_s =~ ISRC_PATTERN
+          raise InvalidISRCError
+        end
+        @country = $1.upcase
+        @registrant = $2.upcase
+        @year = $3.upcase
+        @designation = $4.upcase
+      end   
+
+      # Convert this ISRC into a String.
+      # Will return the readable version of the ISRC with dashes added,
+      # e.g. FR-Z03-91-01231
+      def to_s
+        return [@country, @registrant, @year, @designation].join('-')
+      end
+      
+      # Convert this ISRC into a String.
+      # Will return the 12 character representation of the ISRC without dashes,
+      # e.g. FRZ039101231
+      def to_str
+        return [@country, @registrant, @year, @designation].join
+      end
+      
+      # Compares this ISRC with another one.
+      # 
+      # If _other_ is not of the type ISRC an attempt is made to convert it into one.
+      # This may cause an InvalidISRCError to be raised. Please note that
+      # comparing an ISRC with a different type of object is usually
+      # not commutative.
+      #
+      # Raises:: InvalidISRCError
+      def eql?(other)
+        self.to_s == ISRC.parse(other).to_s
+      end
+      alias :== eql?
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/label.rb

@@ -1,4 +1,5 @@
-# $Id: label.rb 141 2007-07-17 14:21:12Z phw $
+# -*- coding: utf-8 -*-
+# $Id: label.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -26,6 +27,8 @@ module MusicBrainz
     # See:: http://musicbrainz.org/doc/Label.
     class Label < Individual
     
+      include Taggable
+      
       # Used if the type of the label is unknown.
       TYPE_UNKNOWN             = NS_MMD_1 + 'Unknown'
       # Companies mainly distributing other labels production,
@@ -62,4 +65,4 @@ module MusicBrainz
     end
     
   end
-end
+end

data/lib/rbrainz/model/mbid.rb

@@ -1,4 +1,5 @@
-# $Id: mbid.rb 146 2007-07-19 16:33:38Z phw $
+# -*- coding: utf-8 -*-
+# $Id: mbid.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -44,8 +45,8 @@ module MusicBrainz
     # See:: http://musicbrainz.org/doc/MusicBrainzIdentifier
     class MBID
     
-      # The entity type (<tt>:artist</tt>, <tt>:label</tt>, <tt>:release</tt>,
-      # <tt>:track</tt>) this MBID references.
+      # The entity type (<tt>:artist</tt>, <tt>:label</tt>, <tt>:release_group</tt>,
+      # <tt>:release</tt>, <tt>:track</tt>) this MBID references.
       attr_reader :entity
       
       # The UUID of the referenced entity.
@@ -53,7 +54,7 @@ module MusicBrainz
       
       module PATTERN #:nodoc:
         UUID = '([a-fA-F0-9]{8}(:?-[a-fA-F0-9]{4}){3}-[a-fA-F0-9]{12})'
-        ENTITY_TYPE = '(artist|release|track|label)'
+        ENTITY_TYPE = '(artist|release-group|release|track|label)'
         ENTITY_URI = "http://musicbrainz\\.org/#{ENTITY_TYPE}/#{UUID}"
       end
       
@@ -74,6 +75,9 @@ module MusicBrainz
       # 
       # See:: new
       # See:: String#to_mbid, URI::HTTP#to_mbid
+      # 
+      # Raises:: UnknownEntityError, EntityTypeNotMatchingError,
+      #          InvalidMBIDError
       def self.parse(str, entity_type=nil)
         if str.respond_to? :to_mbid
           str.to_mbid(entity_type)
@@ -86,7 +90,8 @@ module MusicBrainz
       # 
       # _str_ can be either a complete identifier or just the UUID part of it.
       # In the latter case the entity type (<tt>:artist</tt>, <tt>:label</tt>,
-      # <tt>:release</tt> or <tt>:track</tt>) has to be specified as well.
+      # <tt>:release_group</tt>, <tt>:release</tt> or <tt>:track</tt>) has to be
+      # specified as well.
       # 
       # Examples:
       #  require 'rbrainz'
@@ -98,13 +103,13 @@ module MusicBrainz
       #          InvalidMBIDError
       def initialize(str, entity_type=nil)
         str = str.to_s if str.respond_to? :to_s
-        if entity_type && !(entity_type.to_s =~ ENTITY_TYPE_REGEXP )
+        unless is_valid_entity_type_or_nil(entity_type)
           raise UnknownEntityError, entity_type
         end
-        entity_type = entity_type.to_sym if entity_type.respond_to? :to_sym
+        entity_type = entity_type_to_symbol(entity_type)
         
         if str =~ ENTITY_URI_REGEXP
-          @entity = $1.to_sym
+          @entity = entity_type_to_symbol($1)
           @uuid = $2.downcase
           unless entity_type.nil? || @entity == entity_type
             raise EntityTypeNotMatchingError, "#{@entity}, #{entity_type}"
@@ -135,7 +140,7 @@ module MusicBrainz
       
       # Returns the string representation of the MBID (that is the complete URI).
       def to_s
-        ENTITY_URI % [entity.to_s, uuid]
+        ENTITY_URI % [Utils.entity_type_to_string(entity), uuid]
       end
       
       # Compares this MBID with another one.
@@ -147,6 +152,20 @@ module MusicBrainz
         self.entity == other.entity and self.uuid == other.uuid
       end
       
+      private
+      
+      def is_valid_entity_type_or_nil(entity_type)
+        return entity_type.nil? || Utils.entity_type_to_string(entity_type) =~ ENTITY_TYPE_REGEXP
+      end
+      
+      def entity_type_to_symbol(entity_type)
+        unless entity_type.respond_to? :to_sym
+          return entity_type
+        end
+        entity_type = entity_type.to_sym
+        return entity_type.to_s.sub('-', '_').to_sym
+      end
+      
     end
 
   end

data/lib/rbrainz/model/rateable.rb

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# $Id: rateable.rb 266 2009-05-24 22:15:22Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2009, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
+
+require 'rbrainz/model/rating'
+
+module MusicBrainz
+  module Model
+
+    # Mixin module to add rating capabilities to Entity classes.
+    #
+    # see:: Rating
+    module Rateable
+      
+      # The community Rating from MusicBrainz.
+      def rating
+        @rating ||= Rating.new
+      end
+      attr_writer :rating
+      
+      # The user Rating from MusicBrainz.
+      def user_rating
+        @user_rating ||= Rating.new
+      end
+      attr_writer :user_rating
+      
+    end
+      
+  end
+end

data/lib/rbrainz/model/rating.rb

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+# $Id: rating.rb 273 2009-05-24 22:29:04Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2008 Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
+
+module MusicBrainz
+  module Model
+
+    #
+    # Represents a rating of an entity.
+    # 
+    # MusicBrainz allows it's users to rate artists, labels, releases and tracks.
+    # Each user rating will be a Float between 1 and 5 or nil, where nil means no rating.
+    # The system will aggregate user ratings to compute the average community rating. 
+    # 
+    # See:: http://wiki.musicbrainz.org/RatingSystem
+    class Rating
+      # The rating (an Float between 1 and 5).
+      # If :count is greater than 1 this will be the average rating. 
+      attr_accessor :value
+
+      # The rating count indicating how often entity was rated.
+      attr_accessor :count
+      
+      def initialize(value=nil, count=nil)
+        @value = value.nil? ? nil : value.to_f
+        @count = count.nil? ? nil : count.to_i
+      end
+      
+      # Convert this rating into a String. Will return rating.
+      def to_s
+        return value.to_s
+      end
+      
+      # Convert this rating into an Integer. Will return rating.
+      def to_i
+        return value.to_i
+      end
+      
+      # Convert this rating into a Float. Will return rating.
+      def to_f
+        return value.to_f
+      end
+      
+      # Tests if this rating is empty
+      def empty?
+        return value.nil?
+      end
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/relateable.rb

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+# $Id: relateable.rb 266 2009-05-24 22:15:22Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2009, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
+
+require 'rbrainz/model/relation'
+require 'rbrainz/model/collection'
+
+module MusicBrainz
+  module Model
+
+    # Mixin module to add add advanced relationship capabilities to Entity classes.
+    #
+    # see:: Relation
+    module Relateable
+      
+      #
+      # Adds a Relation.
+      #
+      # This method adds _relation_ to the list of relations. The
+      # given relation has to be initialized, at least the target
+      # type has to be set.
+      #
+      def add_relation(relation)
+        relations[relation.target_type] << relation
+      end
+      
+      #
+      # Returns a list of Relation objects.
+      #
+      # If _target_type_ is given, only relations of that target
+      # type are returned. For MusicBrainz, the following target
+      # types are defined:
+      # - Relation::TO_ARTIST
+      # - Relation::TO_RELEASE
+      # - Relation::TO_TRACK
+      # - Relation::TO_URL
+      # 
+      # If _target_type_ is Relation::TO_ARTIST, for example,
+      # this method returns all relations between this Entity and
+      # artists.
+      #
+      # You may use the _relation_type_ parameter to further restrict
+      # the selection. If it is set, only relations with the given
+      # relation type are returned. The _required_attributes_ sequence
+      # lists attributes that have to be part of all returned relations.
+      #
+      # If _direction_ is set, only relations with the given reading
+      # direction are returned. You can use the Relation::DIR_FORWARD,
+      # Relation::DIR_BACKWARD, and Relation::DIR_BOTH constants
+      # for this.
+      #
+      def get_relations(options = {:target_type => nil, :relation_type => nil,
+                                   :required_attributes => [], :direction => nil})
+        Utils.check_options options, 
+            :target_type, :relation_type, :required_attributes, :direction
+        
+        target_type   = Utils.add_namespace(options[:target_type], NS_REL_1)
+        relation_type = Utils.add_namespace(options[:relation_type], NS_REL_1)
+        required_attributes = 
+          options[:required_attributes] ? options[:required_attributes] : []
+        direction = options[:direction]
+        
+        # Select all relevant relations depending on the requested target type
+        if target_type
+          result = relations[target_type].to_a
+        else
+          result = relations.values.flatten
+        end
+        
+        # Filter for direction
+        result = result.find_all { |r| r.direction == direction } if direction
+        
+        # Filter for relation type
+        result = result.find_all{ |r| r.type == relation_type } if relation_type
+        
+        # Filter for attributes
+        required = required_attributes.map{|a| Utils.add_namespace(a, NS_REL_1)}.to_set
+        result.find_all do |r|
+             required.subset?( r.attributes.to_set )
+        end
+      end
+      
+      #
+      # Returns a list of target types available for this entity.
+      # 
+      # Use this to find out to which types of targets this entity
+      # has relations. If the entity only has relations to tracks and
+      # artists, for example, then a list containg the strings
+      # Relation::TO_TRACK and Relation::TO_ARTIST is returned.
+      #
+      def relation_target_types
+        result = []
+        relations.each_pair {|type, relations|
+          result << type unless relations.empty?
+        }
+        return result
+      end
+      
+      private #-----------------------------------------------------------------
+      
+      def relations
+        @relations ||= {
+          Relation::TO_ARTIST  => Collection.new,
+          Relation::TO_RELEASE => Collection.new,
+          Relation::TO_TRACK   => Collection.new,
+          Relation::TO_LABEL   => Collection.new,
+          Relation::TO_URL     => Collection.new,
+        }
+      end
+      
+    end
+      
+  end
+end