rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/model/mbid.rb

@@ -1,66 +1,136 @@
-# $Id: mbid.rb 17 2007-05-23 16:51:11Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: mbid.rb 146 2007-07-19 16:33:38Z 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'
+require 'uri'
 
 module MusicBrainz
   module Model
 
+    # The format of a MusicBrainz identifier was wrong.
+    # 
+    # See:: MBID
+    class InvalidMBIDError < Exception
+    end
+    
+    # An unknown entity was encountered.
+    # 
+    # Valid entities are only <tt>:artist</tt>, <tt>:release</tt>,
+    # <tt>:track</tt> and <tt>:label</tt>.
+    # 
+    # See:: MBID
+    class UnknownEntityError < Exception
+    end
+    
+    # The entity type of a MBID didn't match the type of the entity.
+    # 
+    # See:: MBID
+    class EntityTypeNotMatchingError < Exception
+    end
+
     # 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. 
+    # 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
     # 
-    # Example: http://musicbrainz.org/artist/6a2ca1ac-408d-49b0-a7f6-cd608f2f684f.
+    # See:: http://musicbrainz.org/doc/MusicBrainzIdentifier
     class MBID
     
-      attr_reader :entity, :uuid
+      # The entity type (<tt>:artist</tt>, <tt>:label</tt>, <tt>:release</tt>,
+      # <tt>:track</tt>) this MBID references.
+      attr_reader :entity
       
-      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})\/?$/
+      # The UUID of the referenced entity.
+      attr_reader :uuid
       
-      # We make new private. Use from_uri or from_uuid instead.
-      private_class_method :new
+      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_URI = "http://musicbrainz\\.org/#{ENTITY_TYPE}/#{UUID}"
+      end
+      
+      # A regular expression describing the format of a UUID.
+      UUID_REGEXP = Regexp.new('^' + PATTERN::UUID + '$')
+      # A regular expression to test if a string is a valid entity type.
+      ENTITY_TYPE_REGEXP = Regexp.new('^' + PATTERN::ENTITY_TYPE + '$')
+      # A regular expression describing a MusicBrainz identifier URI.
+      ENTITY_URI_REGEXP = Regexp.new('^' + PATTERN::ENTITY_URI + '$')
       
-      # 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]
+      # The general format of a MusicBrainz identifier URI.
+      ENTITY_URI = 'http://musicbrainz.org/%s/%s'
+      
+      # Tries to convert _str_ into a MBID using its to_mbid method.
+      # 
+      # If _str_ does not respond to to_mbid a new MBID is created
+      # using the given parameters.
+      # 
+      # See:: new
+      # See:: String#to_mbid, URI::HTTP#to_mbid
+      def self.parse(str, entity_type=nil)
+        if str.respond_to? :to_mbid
+          str.to_mbid(entity_type)
         else
-          raise InvalidMBIDError.new(uri.inspect)
+          MBID.new(str, entity_type)
         end
-        from_uuid(entity, uuid)
       end
       
-      # Create a new MBID from the entity type and the UUID.
+      # Create a new MBID.
       # 
-      # 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>.
+      # _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.
       # 
-      # 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)
+      # Examples:
+      #  require 'rbrainz'
+      #  include MusicBrainz
+      #  id = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0')
+      #  id = Model::MBID.new('10bf95b6-30e3-44f1-817f-45762cdc0de0', :artist)
+      #  
+      # Raises:: UnknownEntityError, EntityTypeNotMatchingError,
+      #          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 )
+          raise UnknownEntityError, entity_type
         end
-        unless uuid.is_a? String and uuid =~ UUID_REGEXP
-          raise InvalidUUIDError.new(uuid.inspect)
+        entity_type = entity_type.to_sym if entity_type.respond_to? :to_sym
+        
+        if str =~ ENTITY_URI_REGEXP
+          @entity = $1.to_sym
+          @uuid = $2.downcase
+          unless entity_type.nil? || @entity == entity_type
+            raise EntityTypeNotMatchingError, "#{@entity}, #{entity_type}"
+          end
+        elsif str =~ UUID_REGEXP
+          unless entity_type
+            raise UnknownEntityError, "nil is not a valid entity type"
+          end
+          @entity = entity_type
+          @uuid = str.downcase
+        else
+          raise InvalidMBIDError, str
         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
+      # Returns self.
+      # 
+      # If _entity_type_ is given it must match the entity type of the MBID
+      # or an EntityTypeNotMatchingError will be raised.
+      # 
+      # Raises:: EntityTypeNotMatchingError
+      def to_mbid(entity_type=nil)
+        unless entity_type.nil? || @entity == entity_type
+          raise EntityTypeNotMatchingError, "#{self.entity}, #{entity_type}"
+        end
+        self
       end
       
       # Returns the string representation of the MBID (that is the complete URI).
@@ -73,10 +143,11 @@ module MusicBrainz
       # Two MBIDs are considered equal if both their entity
       # type and their UUID are equal.
       def ==(other)
+        other = other.to_mbid if other.respond_to? :to_mbid
         self.entity == other.entity and self.uuid == other.uuid
       end
       
     end
 
   end
-end
+end

data/lib/rbrainz/model/relation.rb

@@ -1,36 +1,93 @@
-# $Id: relation.rb 33 2007-05-29 14:48:47Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: relation.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.
  
 module MusicBrainz
   module Model
 
-    # Relationship class.
+    ##
+    # Represents a relation between two Entities.
+    #
+    # There may be an arbitrary number of relations between all first
+    # class objects in MusicBrainz. The Relation itself has multiple
+    # attributes, which may or may not be used for a given relation
+    # type.
+    #
+    # Note that a Relation object only contains the target but not
+    # the source end of the relation.
+    #
+    # TODO:: Add some examples.
+    #
     class Relation
     
+      # Relation reading direction is from target to source.
       DIR_BACKWARD = :backward
+      # Relation reading direction is from source to target.
       DIR_FORWARD  = :forward
+      # Relation reading direction doesn't matter.
       DIR_BOTH     = :both
       
+      # Identifies relations linking to an artist.
       TO_ARTIST  = NS_REL_1 + 'Artist'
+      # Identifies relations linking to a release.
       TO_RELEASE = NS_REL_1 + 'Release'
+      # Identifies relations linking to a track.
       TO_TRACK   = NS_REL_1 + 'Track'
+      # Identifies relations linking to a label.
       TO_LABEL   = NS_REL_1 + 'Label'
+      # Identifies relations linking to an URL.
       TO_URL     = NS_REL_1 + 'Url'
       
-      attr_accessor :type, :direction
+      # The relation's type.
+      attr_accessor :type
       
-      attr_reader :target, :begin_date, :end_date, :attributes
+      # The reading direction.
+      #
+      # The direction may be one of DIR_FORWARD, DIR_BACKWARD, or DIR_BOTH,
+      # depending on how the relation should be read. For example,
+      # if direction is DIR_FORWARD for a cover relation,
+      # it is read as "X is a cover of Y". Some relations are
+      # bidirectional, like marriages. In these cases, the direction
+      # is Relation.DIR_BOTH.
+      attr_accessor :direction
       
-      def initialize
-        @attributes = Array.new
-        @target = nil
+      # The relation's target object.
+      attr_reader :target
+      
+      # The list of attributes describing this relation.
+      #
+      # The attributes permitted depend on the relation type.
+      attr_reader :attributes
+      
+      # The begin date.
+      #
+      # The definition depends on the relation's type. It may for
+      # example be the day of a marriage or the year an artist
+      # joined a band. For other relation types this may be
+      # undefined.
+      attr_reader :begin_date
+      
+      # The end date.
+      #
+      # As with the begin date, the definition depends on the
+      # relation's type. Depending on the relation type, this may
+      # or may not be defined.
+      attr_reader :end_date
+      
+      def initialize(type=nil, target=nil, direction=nil)
+        @target        = nil
+        @attributes    = Array.new
+        self.type      = type
+        self.target    = target if target
+        self.direction = direction
       end
       
       # Set the target of this relation.
       # 
-      # The target can either be a object of the type Model::Entity
+      # The _target_ can either be a object of the type Model::Entity
       # or a URL.
       def target=(target)
         if target.is_a? Entity
@@ -40,7 +97,14 @@ module MusicBrainz
         end
       end
       
-      # Get the target type.
+      # The type of target this relation points to.
+      #
+      # For MusicBrainz data, the following target types are defined:
+      # - artists: #TO_ARTIST
+      # - labels: #TO_LABEL
+      # - releases: #TO_RELEASE
+      # - tracks: #TO_TRACK
+      # - urls: #TO_URL
       def target_type
         if @target.is_a? Model::Entity
           case @target.entity_type
@@ -58,7 +122,7 @@ module MusicBrainz
         end  
       end
       
-      # Set the begin date of this relation.
+      # Set the begin date of this relation to _date_.
       # 
       # Should be an IncompleteDate object or
       # a date string, which will get converted
@@ -68,7 +132,7 @@ module MusicBrainz
         @begin_date = date
       end
       
-      # Set the end date of this relation.
+      # Set the end date of this relation to _date_.
       # 
       # Should be an IncompleteDate object or
       # a date string, which will get converted

data/lib/rbrainz/model/release.rb

@@ -1,7 +1,9 @@
-# $Id: release.rb 30 2007-05-29 02:12:33Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: release.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/release_event'
@@ -10,39 +12,125 @@ require 'rbrainz/model/disc'
 module MusicBrainz
   module Model
 
+    #
     # A release in the MusicBrainz DB.
-    # 
-    # See http://musicbrainz.org/doc/Release.
+    #
+    # A release within MusicBrainz is an Entity which contains Track
+    # objects.  Releases may be of more than one type: There can be albums,
+    # singles, compilations, live recordings, official releases, bootlegs
+    # etc.
+    #
+    # See:: http://musicbrainz.org/doc/Release.
+    # Note:: The current MusicBrainz server implementation supports only a
+    #        limited set of types.
+    #
     class Release < Entity
     
-      TYPE_ALBUM          = NS_MMD_1 + 'Album' 
-      TYPE_AUDIOBOOK      = NS_MMD_1 + 'Audiobook' 
-      TYPE_BOOTLEG        = NS_MMD_1 + 'Bootleg' 
-      TYPE_COMPILATION    = NS_MMD_1 + 'Compilation' 
-      TYPE_EP             = NS_MMD_1 + 'EP' 
-      TYPE_INTERVIEW      = NS_MMD_1 + 'Interview' 
-      TYPE_LIVE           = NS_MMD_1 + 'Live' 
-      TYPE_NONE           = NS_MMD_1 + 'None' 
-      TYPE_OFFICIAL       = NS_MMD_1 + 'Official' 
-      TYPE_OTHER          = NS_MMD_1 + 'Other' 
-      TYPE_PROMOTION      = NS_MMD_1 + 'Promotion' 
-      TYPE_PSEUDO_RELEASE = NS_MMD_1 + 'Pseudo-Release' 
-      TYPE_REMIX          = NS_MMD_1 + 'Remix' 
-      TYPE_SINGLE         = NS_MMD_1 + 'Single' 
-      TYPE_SOUNDTRACK     = NS_MMD_1 + 'Soundtrack' 
-      TYPE_SPOKENWORD     = NS_MMD_1 + 'Spokenword' 
+      TYPE_ALBUM          = NS_MMD_1 + 'Album'
+      TYPE_AUDIOBOOK      = NS_MMD_1 + 'Audiobook'
+      TYPE_BOOTLEG        = NS_MMD_1 + 'Bootleg'
+      TYPE_COMPILATION    = NS_MMD_1 + 'Compilation'
+      TYPE_EP             = NS_MMD_1 + 'EP'
+      TYPE_INTERVIEW      = NS_MMD_1 + 'Interview'
+      TYPE_LIVE           = NS_MMD_1 + 'Live'
+      TYPE_NONE           = NS_MMD_1 + 'None'
+      TYPE_OFFICIAL       = NS_MMD_1 + 'Official'
+      TYPE_OTHER          = NS_MMD_1 + 'Other'
+      TYPE_PROMOTION      = NS_MMD_1 + 'Promotion'
+      TYPE_PSEUDO_RELEASE = NS_MMD_1 + 'Pseudo-Release'
+      TYPE_REMIX          = NS_MMD_1 + 'Remix'
+      TYPE_SINGLE         = NS_MMD_1 + 'Single'
+      TYPE_SOUNDTRACK     = NS_MMD_1 + 'Soundtrack'
+      TYPE_SPOKENWORD     = NS_MMD_1 + 'Spokenword'
       
-      attr_accessor :title, :asin, :artist,
-                    :text_language, :text_script
+      # See Entity::ENTITY_TYPE.
+      ENTITY_TYPE = :release # :nodoc:
+      
+      # The title of this release.
+      attr_accessor :title
+
+      # The amazon shop identifier.
+      #
+      # The ASIN is a 10-letter code (except for books) assigned
+      # by Amazon, which looks like 'B000002IT2' or 'B00006I4YD'.
+      attr_accessor :asin
+
+      # The main artist of this release.
+      attr_accessor :artist
+
+      # The language used in release and track titles.
+      # 
+      # To represent the language, the ISO-639-2/T standard is used,
+      # which provides three-letter terminological language codes like
+      # 'ENG', 'DEU', 'JPN', 'KOR', 'ZHO' or 'YID'.
+      #
+      # Note that this refers to release and track <i>titles</i>, not
+      # lyrics.
+      # 
+      # See:: Utils#get_language_name
+      attr_accessor :text_language
+
+      # The script used in release and track titles.
+      #
+      # To represent the script, ISO-15924 script codes are used.
+      # Valid codes are, among others: 'Latn', 'Cyrl', 'Hans', 'Hebr'
+      #
+      # Note that this refers to release and track <i>titles</i>, not
+      # lyrics.
+      # 
+      # See:: Utils#get_script_name
+      attr_accessor :text_script
                     
-      attr_reader :tracks, :release_events, :discs, :types
+      # The list of tracks.
+      attr_reader :tracks
+
+      # The list of release events.
+      #
+      # A Release may contain a list of so-called release events,
+      # each represented using a ReleaseEvent object. Release
+      # events specify where and when this release was, well, released.
+      attr_reader :release_events
+
+      # The list of associated discs.
+      #
+      # Note that under rare circumstances (identical TOCs), a
+      # Disc could be associated with more than one release.
+      attr_reader :discs
+
+      # The list of types for this release.
+      #
+      # To test for release types, you can use the constants
+      # TYPE_ALBUM, TYPE_SINGLE, etc.
+      attr_reader :types
       
-      def initialize
-        super
-        @tracks = Array.new
-        @release_events = Array.new
-        @discs = Array.new
-        @types = Array.new
+      def initialize(id=nil, title=nil)
+        super id
+        self.title      = title
+        @tracks         = Collection.new
+        @release_events = Collection.new
+        @discs          = Collection.new
+        @types          = Array.new
+      end
+
+      #
+      # Checks if this is a single artist's release.
+      #
+      # Returns +true+ if the release's main artist (#artist) is
+      # also the main artist for all of the tracks. This is checked by
+      # comparing the artist IDs.
+      #
+      # Note that the release's artist has to be set (see #artist=)
+      # for this. The track artists may be unset.
+      def single_artist_release?
+          raise 'Release Artist may not be None!' unless artist
+          tracks.all {|track| !track.artist || track.artist.id == artist.id }
+      end
+    
+      # Returns the string representation for this release.
+      # 
+      # Returns #title converted into a string.
+      def to_s
+        title.to_s
       end
       
     end