rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/model/entity.rb

@@ -1,61 +1,83 @@
-# $Id: entity.rb 30 2007-05-29 02:12:33Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: entity.rb 145 2007-07-19 13:11:44Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
  
 require 'rbrainz/model/mbid'
 require 'rbrainz/model/relation'
+require 'rbrainz/model/collection'
+require 'rbrainz/model/tag'
+require 'set'
 
 module MusicBrainz
   module Model
 
-    # Superclass for all entities.
+    #
+    # A first-level MusicBrainz class.
+    # 
+    # All entities in MusicBrainz have unique IDs (which are MBID's representing
+    # absolute URIs) and may have any number of #relations to other entities.
+    # This class is abstract and should not be instantiated.
+    # 
+    # Relations are differentiated by their <i>target type</i>, that means,
+    # where they link to. MusicBrainz currently supports four target types
+    # (artists, releases, tracks, and URLs) each identified using a URI.
+    # To get all relations with a specific target type, you can use
+    # #relations and pass one of the following constants as the
+    # parameter:
+    #
+    # - Relation::TO_ARTIST
+    # - Relation::TO_RELEASE
+    # - Relation::TO_TRACK
+    # - Relation::TO_URL
+    #
+    # See:: Relation
+    #
     class Entity
-    
+      
+      # The entity type of this entity. Must be set by child classes correctly.
+      # 
+      # Use #entity_type to query the type.
+      ENTITY_TYPE = nil # :nodoc:
+      
+      # The MusicBrainz ID. A MBID containing an absolute URI.
       attr_reader :id
       
-      def initialize
+      # A Collection of Tag objects assigned to this entity.
+      attr_reader :tags
+      
+      # Create a new Entity. You can assign a MusicBrainz identifier to the
+      # created entity with the parameter _mbid_ (see id=).
+      def initialize(mbid=nil)
+        self.id = mbid
+        @tags = Collection.new
         @relations = {
-          Relation::TO_ARTIST  => Array.new,
-          Relation::TO_RELEASE => Array.new,
-          Relation::TO_TRACK   => Array.new,
-          Relation::TO_LABEL   => Array.new,
-          Relation::TO_URL     => Array.new,
+          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
       
       # Set the MBID.
       # 
-      # +mbid+ should be an instance of +MBID+ or a string
+      # _mbid_ should be an instance of MBID or a string
       # representing either a complete MBID URI or just the
       # UUID part of it. If it is a complete URI the entity
       # part of the URI must match the entity type returned
-      # by +entity_type+ or an +EntityTypeNotMatchingError+
+      # by +entity_type+ or an EntityTypeNotMatchingError
       # will be raised.
       # 
-      # Raises: +UnknownEntityError+, +InvalidUUIDError+,
-      # +EntityTypeNotMatchingError+
+      # Raises: UnknownEntityError, InvalidMBIDError,
+      # EntityTypeNotMatchingError
       def id=(mbid)
-        # If this already is an instance of MBID store it directly.
-        if mbid.is_a? MBID
-          @id = mbid
-        elsif mbid.nil?
-          @id = nil
+        if mbid
+          @id = MBID.parse(mbid, entity_type)
         else
-          # Try to create an MBID from URI
-          begin
-            @id = MBID.from_uri(mbid)
-          rescue InvalidMBIDError => e
-            # Try it again and use mbid as the UUID
-            @id = MBID.from_uuid(self.entity_type, mbid)
-          end
-        end
-        
-        # Check if the entity type of @id matches that of the current object.
-        unless @id.nil? or @id.entity == self.entity_type
-          exception = EntityTypeNotMatchingError.new(@id.entity.to_s)
           @id = nil
-          raise exception
         end
       end
       
@@ -64,7 +86,7 @@ module MusicBrainz
       # Depending on the class this is <tt>:artist</tt>, <tt>:release</tt>,
       # <tt>:track</tt> or <tt>:label</tt>.
       def self.entity_type
-        self.name.sub('MusicBrainz::Model::', '').downcase.to_sym
+        self::ENTITY_TYPE
       end
       
       # Returns the entity type of the instance.
@@ -75,36 +97,83 @@ module MusicBrainz
         self.class.entity_type
       end
       
-      # Add a relation to this entity.
+      #
+      # 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 the relations of this entity.
+      #
+      # Returns a list of relations.
+      #
+      # 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})
-        # Select all results depending on the requested target type
-        if options[:target_type]
-          result = @relations[options[:target_type]]
+        Utils.check_options options, 
+            :target_type, :relation_type, :required_attributes, :direction
+        target_type = options[:target_type]
+        relation_type = options[:relation_type]
+        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.each_value {|array| result += array}
+          result = @relations.values.flatten
         end
         
-        # Remove relations which don't meet all the criteria.
-        result.delete_if {|relation|
-          (options[:relation_type] and relation.type != options[:relation_type]) \
-          or (options[:required_attributes] and
-              (relation.attributes & options[:required_attributes]).sort \
-               != options[:required_attributes].sort) \
-          or (options[:direction] and relation.direction != options[:direction])
-        }
+        # Filter for direction
+        #
+        result = result.find_all { |r| r.direction == direction } if direction
         
-        return result
+        # Filter for relation type
+        #
+        result = result.find_all{ |r| r.type == relation_type } if relation_type
+        
+        # Filter for attributes
+        #
+        required = required_attributes.to_set
+        result.find_all do |r|
+             required.subset?( r.attributes.to_set )
+        end
       end
       
-      # Return all relation target types for which this entity
-      # has relations defined.
+      #
+      # 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|

data/lib/rbrainz/model/incomplete_date.rb

@@ -1,7 +1,9 @@
-# $Id: incomplete_date.rb 17 2007-05-23 16:51:11Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: incomplete_date.rb 145 2007-07-19 13:11:44Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'date'
 
@@ -12,28 +14,35 @@ module MusicBrainz
     # a date which can be defined without day or without
     # month and day. It can be written as <em>YYYY</em>,
     # <em>YYYY-MM</em> or <em>YYYY-MM-DD</em>.
-    class IncompleteDate
-    
+    class IncompleteDate < ::Range
       attr_reader :year, :month, :day
-      
-      # Include the Comparable module to make incomplete dates
-      # comparable and sortable.
-      include Comparable
-      
-      # TODO: Validation of the date
+
+      # Create a new IncompleteDate. The parameter _date_ must be a String in
+      # the form <em>YYYY</em>, <em>YYYY-MM</em> or <em>YYYY-MM-DD</em>.
       def initialize(date)
-        @year = nil
-        @month = nil
-        @day = nil
-        if date = date.to_s and date =~ /^\d{4}(-\d{2}){0,2}$/
-          @year = date[0..3].to_i if date.size >= 4
-          @month = date[5..6].to_i if date.size >= 7
-          @day = date[8..9].to_i if date.size == 10
-        elsif not date.empty?
-          raise ArgumentError
+        date = date.to_s if date.respond_to? :to_s
+        if date =~ /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/
+          @year = $1.to_i
+          @month = $2 ? $2.to_i : nil
+          @day = $3 ? $3.to_i : nil
+          if @month
+            if @day
+              start_d = Date.civil( @year, @month, @day)
+              end_d = start_d.succ
+            else
+              start_d = Date.civil( @year, @month)
+              end_d = Date.civil( @year, @month+1)
+            end
+          else
+            start_d = Date.civil( @year)
+            end_d = Date.civil( @year+1)
+          end
+          super( start_d, end_d, true)
+        else
+          raise ArgumentError, "Invalid incomplete date #{date}"
         end
       end
-      
+
       # Returns the incomplete date in its textual form
       # <em>YYYY</em>, <em>YYYY-MM</em> or <em>YYYY-MM-DD</em>.
       # 
@@ -45,31 +54,6 @@ module MusicBrainz
         }
         return date
       end
-      
-      # Compare this incomplete date with another incomplete date.
-      # If two incomplete dates are compared of which one date has
-      # less information than the other only the information
-      # present in both incomplete dates is used for comparison.
-      # That means that the dates 1980-08-22, 1980-08 and 1980 are
-      # all considered equal if compared to one another since it
-      # can't be decided if e.g. the date 1980-08 is earlier or later
-      # than 1980-08-22.
-      # 
-      # As a consequence of this a list of +IncompleteDate+ objects
-      # won't get sorted in the lexical order of their string
-      # representations. If you need a lexical order you must convert
-      # these objects to strings before ordering them.
-      def <=>(other)
-        result = self.year <=> other.year
-        if result == 0 and self.month and other.month
-          result = self.month <=> other.month
-          if result == 0 and self.day and other.day
-            result = self.day <=> other.day
-          end
-        end
-        return result
-      end
-     
     end
     
   end    

data/lib/rbrainz/model/individual.rb

@@ -0,0 +1,103 @@
+# $Id: individual.rb 145 2007-07-19 13:11:44Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
+
+require 'rbrainz/model/entity'
+require 'rbrainz/model/incomplete_date'
+
+module MusicBrainz
+  module Model
+
+    # Superclass for Artist and Label.
+    # 
+    # Aggregates the common attributes of artists and labels.
+    class Individual < Entity
+    
+      # The name of the artist or label.
+      attr_accessor :name
+      
+      # Name used for sorting (e.g. "White Stripes, The").
+      attr_accessor :sort_name
+      
+      # Field to distinguish between identically named artists or labels.
+      attr_accessor :disambiguation
+      
+      # The type of this artist or label. See the constants defined in Artist
+      # and Label for a list of possible types.
+      attr_accessor :type
+      
+      # Collection of alternate names, including possible typos.
+      attr_reader :aliases
+      
+      # The begin date is interpreted differently for bands, individual artists
+      # and labels. For bands and labels this is the founding date, for
+      # individual artists it is the date of birth.
+      # The begin date is an instance of IncompleteDate.
+      attr_reader :begin_date
+      
+      # The end date is interpreted differently for bands, individual artists
+      # and labels. For bands and labels this is the breakup date, for
+      # individual artists it is the date of death.
+      # The end date is an instance of IncompleteDate.
+      attr_reader :end_date
+      
+      # A Collection of releases of this artist or label.
+      #
+      # This may also include releases where this artist isn't the
+      # <i>main</i> artist but has just contributed one or more tracks
+      # (aka VA-Releases).
+      attr_reader :releases
+    
+      def initialize(id=nil, type=nil, name=nil, sort_name=nil)
+        super id
+        self.type       = type
+        self.name       = name
+        self.sort_name  = sort_name
+        @aliases        = Collection.new
+        @releases       = Collection.new
+      end
+                    
+      # Set the begin date of this individual to _date_.
+      # 
+      # Should be an IncompleteDate object or a date string, which will
+      # get converted into an IncompleteDate.
+      def begin_date=(date)
+        date = IncompleteDate.new date unless date.is_a? IncompleteDate
+        @begin_date = date
+      end
+      
+      # Set the end date of this individual to _date_.
+      # 
+      # Should be an IncompleteDate object or a date string, which will
+      # get converted into an IncompleteDate.
+      def end_date=(date)
+        date = IncompleteDate.new date unless date.is_a? IncompleteDate
+        @end_date = date
+      end
+      
+      # Returns a unique name for the individual (using disambiguation).
+      #
+      # The unique name ist the individual's name together with the
+      # disambiguation attribute in parenthesis if it exists. 
+      #
+      # Example:: 'Paradise Lost  (British metal / hard rock band)'.
+      def unique_name
+        unique_name = @name
+        unique_name += " (#{@disambiguation})" if @disambiguation
+        return unique_name
+      end
+      
+      # Returns the string representation for this individual.
+      # 
+      # Returns #unique_name converted into a string.
+      def to_s
+        unique_name.to_s
+      end
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/label.rb

@@ -1,54 +1,63 @@
-# $Id: label.rb 30 2007-05-29 02:12:33Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: label.rb 141 2007-07-17 14:21:12Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
 
-require 'rbrainz/model/entity'
-require 'rbrainz/model/incomplete_date'
+require 'rbrainz/model/individual'
 
 module MusicBrainz
   module Model
 
     # A label in the MusicBrainz DB.
     # 
-    # See http://musicbrainz.org/doc/Label.
-    class Label < Entity
+    # Labels in MusicBrainz can have a type. Currently, the following types
+    # are supported
+    # 
+    # - http://musicbrainz.org/ns/mmd-1.0#Unknown
+    # - http://musicbrainz.org/ns/mmd-1.0#Distributor
+    # - http://musicbrainz.org/ns/mmd-1.0#Holding
+    # - http://musicbrainz.org/ns/mmd-1.0#OriginalProduction
+    # - http://musicbrainz.org/ns/mmd-1.0#BootlegProduction
+    # - http://musicbrainz.org/ns/mmd-1.0#ReissueProduction
+    #
+    # See:: Individual
+    # See:: http://musicbrainz.org/doc/Label.
+    class Label < Individual
     
+      # Used if the type of the label is unknown.
+      TYPE_UNKNOWN             = NS_MMD_1 + 'Unknown'
+      # Companies mainly distributing other labels production,
+      # usually in a specific region of the world.
       TYPE_DISTRIBUTOR         = NS_MMD_1 + 'Distributor'
+      # Holdings, conglomerates or other financial entities whose main
+      # activity is not to produce records, but to manage a large set of
+      # recording labels owned by them.
       TYPE_HOLDING             = NS_MMD_1 + 'Holding'
+      # Recording labels producing entirely new releases.
       TYPE_ORIGINAL_PRODUCTION = NS_MMD_1 + 'OriginalProduction'
+      # Bootlegs companies (as in "not sanctioned by the rights owner(s)
+      # of the released work")
       TYPE_BOOTLEG_PRODUCTION  = NS_MMD_1 + 'BootlegProduction'
+      # Labels specializing in catalog reissues.
       TYPE_REISSUE_PRODUCTION  = NS_MMD_1 + 'ReissueProduction'
       
-      attr_accessor :name, :sort_name, :disambiguation,
-                    :code, :country, :type
-      
-      attr_reader :founding_date, :dissolving_date, :releases
-      
-      def initialize
-        super
-        @releases = Array.new
-      end
+      # See Entity::ENTITY_TYPE.
+      ENTITY_TYPE = :label # :nodoc:
       
-      # Set the founding date of the label.
+      # The code of the label.
       # 
-      # Should be an IncompleteDate object or
-      # a date string, which will get converted
-      # into an IncompleteDate.
-      def founding_date=(date)
-        date = IncompleteDate.new date unless date.is_a? IncompleteDate
-        @founding_date = date
-      end
+      # See:: http://musicbrainz.org/doc/LabelCode
+      attr_accessor :code
       
-      # Set the dissolving date of the label.
+      # The country in which the company was founded.
+      # A string containing a ISO 3166 country code like
+      # 'GB', 'US' or 'DE'.
       # 
-      # Should be an IncompleteDate object or
-      # a date string, which will get converted
-      # into an IncompleteDate.
-      def dissolving_date=(date)
-        date = IncompleteDate.new date unless date.is_a? IncompleteDate
-        @dissolving_date = date
-      end
+      # See:: Utils#get_country_name
+      # See:: http://musicbrainz.org/doc/LabelCountry
+      attr_accessor :country
       
     end