rbrainz 0.4.2 → 0.5.0

data/lib/rbrainz/model/relation.rb

@@ -1,4 +1,5 @@
-# $Id: relation.rb 173 2007-08-24 15:11:11Z phw $
+# -*- coding: utf-8 -*-
+# $Id: relation.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer

data/lib/rbrainz/model/release.rb

@@ -1,4 +1,5 @@
-# $Id: release.rb 190 2007-12-04 12:51:17Z phw $
+# -*- coding: utf-8 -*-
+# $Id: release.rb 278 2009-06-07 21:30:51Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -8,6 +9,9 @@
 require 'rbrainz/model/entity'
 require 'rbrainz/model/release_event'
 require 'rbrainz/model/disc'
+require 'rbrainz/model/rateable'
+require 'rbrainz/model/relateable'
+require 'rbrainz/model/taggable'
 
 module MusicBrainz
   module Model
@@ -26,6 +30,10 @@ module MusicBrainz
     #        for more information.
     class Release < Entity
     
+      include Rateable
+      include Relateable
+      include Taggable
+      
       # A type for not a type. Currently unsupported by MusicBrainz
       TYPE_NONE           = NS_MMD_1 + 'None'
       
@@ -113,6 +121,9 @@ module MusicBrainz
       # See:: Utils#get_script_name
       attr_accessor :text_script
                     
+      # The release group this release is part of.
+      attr_accessor :release_group
+
       # The list of tracks.
       attr_reader :tracks
 
@@ -138,6 +149,7 @@ module MusicBrainz
       def initialize(id=nil, title=nil)
         super id
         self.title      = title
+        @release_groups = Collection.new
         @tracks         = Collection.new
         @release_events = Collection.new
         @discs          = Collection.new
@@ -153,9 +165,11 @@ module MusicBrainz
       #
       # Note that the release's artist has to be set (see #artist=)
       # for this. The track artists may be unset.
+      #
+      # Raises:: RuntimeError
       def single_artist_release?
           raise 'Release Artist may not be None!' unless artist
-          tracks.all {|track| !track.artist || track.artist.id == artist.id }
+          tracks.all? {|track| !track.artist || track.artist.id == artist.id }
       end
     
       # Returns the earliest release date as an IncompleteDate.
@@ -194,4 +208,4 @@ module MusicBrainz
     end
     
   end    
-end
+end

data/lib/rbrainz/model/release_event.rb

@@ -1,4 +1,5 @@
-# $Id: release_event.rb 189 2007-11-26 00:10:49Z phw $
+# -*- coding: utf-8 -*-
+# $Id: release_event.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -82,4 +83,4 @@ module MusicBrainz
     end
     
   end    
-end
+end

data/lib/rbrainz/model/release_group.rb

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+# $Id: release_group.rb 269 2009-05-24 22:15:27Z 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/entity'
+require 'rbrainz/model/release'
+
+module MusicBrainz
+  module Model
+
+    #
+    # A release group in the MusicBrainz DB.
+    #
+    # A release group within MusicBrainz is an Entity which groups several
+    # different versions of releases (e.g. different editions of the same album).
+    #
+    # See:: http://wiki.musicbrainz.org/Release_Groups
+    class ReleaseGroup < Entity
+      
+      # A type for not a type. Currently unsupported by MusicBrainz
+      TYPE_NONE           = NS_MMD_1 + 'None'
+      
+      # Special type for release groups that hold non-album track releases.
+      TYPE_NON_ALBUM_TRACKS = NS_MMD_1 + 'NonAlbum Track'
+      
+      # An album, perhaps better defined as a "Long Play" (LP) release,
+      # generally consists of previously unreleased material. This includes
+      # release re-issues, with or without bonus tracks.
+      TYPE_ALBUM          = NS_MMD_1 + 'Album'
+      # An audiobook is a book read by a narrator without music.
+      TYPE_AUDIOBOOK      = NS_MMD_1 + 'Audiobook'
+      # A compilation is a collection of previously released tracks by one or
+      # more artists. Please note that this is a simplified description of a
+      # compilation.
+      TYPE_COMPILATION    = NS_MMD_1 + 'Compilation'
+      # An EP is a so-called "Extended Play" release and often contains the
+      # letters EP in the title.
+      TYPE_EP             = NS_MMD_1 + 'EP'
+      # An interview release contains an interview, generally with an Artist.
+      TYPE_INTERVIEW      = NS_MMD_1 + 'Interview'
+      # A release that was recorded live.
+      TYPE_LIVE           = NS_MMD_1 + 'Live'
+      # A release that primarily contains remixed material.
+      TYPE_REMIX          = NS_MMD_1 + 'Remix'
+      # A single typically has one main song and possibly a handful of
+      # additional tracks or remixes of the main track. A single is usually
+      # named after its main song.
+      TYPE_SINGLE         = NS_MMD_1 + 'Single'
+      # A soundtrack is the musical score to a movie, TV series, stage show,
+      # computer game etc.
+      TYPE_SOUNDTRACK     = NS_MMD_1 + 'Soundtrack'
+      # Non-music spoken word releases.
+      TYPE_SPOKENWORD     = NS_MMD_1 + 'Spokenword'
+      # Any release that does not fit or can't decisively be placed in any of
+      # the categories above.
+      TYPE_OTHER          = NS_MMD_1 + 'Other'
+      
+      # See Entity::ENTITY_TYPE.
+      ENTITY_TYPE = :release_group # :nodoc:
+      
+      # The title of this release group.
+      attr_accessor :title
+      
+      # A Collection of releases in this release group.
+      attr_reader :releases
+      
+      # The artist of this release group.
+      attr_accessor :artist
+      
+      # 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(id=nil, title=nil)
+        super id
+        @title = title
+        @releases = Collection.new
+        @types = Array.new
+      end
+      
+      # Returns the string representation for this release group.
+      # 
+      # Returns #title converted into a string.
+      def to_s
+        title.to_s
+      end
+        
+    end
+  
+  end
+end

data/lib/rbrainz/model/scored_collection.rb

@@ -1,4 +1,5 @@
-# $Id: scored_collection.rb 172 2007-08-24 11:19:19Z phw $
+# -*- coding: utf-8 -*-
+# $Id: scored_collection.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -104,4 +105,4 @@ module MusicBrainz
     end
     
   end
-end
+end

data/lib/rbrainz/model/tag.rb

@@ -1,4 +1,5 @@
-# $Id: tag.rb 181 2007-10-04 09:20:49Z phw $
+# -*- coding: utf-8 -*-
+# $Id: tag.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -23,8 +24,8 @@ module MusicBrainz
       attr_accessor :count
       
       def initialize(text=nil, count=nil)
-        self.text  = text
-        self.count = count
+        @text  = text
+        @count = count
       end
       
       # Convert this tag into a String. Will return text.
@@ -35,4 +36,4 @@ module MusicBrainz
     end
 
   end
-end
+end

data/lib/rbrainz/model/taggable.rb

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# $Id: taggable.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/tag'
+
+module MusicBrainz
+  module Model
+
+    # Mixin module to add folksonomy tagging capabilities to Entity classes.
+    #
+    # see:: Tag
+    module Taggable
+      
+      # Returns a Collection of Tag objects assigned to this entity.
+      def tags
+        @tags ||= Collection.new
+      end
+      
+    end
+      
+  end
+end

data/lib/rbrainz/model/track.rb

@@ -1,4 +1,5 @@
-# $Id: track.rb 145 2007-07-19 13:11:44Z phw $
+# -*- coding: utf-8 -*-
+# $Id: track.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,6 +7,10 @@
 #             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'rbrainz/model/entity'
+require 'rbrainz/model/isrc'
+require 'rbrainz/model/rateable'
+require 'rbrainz/model/relateable'
+require 'rbrainz/model/taggable'
 
 module MusicBrainz
   module Model
@@ -15,6 +20,10 @@ module MusicBrainz
     # See:: http://musicbrainz.org/doc/Track.
     class Track < Entity
     
+      include Rateable
+      include Relateable
+      include Taggable
+      
       # See Entity::ENTITY_TYPE.
       ENTITY_TYPE = :track # :nodoc:
       
@@ -30,6 +39,9 @@ module MusicBrainz
       # The list of associated PUIDs.           
       attr_reader :puids
       
+      # The list of associated ISRCs.           
+      attr_reader :isrcs
+      
       # The releases on which this track appears.
       attr_reader :releases
       
@@ -37,6 +49,7 @@ module MusicBrainz
         super id
         self.title = title
         @puids     = Collection.new
+        @isrcs     = Collection.new
         @releases  = Collection.new
       end
       
@@ -50,4 +63,4 @@ module MusicBrainz
     end
 
   end
-end
+end

data/lib/rbrainz/model/user.rb

@@ -1,4 +1,5 @@
-# $Id: user.rb 145 2007-07-19 13:11:44Z phw $
+# -*- coding: utf-8 -*-
+# $Id: user.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Nigel Graham (mailto:nigel_graham@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -45,4 +46,4 @@ module MusicBrainz
     end
 
   end
-end
+end

data/lib/rbrainz/utils.rb

@@ -1,4 +1,5 @@
-# $Id: utils.rb 143 2007-07-18 11:40:55Z phw $
+# -*- coding: utf-8 -*-
+# $Id: utils.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer

data/lib/rbrainz/utils/data.rb

@@ -1,4 +1,5 @@
-# $Id: data.rb 141 2007-07-17 14:21:12Z phw $
+# -*- coding: utf-8 -*-
+# $Id: data.rb 273 2009-05-24 22:29:04Z phw $
 #
 # Helper methods to deal with MusicBrainz data.
 #
@@ -75,4 +76,4 @@ module MusicBrainz
     end
     
   end
-end
+end

data/lib/rbrainz/utils/helper.rb

@@ -1,4 +1,5 @@
-# $Id: helper.rb 173 2007-08-24 15:11:11Z phw $
+# -*- coding: utf-8 -*-
+# $Id: helper.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Nigel Graham, Philipp Wolfer
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -31,6 +32,11 @@ module MusicBrainz
         end
       end
       
+      # Converts an entity type constant symbol into the proper string representation 
+      def entity_type_to_string(entity_type)
+        return entity_type.to_s.sub('_', '-')
+      end
+      
       # Check an options hash for required options.
       # Raises an ArgumentError if unknown options are present in the hash.
       def check_options(options, *optdecl)   # :nodoc:
@@ -44,4 +50,4 @@ module MusicBrainz
     end
       
   end
-end
+end

data/lib/rbrainz/version.rb

@@ -1,4 +1,5 @@
-# $Id: version.rb 219 2008-09-04 18:14:48Z phw $
+# -*- coding: utf-8 -*-
+# $Id: version.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Version information.
 #
@@ -10,6 +11,6 @@
 module MusicBrainz
 
   # The version of the RBrainz library.
-  RBRAINZ_VERSION = '0.4.2'
+  RBRAINZ_VERSION = '0.5.0'
 
 end

data/lib/rbrainz/webservice.rb

@@ -1,4 +1,5 @@
-# $Id: webservice.rb 146 2007-07-19 16:33:38Z phw $
+# -*- coding: utf-8 -*-
+# $Id: webservice.rb 254 2009-05-13 20:04:36Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -20,20 +21,24 @@ module MusicBrainz # :nodoc:
   # 
   # See:: Model
   module Webservice
+    
+    # Base exception class for all webservice errors.
+    class WebserviceError < ::Exception
+    end
 
     # Connecting to the web service failed.
     #
     # This exception is raised if the connection to the server can not be
     # established due to networking problems (e.g. wrong port number or
     # server down).
-    class ConnectionError < Exception
+    class ConnectionError < WebserviceError
     end
     
     # An invalid request was made.
     # 
     # This exception is raised if the client made an invalid request. That could
     # be syntactically invalid identifiers or unknown or invalid parameter values.
-    class RequestError < Exception
+    class RequestError < WebserviceError
     end
     
     # Client requested a resource which requires authentication via HTTP
@@ -41,11 +46,11 @@ module MusicBrainz # :nodoc:
     # 
     # If sent even though user name and password were given: user name and/or
     # password are incorrect. 
-    class AuthenticationError < Exception
+    class AuthenticationError < WebserviceError
     end
     
     # The requested resource doesn't exist.
-    class ResourceNotFoundError < Exception
+    class ResourceNotFoundError < WebserviceError
     end
 
     # The returned resource was invalid.
@@ -53,10 +58,10 @@ module MusicBrainz # :nodoc:
     # This may be due to a malformed XML document or if the requested data
     # wasn't part of the response. It can only occur in case of bugs in the web
     # service itself.
-    class ResponseError < Exception
+    class ResponseError < WebserviceError
     end
     
   end 
 end
 
-require 'rbrainz/webservice/query'
+require 'rbrainz/webservice/query'

data/lib/rbrainz/webservice/filter.rb

@@ -1,4 +1,5 @@
-# $Id: filter.rb 203 2008-03-17 11:00:15Z phw $
+# -*- coding: utf-8 -*-
+# $Id: filter.rb 264 2009-05-24 22:15:19Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -70,6 +71,50 @@ module MusicBrainz
     
     end
     
+    # A filter for the release group collection.
+    class ReleaseGroupFilter < AbstractFilter
+    
+      # The parameter _filter_ is a hash with filter options. At least one
+      # filter despite <tt>:limit</tt> and <tt>:offset</tt> must be specified.
+      # 
+      # Available filter options:
+      # [:title]     Fetch a list of release groups with a matching title.
+      # [:artist]    The returned release groups should match the given artist name.
+      # [:artistid]  The returned releasegroups should match the given artist ID
+      #              (36 character ASCII representation). If this is given,
+      #              the artist parameter is ignored.
+      # [:releasetypes] The returned release groups must match all of the given
+      #                 release types. This is either an array of release types
+      #                 as defined in Model::ReleaseGroup or a string of space separated
+      #                 values like Official, Bootleg, Album, Compilation etc.
+      # [:limit]     The maximum number of release groups returned. Defaults
+      #              to 25, the maximum allowed value is 100. 
+      # [:offset]    Return search results starting at a given offset. Used
+      #              for paging through more than one page of results.
+      # [:query]     A Lucene search query. The query parameter is a search
+      #              string which will be passed to the underlying Lucene search
+      #              engine. It must follow the syntax described in
+      #              http://musicbrainz.org/doc/TextSearchSyntax.
+      def initialize(filter)
+        Utils.check_options filter, 
+          :limit, :offset, :query, :title, :artist, :artistid, :releasetypes
+        super(filter)
+        @filter[:title]        = filter[:title]     if filter[:title]
+        @filter[:artist]       = filter[:artist]    if filter[:artist]
+        @filter[:artistid]     = filter[:artistid]  if filter[:artistid]
+        
+        if releasetypes = filter[:releasetypes]
+          if releasetypes.respond_to?(:to_a)
+            releasetypes = releasetypes.to_a.map do |type|
+              Utils.remove_namespace(type)
+            end.join(' ')
+          end
+          @filter[:releasetypes] = releasetypes
+        end
+      end
+    
+    end
+    
     # A filter for the release collection.
     class ReleaseFilter < AbstractFilter
     
@@ -92,7 +137,9 @@ module MusicBrainz
       # [:asin]      The Amazon ASIN.
       # [:lang]      The language for this release.
       # [:script]    The script used in this release.
-      # [:limit]     The maximum number of tracks returned. Defaults
+      # [:cdstubs]   Flag which indicates whether to include CD stubs or not (boolean).
+      #              Defaults to false.
+      # [:limit]     The maximum number of releases returned. Defaults
       #              to 25, the maximum allowed value is 100. 
       # [:offset]    Return search results starting at a given offset. Used
       #              for paging through more than one page of results.
@@ -103,7 +150,7 @@ module MusicBrainz
       def initialize(filter)
         Utils.check_options filter, 
           :limit, :offset, :query, :title, :discid, :artist, :artistid, 
-          :releasetypes, :count, :date, :asin, :lang, :script
+          :releasetypes, :count, :date, :asin, :lang, :script, :cdstubs
         super(filter)
         @filter[:title]        = filter[:title]     if filter[:title]
         @filter[:discid]       = filter[:discid]    if filter[:discid]
@@ -115,6 +162,8 @@ module MusicBrainz
         @filter[:lang]         = filter[:lang]      if filter[:lang]
         @filter[:script]       = filter[:script]    if filter[:script]
         
+        @filter[:cdstubs] = filter[:cdstubs] ? 'yes' : 'no'
+        
         if releasetypes = filter[:releasetypes]
           if releasetypes.respond_to?(:to_a)
             releasetypes = releasetypes.to_a.map do |type|
@@ -218,4 +267,4 @@ module MusicBrainz
     end
     
   end
-end
+end