rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/model/release_event.rb

@@ -1,23 +1,52 @@
-# $Id: release_event.rb 9 2007-05-21 21:16:34Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: release_event.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/label'
 
 module MusicBrainz
   module Model
 
-    # A release event in the MusicBrainz DB.
+    #
+    # A release event in the MusicBrainz DB indicating where and when a release
+    # took place.
     # 
-    # See http://musicbrainz.org/doc/ReleaseEvent.
+    # All country codes used must be valid ISO-3166 country codes (i.e. 'DE',
+    # 'UK' or 'FR'). The dates are instances of IncompleteDate or strings which
+    # must have the format 'YYYY', 'YYYY-MM' or 'YYYY-MM-DD'.
+    #
+    # See:: http://musicbrainz.org/doc/ReleaseEvent.
+    #
     class ReleaseEvent
     
-      attr_accessor :country, :catalog_number,
-                    :barcode, :label
-                    
+      # The country in which an album was released.
+      # A string containing a ISO 3166 country code like
+      # 'GB', 'US' or 'DE'.
+      # 
+      # See:: Utils#get_country_name
+      # See:: http://musicbrainz.org/doc/ReleaseCountry
+      attr_accessor :country
+      
+      # The catalog number given to the release by the label.
+      attr_accessor :catalog_number
+      
+      # The barcode as it is printed on the release.
+      attr_accessor :barcode
+      
+      # The label issuing the release.
+      attr_accessor :label
+      
+      # The release date. An instance of IncompleteDate.
       attr_reader :date
       
+      def initialize(country=nil, date=nil)
+        self.country = country
+        self.date    = date if date
+      end
+      
       # Set the date the release took place.
       # 
       # Should be an IncompleteDate object or

data/lib/rbrainz/model/scored_collection.rb

@@ -0,0 +1,99 @@
+# $Id: scored_collection.rb 136 2007-07-16 15:45:32Z 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/collection'
+
+module MusicBrainz
+  module Model
+
+    # A ScoredCollection is a list of entities with scores.
+    # 
+    # A ScoredCollection is returned as the result of an entity search (e.g. search
+    # for an Artist). It contains an ordered list of Entry objects which wrap
+    # the entities and a corresponding search score, which indicates how good
+    # the entity matches the search criteria used for the search. The entities
+    # in a scored collection are sorted by score (in descending order).
+    # 
+    # 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.
+    # 
+    # See http://lucene.apache.org/java/docs/scoring.html for more information
+    # about the scoring system used by MusicBrainz.
+    class ScoredCollection < Collection
+    
+      # An entry in a ScoredCollection wrapping an entity and a
+      # corresponding search result score.
+      class Entry
+        include Comparable
+        attr_accessor :entity, :score
+        
+        def initialize(entity, score=nil)
+          @entity = entity
+          @score  = score
+        end
+        
+        def <=>(other)
+          if self.score.nil? && other.score.nil?
+            return self.entity <=> other.entity
+          end
+          return -1 if self.score.nil?
+          return 1 if other.score.nil?
+          
+          return self.score <=> other.score
+        end
+      end
+    
+      # Return an array of all entities.
+      def entities
+        return map {|entry| entry.entity}
+      end
+      
+      # Add a new entry to the collection.
+      # 
+      # You may either add a ScoredCollection::Entry, just an Model::Entity
+      # or an object responding to +first+ and +last+ where +first+ must
+      # return the entity and +last+ the score.
+      # 
+      # Examples:
+      #  include MusicBrainz
+      #  artist = Model::Artist.new
+      #  
+      #  collection << Model::ScoredCollection::Entry.new(artist, 100)
+      #  collection << [artist, 100]
+      #  collection << artist
+      def <<(entry)
+        super wrap(entry)
+      end
+      
+      # Set the entry at the given position.
+      # 
+      # You may either add a ScoredCollection::Entry, just an Model::Entity
+      # or an object responding to +first+ and +last+ where +first+ must
+      # return the entity and +last+ the score.
+      def []=(index, entry)
+        super wrap(entry)
+      end
+      
+      private #-----------------------------------------------------------------
+      
+      def wrap(entry)
+        unless entry.is_a? Entry
+          if entry.respond_to?(:first) and entry.respond_to?(:last)
+            entry = Entry.new(entry.first, entry.last)
+          else
+            entry = Entry.new(entry)
+          end
+        end
+        return entry
+      end
+    end
+    
+  end
+end

data/lib/rbrainz/model/tag.rb

@@ -0,0 +1,39 @@
+# $Id: tag.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
+
+    #
+    # Represents a tag assigned to an entity.
+    # 
+    # Tags are arbitrary labels assigned to entities by the users of MusicBrainz.
+    # 
+    # Note:: Tagging is not supported by the current MusicBrainz server but will
+    #        be added in the near future.
+    class Tag
+      # The tag text.
+      attr_accessor :text
+
+      # The tag count indicating how often the tag was used for the entity it's
+      # assigned to.
+      attr_accessor :count
+      
+      def initialize(text=nil, count=nil)
+        self.text  = text
+        self.count = count
+      end
+      
+      # Convert this tag into a String. Will return text.
+      def to_s
+        return text.to_s
+      end
+      
+    end
+
+  end
+end

data/lib/rbrainz/model/track.rb

@@ -1,7 +1,9 @@
-# $Id: track.rb 30 2007-05-29 02:12:33Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: track.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'
 
@@ -10,17 +12,39 @@ module MusicBrainz
 
     # A track in the MusicBrainz DB.
     # 
-    # See http://musicbrainz.org/doc/Track.
+    # See:: http://musicbrainz.org/doc/Track.
     class Track < Entity
     
-      attr_accessor :title, :duration, :artist
-                    
-      attr_reader :puids, :releases
-      
-      def initialize
-        super
-        @puids = Array.new
-        @releases = Array.new
+      # See Entity::ENTITY_TYPE.
+      ENTITY_TYPE = :track # :nodoc:
+      
+      # The track's title.
+      attr_accessor :title
+      
+      # The duration in milliseconds.
+      attr_accessor :duration
+      
+      # The track's main artist.
+      attr_accessor :artist
+      
+      # The list of associated PUIDs.           
+      attr_reader :puids
+      
+      # The releases on which this track appears.
+      attr_reader :releases
+      
+      def initialize(id=nil, title=nil)
+        super id
+        self.title = title
+        @puids     = Collection.new
+        @releases  = Collection.new
+      end
+      
+      # Returns the string representation for this track.
+      # 
+      # Returns #title converted into a string.
+      def to_s
+        title.to_s
       end
       
     end

data/lib/rbrainz/model/user.rb

@@ -0,0 +1,48 @@
+# $Id: user.rb 145 2007-07-19 13:11:44Z phw $
+#
+# Author::    Nigel Graham (mailto:nigel_graham@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
+
+    # A MusicBrainz user.
+    class User
+      # The MusicBrainz user name.
+      attr_accessor :name
+
+      # The user's types.
+      # 
+      # Most users' type list is empty. Currently, the following types
+      # are defined:
+      #
+      # - 'http://musicbrainz.org/ns/ext-1.0#AutoEditor'
+      # - 'http://musicbrainz.org/ns/ext-1.0#RelationshipEditor'
+      # - 'http://musicbrainz.org/ns/ext-1.0#Bot'
+      # - 'http://musicbrainz.org/ns/ext-1.0#NotNaggable'
+      attr_reader :types
+      
+      def initialize(name=nil)
+        self.name = name
+        @types = []
+      end
+      
+      # The setter for the nag screen flag.
+      def show_nag=(value)
+        @show_nag = (value.to_s == 'true')
+      end
+      
+      # The value of the nag screen flag.
+      def show_nag?
+        @show_nag
+      end
+      
+      def to_s
+        return name.to_s
+      end
+    end
+
+  end
+end

data/lib/rbrainz/utils.rb

@@ -0,0 +1,9 @@
+# $Id: utils.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/version'
+Dir[File.dirname(__FILE__) + "/utils/*.rb"].each { |file| require(file) }

data/lib/rbrainz/utils/data.rb

@@ -0,0 +1,78 @@
+# $Id: data.rb 141 2007-07-17 14:21:12Z phw $
+#
+# Helper methods to deal with MusicBrainz data.
+#
+# 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/data/countrynames'
+require 'rbrainz/data/languagenames'
+require 'rbrainz/data/scriptnames'
+require 'rbrainz/data/releasetypenames'
+
+module MusicBrainz
+
+  # This module contains helper functions to make common tasks easier.
+  module Utils
+  
+    # Returns a country's name based on an ISO-3166 country code.
+    #
+    # The country table this function is based on has been modified for
+    # MusicBrainz purposes by using the extension mechanism defined in ISO-3166.
+    # All IDs are still valid ISO-3166 country codes, but some IDs have been
+    # added to include historic countries and some of the country names have
+    # been modified to make them better suited for display purposes.
+    # 
+    # If the country ID is not found, +nil+ is returned. This may happen for
+    # example, when new countries are added to the MusicBrainz web service which
+    # aren't known to this library yet.
+    # 
+    # See:: #Data::COUNTRY_NAMES
+    def self.get_country_name(id)
+      return Data::COUNTRY_NAMES[id]
+    end
+    
+    # Returns a language name based on an ISO-639-2/T code.
+    # 
+    # This function uses a subset of the ISO-639-2/T code table to map language
+    # IDs (terminologic, not bibliographic ones!) to names.
+    # 
+    # If the language ID is not found, +nil+ is returned. This may happen for
+    # example, when new languages are added to the MusicBrainz web service which
+    # aren't known to this library yet.
+    # 
+    # See:: #Data::LANGUAGE_NAMES
+    def self.get_language_name(id)
+      return Data::LANGUAGE_NAMES[id]
+    end
+    
+    # Returns a script name based on an ISO-15924 code.
+    # 
+    # This function uses a subset of the ISO-15924 code table to map script
+    # IDs to names.
+    # 
+    # If the script ID is not found, +nil+ is returned. This may happen for
+    # example, when new scripts are added to the MusicBrainz web service which
+    # aren't known to this library yet.
+    # 
+    # See:: #Data::SCRIPT_NAMES
+    def self.get_script_name(id)
+      return Data::SCRIPT_NAMES[id]
+    end
+    
+    # Returns the name of a release type URI.
+    # 
+    # If the release type is not found, +nil+ is returned. This may happen for
+    # example, when new release types are added to the MusicBrainz web service
+    # which aren't known to this library yet.
+    # 
+    # See:: #Data::RELEASE_TYPE_NAMES
+    # See:: Model::Release
+    def self.get_release_type_name(id)
+      return Data::RELEASE_TYPE_NAMES[id]
+    end
+    
+  end
+end

data/lib/rbrainz/utils/helper.rb

@@ -0,0 +1,22 @@
+# $Id: helper.rb 141 2007-07-17 14:21:12Z phw $
+#
+# Author::    Nigel Graham, Philipp Wolfer
+# 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 Utils
+  
+    # Check an options hash for required options.
+    # Raises an ArgumentError if unknown options are present in the hash.
+    def self.check_options(options, *optdecl)   # :nodoc:
+      h = options.dup
+      optdecl.each do |name|
+        h.delete name
+      end
+      raise ArgumentError, "no such option: #{h.keys.join(' ')}" unless h.empty?
+    end
+      
+  end
+end

data/lib/rbrainz/version.rb

@@ -0,0 +1,15 @@
+# $Id: version.rb 143 2007-07-18 11:40:55Z phw $
+#
+# Version information.
+#
+# 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
+
+  # The version of the RBrainz library.
+  RBRAINZ_VERSION = '0.2.0'
+
+end