rbrainz 0.1.0

data/lib/rbrainz/model.rb

@@ -0,0 +1,48 @@
+# $Id: model.rb 13 2007-05-22 22:59:57Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+module MusicBrainz
+  module Model
+
+    # Namespace for all MusicBrainz metadata.
+    NS_MMD_1 = 'http://musicbrainz.org/ns/mmd-1.0#'
+    
+    # Namespace for MusicBrainz relations.
+    NS_REL_1 = 'http://musicbrainz.org/ns/rel-1.0#'
+    
+    # Namespace for MusicBrainz extensions.
+    NS_EXT_1 = 'http://musicbrainz.org/ns/ext-1.0#'
+
+    # Defines the format of an UUID (Universally Unique Identifier)
+    UUID_REGEXP = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/
+    
+    # The format of a MusicBrainz identifier was wrong.
+    class InvalidMBIDError < Exception
+    end
+    
+    # The format of a MusicBrainz UUID was wrong.
+    class InvalidUUIDError < Exception
+    end
+    
+    # An unknown entity was encountered.
+    # Valid entities are only :artist, :release, :track and :label.
+    class UnknownEntityError < Exception
+    end
+    
+    # The entity type of a MBID didn't match the type of the entity.
+    class EntityTypeNotMatchingError < Exception
+    end
+    
+  end 
+end
+
+require 'rbrainz/data/countrynames'
+require 'rbrainz/data/languagenames'
+require 'rbrainz/data/scriptnames'
+
+require 'rbrainz/model/artist'
+require 'rbrainz/model/label'
+require 'rbrainz/model/release'
+require 'rbrainz/model/track'

data/lib/rbrainz/model/alias.rb

@@ -0,0 +1,23 @@
+# $Id: alias.rb 4 2007-05-21 02:04:26Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+module MusicBrainz
+  module Model
+
+    # An artist alias.
+    # 
+    # See http://musicbrainz.org/doc/ArtistAlias.
+    class Alias
+    
+      attr_accessor :name, :type, :script
+      
+      def to_s
+        return name.to_s
+      end
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/artist.rb

@@ -0,0 +1,54 @@
+# $Id: artist.rb 13 2007-05-22 22:59:57Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+require 'rbrainz/model/entity'
+require 'rbrainz/model/alias'
+require 'rbrainz/model/incomplete_date'
+
+module MusicBrainz
+  module Model
+
+    # An artist in the MusicBrainz DB.
+    # 
+    # See http://musicbrainz.org/doc/Artist.
+    class Artist < Entity
+    
+      TYPE_PERSON = NS_MMD_1 + 'Person'
+      TYPE_GROUP  = NS_MMD_1 + 'Group'
+      
+      attr_accessor :name, :sort_name, :disambiguation,
+                    :type, :aliases, :releases
+                    
+      attr_reader :begin_date, :end_date
+                    
+      def initialize
+        @aliases = Array.new
+        @releases = Array.new
+      end
+      
+      # Set the begin date of this artist.
+      # 
+      # 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 artist.
+      # 
+      # 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
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/disc.rb

@@ -0,0 +1,30 @@
+# $Id: disc.rb 15 2007-05-23 14:31:36Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+module MusicBrainz
+  module Model
+
+    # Represents an audio CD.
+    # 
+    # A disc has a disc id, which is calculated from the
+    # CD's table of contents (TOC). It also can include
+    # the numbers of sectors on the CD.
+    # 
+    # The disc id is mainly used to lookup a release in
+    # the MusicBrainz database the matches a given disc
+    # id. See Webservice::ReleaseFilter for details on
+    # this.
+    # 
+    # See http://wiki.musicbrainz.org/DiscID.
+    # 
+    # TODO: Currently the calculation of a disc ID is not supported.
+    class Disc
+    
+      attr_accessor :id, :sectors
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/entity.rb

@@ -0,0 +1,72 @@
+# $Id: entity.rb 15 2007-05-23 14:31:36Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+ 
+require 'rbrainz/model/mbid'
+
+module MusicBrainz
+  module Model
+
+    # Superclass for all entities.
+    # 
+    # TODO: implement relations.
+    class Entity
+    
+      attr_reader :id
+      
+      # Set the MBID.
+      # 
+      # +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+
+      # will be raised.
+      # 
+      # Raises: +UnknownEntityError+, +InvalidUUIDError+,
+      # +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
+        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
+      
+      # Returns the entity type of the entity class.
+      # 
+      # 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
+      end
+      
+      # Returns the entity type of the instance.
+      # 
+      # Depending on the class this is <tt>:artist</tt>, <tt>:release</tt>,
+      # <tt>:track</tt> or <tt>:label</tt>.
+      def entity_type
+        self.class.entity_type
+      end
+      
+    end
+    
+  end
+end

data/lib/rbrainz/model/incomplete_date.rb

@@ -0,0 +1,76 @@
+# $Id: incomplete_date.rb 17 2007-05-23 16:51:11Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+require 'date'
+
+module MusicBrainz
+  module Model
+
+    # Represents an incomplete date. An incomplete date is
+    # 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
+    
+      attr_reader :year, :month, :day
+      
+      # Include the Comparable module to make incomplete dates
+      # comparable and sortable.
+      include Comparable
+      
+      # TODO: Validation of the date
+      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
+        end
+      end
+      
+      # Returns the incomplete date in its textual form
+      # <em>YYYY</em>, <em>YYYY-MM</em> or <em>YYYY-MM-DD</em>.
+      # 
+      # TODO: Allow formatting options similiar to Date.to_s
+      def to_s
+        date = @year.to_s
+        [@month, @day].each {|value|
+          date += '-%02d' % value if value
+        }
+        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    
+end

data/lib/rbrainz/model/label.rb

@@ -0,0 +1,55 @@
+# $Id: label.rb 13 2007-05-22 22:59:57Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+require 'rbrainz/model/entity'
+require 'rbrainz/model/incomplete_date'
+
+module MusicBrainz
+  module Model
+
+    # A label in the MusicBrainz DB.
+    # 
+    # See http://musicbrainz.org/doc/Label.
+    class Label < Entity
+    
+      TYPE_DISTRIBUTOR         = NS_MMD_1 + 'Distributor'
+      TYPE_HOLDING             = NS_MMD_1 + 'Holding'
+      TYPE_ORIGINAL_PRODUCTION = NS_MMD_1 + 'OriginalProduction'
+      TYPE_BOOTLEG_PRODUCTION  = NS_MMD_1 + 'BootlegProduction'
+      TYPE_REISSUE_PRODUCTION  = NS_MMD_1 + 'ReissueProduction'
+      
+      attr_accessor :name, :sort_name, :disambiguation,
+                    :code, :country, :type, :releases
+      
+      attr_reader :founding_date, :dissolving_date
+      
+      def initialize
+        @releases = Array.new
+      end
+      
+      # Set the founding date 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
+      
+      # Set the dissolving date of the label.
+      # 
+      # 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
+      
+    end
+    
+  end
+end

data/lib/rbrainz/model/mbid.rb

@@ -0,0 +1,82 @@
+# $Id: mbid.rb 17 2007-05-23 16:51:11Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+
+require 'rbrainz/model'
+
+module MusicBrainz
+  module Model
+
+    # Represents a MusicBrainz identifier.
+    # 
+    # A MusicBrainz identifier is an URI identifying a resource like an artist or a track.
+    # It consists of an URI prefix, the entity type it refers to and an UUID that
+    # identifies the referenced entity. 
+    # 
+    # See http://musicbrainz.org/doc/MusicBrainzIdentifier.
+    # 
+    # Example: http://musicbrainz.org/artist/6a2ca1ac-408d-49b0-a7f6-cd608f2f684f.
+    class MBID
+    
+      attr_reader :entity, :uuid
+      
+      ENTITY_URI = 'http://musicbrainz.org/%s/%s'
+      ENTITY_URI_REGEXP = /^http:\/\/musicbrainz.org\/(artist|release|track|label)\/([a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12})\/?$/
+      
+      # We make new private. Use from_uri or from_uuid instead.
+      private_class_method :new
+      
+      # Creates a new MBID from a MBID URI, e.g.
+      # http://musicbrainz.org/artist/6a2ca1ac-408d-49b0-a7f6-cd608f2f684f
+      def self.from_uri(uri)
+        if match = ENTITY_URI_REGEXP.match(uri)
+          entity = match[1]
+          uuid = match[2]
+        else
+          raise InvalidMBIDError.new(uri.inspect)
+        end
+        from_uuid(entity, uuid)
+      end
+      
+      # Create a new MBID from the entity type and the UUID.
+      # 
+      # The entity type must be <tt>:artist</tt>, <tt>:release</tt>,
+      # <tt>:track</tt> or <tt>:label</tt>. The UUID is the last
+      # part of the URI, e.g. <tt>6a2ca1ac-408d-49b0-a7f6-cd608f2f684f</tt>.
+      # 
+      # Raises: +UnknownEntityError+, +InvalidUUIDError+
+      def self.from_uuid(entity, uuid)
+        if entity.nil? or entity == '' or
+           not [:artist, :release, :track, :label].include? entity.to_sym
+          raise UnknownEntityError.new(entity.to_s)
+        end
+        unless uuid.is_a? String and uuid =~ UUID_REGEXP
+          raise InvalidUUIDError.new(uuid.inspect)
+        end
+        new(entity.to_sym, uuid)
+      end
+      
+      # Initialize the UUID given the entity type and an UUID.
+      def initialize(entity, uuid) # :notnew:
+        @entity = entity
+        @uuid = uuid
+      end
+      
+      # Returns the string representation of the MBID (that is the complete URI).
+      def to_s
+        ENTITY_URI % [entity.to_s, uuid]
+      end
+      
+      # Compares this MBID with another one.
+      # 
+      # Two MBIDs are considered equal if both their entity
+      # type and their UUID are equal.
+      def ==(other)
+        self.entity == other.entity and self.uuid == other.uuid
+      end
+      
+    end
+
+  end
+end