rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/model.rb

@@ -1,9 +1,22 @@
-# $Id: model.rb 13 2007-05-22 22:59:57Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: model.rb 143 2007-07-18 11:40:55Z 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 MusicBrainz # :nodoc:
+
+  # The MusicBrainz domain model.
+  # These classes are part of the MusicBrainz domain model. They may be used
+  # by other modules and don't contain any network or other I/O code. If you
+  # want to request data from the web service, please have a look at
+  # Webservice::Query.
+  # 
+  # The most important classes, usually acting as entry points, are
+  # Artist, Release, Track and Label.
+  # 
+  # See:: Webservice
   module Model
 
     # Namespace for all MusicBrainz metadata.
@@ -14,35 +27,14 @@ module MusicBrainz
     
     # 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
+   
+    require 'rbrainz/model/default_factory'
+    require 'rbrainz/utils'
+    require 'rbrainz/core_ext'
     
+    # The ID of the special 'Various Artists' artist. This is an instance of MBID.
+    # See:: http://musicbrainz.org/doc/VariousArtists
+    VARIOUS_ARTISTS_ID = MBID.new('89ad4ac3-39f7-470e-963a-56509c546377', Artist.entity_type)
+  
   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'
+end

data/lib/rbrainz/model/alias.rb

@@ -1,17 +1,41 @@
-# $Id: alias.rb 4 2007-05-21 02:04:26Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: alias.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
 
-    # An artist alias.
+    #
+    # Represents an artist or label alias.
+    #
+    # An alias (the <i>alias name</i>) is a different representation of an
+    # artist's or label's name. This may be a common misspelling or
+    # a transliteration (the <i>alias type</i>).
     # 
-    # See http://musicbrainz.org/doc/ArtistAlias.
+    # The <i>alias script</i> is interesting mostly for transliterations and
+    # indicates which script is used for the alias value. To represent the
+    # script, ISO-15924 script codes like 'Latn', 'Cyrl', or 'Hebr' are used.
+    #
+    # See:: http://musicbrainz.org/doc/ArtistAlias.
     class Alias
     
-      attr_accessor :name, :type, :script
+      # The alias name.
+      attr_accessor :name
+
+      # The alias type. An absolute URI or +nil+.
+      attr_accessor :type
+
+      # The alias script. See Utils#get_script_name.
+      attr_accessor :script
+      
+      def initialize(name=nil, type=nil, script=nil)
+        self.name   = name
+        self.type   = type
+        self.script = script
+      end
       
       def to_s
         return name.to_s

data/lib/rbrainz/model/artist.rb

@@ -1,52 +1,41 @@
-# $Id: artist.rb 30 2007-05-29 02:12:33Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: artist.rb 140 2007-07-17 13:27:54Z 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/individual'
 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
+    #
+    # Artists in MusicBrainz can have a type. Currently, this type can
+    # be either Person or Group for which the following URIs are assigned:
+    #
+    # - http://musicbrainz.org/ns/mmd-1.0#Person
+    # - http://musicbrainz.org/ns/mmd-1.0#Group
+    #
+    # Use the TYPE_PERSON and TYPE_GROUP constants for comparison.
+    #
+    # See:: Individual
+    # See:: http://musicbrainz.org/doc/Artist.
+    class Artist < Individual
     
-      TYPE_PERSON = NS_MMD_1 + 'Person'
-      TYPE_GROUP  = NS_MMD_1 + 'Group'
-      
-      attr_accessor :name, :sort_name, :disambiguation, :type
-                    
-      attr_reader :begin_date, :end_date, :aliases, :releases
-                    
-      def initialize
-        super
-        @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
+      # Used if the type of the artist is unknown.
+      TYPE_UNKNOWN = NS_MMD_1 + 'Unknown'
+      # This indicates an individual person.
+      TYPE_PERSON  = NS_MMD_1 + 'Person'
+      # This indicates a group of people that may or may
+      # not have a distinctive name.
+      TYPE_GROUP   = NS_MMD_1 + 'Group'
+    
+      # See Entity::ENTITY_TYPE.
+      ENTITY_TYPE = :artist # :nodoc:
       
     end
 

data/lib/rbrainz/model/collection.rb

@@ -0,0 +1,102 @@
+# $Id: collection.rb 130 2007-07-12 18:55:24Z nigel_graham $
+#
+# 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'
+
+module MusicBrainz
+  module Model
+
+    # A Collection is a list of models.
+    # 
+    # A collection object may only store an extract of the complete data
+    # available on the server. This is especially the case if the limit or
+    # offset filter was used in the query. The collection object makes the
+    # total number of elements on the server and the current offset available
+    # with the +count+ respective the +offset+ parameter.
+    class Collection
+    
+      include ::Enumerable
+      
+      # Returns the total number of elements for that collection on the server. 
+      attr_accessor :count
+      
+      # Returns the position at which this collection starts. Used for paging
+      # through more than one page of results.
+      attr_accessor :offset
+    
+      # Create a new collection object.
+      # 
+      # The count and offset parameters should be set according to the values
+      # returned by the server.
+      def initialize(count=0, offset=0, array=nil)
+        @count  = count.to_i
+        @offset = offset.to_i
+        if array
+          @entries = array.to_ary.dup
+        else
+          @entries = Array.new
+        end
+      end
+      
+      # Add a new element to this collection.
+      def <<(entry)
+        @entries << entry
+      end
+      
+      # Delete an element from the collection.
+      def delete(entry)
+        @entries.delete(entry)
+      end
+      
+      # Iterate over the contents of the collection.
+      def each
+        @entries.each {|e| yield e}
+      end
+      
+      # Access a random element in the collection by the element's index.
+      def [](index)
+        @entries[index]
+      end
+      
+      # Set a random element in the collection by the element's index.
+      def []=(index, entry)
+        @entries[index] = entry
+      end
+      
+      # Create a new collection containing the elements of both collections.
+      # Count and offset will be set to +nil+ in the new collection.
+      def +(other_collection)
+        new_collection = Collection.new
+        (self.to_a + other_collection.to_a).each do |entry|
+          new_collection << entry
+        end
+        return new_collection
+      end
+      
+      # The number of elements in the collection.
+      def size
+        @entries.size
+      end
+      
+      # Returns true, if the collection contains no elements.
+      def empty?
+        @entries.empty?
+      end
+      
+      # Convert the collection into an Array.
+      def to_a
+        @entries.dup
+      end
+      alias to_ary to_a
+      
+      def dup
+        Collection.new(self.count, self.offset, @entries)
+      end
+    end
+    
+  end
+end

data/lib/rbrainz/model/default_factory.rb

@@ -0,0 +1,78 @@
+# $Id: default_factory.rb 143 2007-07-18 11:40:55Z 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/artist'
+require 'rbrainz/model/label'
+require 'rbrainz/model/release'
+require 'rbrainz/model/track'
+require 'rbrainz/model/user'
+
+module MusicBrainz
+  module Model
+
+    # A factory to create model classes.
+    class DefaultFactory
+      
+      # Creates a new entity for a given entity type (<tt>:artist</tt>,
+      # <tt>:label</tt>, <tt>:release</tt> or <tt>:track</tt>).
+      def new_entity(entity_type)
+        case entity_type
+          when :artist
+            new_artist
+          when :label
+            new_label
+          when :release
+            new_release
+          when :track
+            new_track
+        end
+      end
+      
+      def new_artist
+        Artist.new
+      end
+      
+      def new_label
+        Label.new
+      end
+      
+      def new_release
+        Release.new
+      end
+      
+      def new_track
+        Track.new
+      end
+      
+      def new_alias
+        Alias.new
+      end
+      
+      def new_disc
+        Disc.new
+      end
+      
+      def new_relation
+        Relation.new
+      end
+      
+      def new_release_event
+        ReleaseEvent.new
+      end
+      
+      def new_tag
+        Tag.new
+      end
+      
+      def new_user
+        User.new
+      end
+      
+    end
+    
+  end
+end

data/lib/rbrainz/model/disc.rb

@@ -1,14 +1,16 @@
-# $Id: disc.rb 15 2007-05-23 14:31:36Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: disc.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.
 
 module MusicBrainz
   module Model
 
     # Represents an audio CD.
     # 
-    # A disc has a disc id, which is calculated from the
+    # 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.
     # 
@@ -17,12 +19,47 @@ module MusicBrainz
     # id. See Webservice::ReleaseFilter for details on
     # this.
     # 
-    # See http://wiki.musicbrainz.org/DiscID.
+    # If you need to calculate disc IDs you should install the mb-discid
+    # package. It allows you to calculate the disc ID for an audio CD.
     # 
-    # TODO: Currently the calculation of a disc ID is not supported.
+    # Example:
+    #  require 'rbrainz'
+    #  require 'mb-discid'
+    #  
+    #  discid = MusicBrainz::DiscID.new
+    #  discid.read
+    #  
+    #  disc = MusicBrainz::Model::Disc.new
+    #  disc.id = discid
+    # 
+    # See:: http://wiki.musicbrainz.org/DiscID for more information about
+    #       MusicBrainz disc IDs.
+    # See:: http://rbrainz.rubyforge.org/mbdiscid/api/
     class Disc
     
-      attr_accessor :id, :sectors
+      # Number of sectors on the disc
+      attr_accessor :sectors
+      
+      # The MusicBrainz DiscID. A string containing a 28-character DiscID.
+      attr_reader :id
+      
+      def initialize(id=nil)
+        self.id = id if id
+      end
+      
+      # Set the MusicBrainz disc ID for this disc.
+      # 
+      # The disc_id argument can be a string or a MusicBrainz::DiscID object.
+      def id=(disc_id)
+        @id = disc_id.to_s
+      end
+      
+      # Convert the Disc into a string.
+      # 
+      # Returns #id converted into a string.
+      def to_s
+        id.to_s
+      end
       
     end