rbrainz 0.1.1 → 0.2.0

data/CHANGES

@@ -0,0 +1,31 @@
+= Changelog
+
+== 0.2.0 (2007-07-19)
+* Querying of collections implemented
+* Collection class to store search results (with support for search score and offset)
+* User authentication
+* Querying of user information
+* Support POST in Webservice class to submit information.
+* PUID submission.
+* Made IncompleteDate behave like a range with corresponding equality operations
+* Restructured MBID to use a ducktyping approach
+* Introduced Individual as superclass for Artist and Label
+* Added unique_name method for Artist and Label
+* Label: Renamed founding_date and dissolving_date to begin_date
+  and end_date (to be more consistent with Artist)
+* Support for label aliases
+* Added label type "Unknown"
+* Full text search (lucene search queries).
+* Support entity tags as defined in the MB metadata scheme 1.2. Currently only
+  available on test.musicbrainz.org.
+* New Model::DefaultFactory
+
+== 0.1.1 (2007-05-29)
+* Full support for relations
+* Proper exception handling in Webservice class
+* Minor corrections
+
+== 0.1.0 (2007-05-23)
+* Initial release
+
+$Id: CHANGES 145 2007-07-19 13:11:44Z phw $

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007, Philipp Wolfer
+RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions

data/README

@@ -7,5 +7,6 @@ To generate the complete RBrainz documentation run
  
 The documentation will be stored in doc/api.
 
-Copyright (c) 2007, Philipp Wolfer
-Licensing information can be found in the file LICENSE.
+RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
+It is free softare distributed under a BSD style license. See
+LICENSE for details.

data/Rakefile

@@ -1,4 +1,4 @@
-# $Id: Rakefile 34 2007-05-29 15:08:03Z phw $
+# $Id: Rakefile 145 2007-07-19 13:11:44Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -9,48 +9,51 @@ require 'rubygems'
 require 'rake/gempackagetask'
 require 'rake/testtask'
 require 'rake/rdoctask'
+require './lib/rbrainz/version'
+
+task :default do
+  puts "Please see 'rake --tasks' for an overview of the available tasks."
+end
 
 # Packaging tasks: -------------------------------------------------------
 
 PKG_NAME = 'rbrainz'
-PKG_VERSION = '0.1.1'
+PKG_VERSION = MusicBrainz::RBRAINZ_VERSION
 PKG_FILES = FileList[
-  "Rakefile", "LICENSE", "README", "TODO",
+  "Rakefile", "LICENSE", "README", "TODO", "CHANGES",
   "doc/README.rdoc",
-  "examples/**/*",
+  "examples/**/*.rb",
   "lib/**/*.rb",
   "test/**/*.rb",
   "test/test-data/**/*"
 ]
+PKG_EXTRA_RDOC_FILES = ['doc/README.rdoc', 'LICENSE', 'TODO', 'CHANGES']
 
 spec = Gem::Specification.new do |spec|
   spec.platform = Gem::Platform::RUBY
-  spec.summary = 'Ruby library for the MusicBrainz XML webservice.'
+  spec.summary = 'Ruby library for the MusicBrainz XML web service.'
   spec.name = PKG_NAME
   spec.version = PKG_VERSION
-  spec.requirements << 'none'
-  spec.require_path = 'lib'
-  spec.autorequire = 'rbrainz'
+  spec.requirements << 'Optional: mb-discid >= 0.1.2 (for calculating disc IDs)'
+  spec.autorequire = spec.name
   spec.files = PKG_FILES
   spec.description = <<EOF
     RBrainz is a Ruby client library to access the MusicBrainz XML
-    webservice written in pure Ruby.
+    web service. RBrainz supports the MusicBrainz XML Metadata Version 1.2,
+    including support for labels and extended release events.
     
     RBrainz follows the design of python-musicbrainz2, the reference
     implementation for a MusicBrainz client library. Developers used to
     python-musicbrainz2 should already know most of RBrainz' interface.
     However, RBrainz differs from python-musicbrainz2 wherever it makes
     the library more Ruby like or easier to use.
-    
-    RBrainz supports the MusicBrainz XML Metadata Version 1.1, including
-    support for labels and extended release events.
 EOF
-  spec.author = 'Philipp Wolfer' 
+  spec.author = ['Philipp Wolfer', 'Nigel Graham']
   spec.email = 'phw@rubyforge.org'
   spec.homepage = 'http://rbrainz.rubyforge.org'
   spec.rubyforge_project = 'rbrainz'
   spec.has_rdoc = true
-  spec.extra_rdoc_files = ['doc/README.rdoc']
+  spec.extra_rdoc_files = PKG_EXTRA_RDOC_FILES
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
@@ -58,6 +61,16 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_tar_gz= true
 end
 
+# Build the RBrainz gem and install it"
+task :install => [:test, :gem] do
+  sh %{gem install pkg/#{PKG_NAME}-#{PKG_VERSION}.gem}
+end
+
+# Uninstall RBrainz"
+task :uninstall => [:gem] do
+  sh %{gem uninstall #{PKG_NAME}}
+end
+
 # Test tasks: ------------------------------------------------------------
 
 desc "Run the unit and functional tests"
@@ -83,9 +96,9 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title    = "RBrainz %s" % PKG_VERSION
   rdoc.main     = 'doc/README.rdoc'
   rdoc.rdoc_dir = 'doc/api'
-  rdoc.rdoc_files.include('doc/README.rdoc', 'lib/**/*.rb',
-                          'LICENSE', 'TODO')
-  rdoc.options << '--inline-source' << '--line-numbers'
+  rdoc.rdoc_files.include('lib/**/*.rb', PKG_EXTRA_RDOC_FILES)
+  rdoc.options << '--inline-source' << '--line-numbers' \
+               << '--charset=UTF-8' #<< '--diagram'
 end
 
 # Other tasks: -----------------------------------------------------------
@@ -95,10 +108,10 @@ def egrep(pattern)
     count = 0
     open(fn) do |f|
       while line = f.gets
-	count += 1
-	if line =~ pattern
-	  puts "#{fn}:#{count}:#{line}"
-	end
+    	count += 1
+    	if line =~ pattern
+    	  puts "#{fn}:#{count}:#{line}"
+    	end
       end
     end
   end
@@ -106,5 +119,10 @@ end
 
 desc "Look for TODO and FIXME tags in the code"
 task :todo do
-  egrep /#.*(FIXME|TODO)/
+  egrep(/#.*(FIXME|TODO)/)
+end
+
+desc "Print version information"
+task :version do
+  puts "%s %s" % [PKG_NAME, PKG_VERSION]
 end

data/TODO

@@ -1,29 +1,12 @@
-=TODO
+= TODO
 
-==Short term tasks
-* Query collections (0.2.0)
-* Support for the score parameter in search result. Could be implemented
-  a little bit like in PythonMusicBrainz2, but more flexible. Maybe a result
-  object over which one can iterate to retrieve all results with the
-  corresponding score. (0.2.0)
-   result.each {|entity, score|
-     ...
-   }
-* Support for the offset parameter for queries on collections
-  to retrieve results below the 100 results limit. Could be easily integrated
-  into the result object (see previous point). (0.2.0)
-* Make it easier to create MBID objects or allow usage of ID strings
-  where it makes life easier (>= 0.2.1).
-* Add usefull constructor parameters to the models (>= 0.2.1).
+== Short term tasks
 * Improve API documentation.
 
-==Longer term tasks
-* Calculation of disc IDs (0.3.0)
-* User authentication (0.4.0)
-* Querying of user information (0.4.0)
-* PUID submission
-* Full text search (lucene search queries).
+== Longer term tasks
 * Implement a command line tool (+mbquery+) for querying the MusicBrainz
   database which will serve as a usefull example for RBrainz.
 * Support for common extensions (this could be implemented by adding
-  additional extension libraries which extend the existing classes).
+  additional extension libraries which extend the existing classes).
+  
+$Id: TODO 129 2007-07-12 17:52:17Z phw $

data/doc/README.rdoc

@@ -1,40 +1,45 @@
-=RBrainz - Ruby MusicBrainz library
-RBrainz is a Ruby client library to access the MusicBrainz XML webservice,
+= RBrainz - Ruby MusicBrainz library
+RBrainz is a Ruby client library to access the MusicBrainz XML web service,
 which can be used to query the MusicBrainz database.
 
-RBrainz is written in pure Ruby and follows the design of
+RBrainz is written in Ruby and follows the design of
 PythonMusicBrainz2[http://musicbrainz.org/doc/PythonMusicBrainz2],
 the reference implementation for a MusicBrainz client library. Developers
 used to PythonMusicBrainz2 should already know most of RBrainz' interface.
 However, RBrainz differs from PythonMusicBrainz2 wherever it makes the
 library more Ruby like or easier to use.
 
-RBrainz supports the MusicBrainz XML Metadata Version 1.1, including support
+RBrainz supports the MusicBrainz XML Metadata Version 1.2, including support
 for labels and extended release events.
 
-==Installation
-===Installing with RubyGems
+== Installation
+=== Installing with RubyGems
 The easiest way to install the latest release of RBrainz is using
 RubyGems[http://rubygems.org] by executing the following command:
  gem install rbrainz
  
-===Manual installation
-Not supported, yet.
+=== Manual installation
+If you downloaded the RBRainz source package or checked out the latest version
+from SVN you can install it with
+ rake install
+ 
+You still need RubyGems for the installation to succeed.
 
-==Basic usage
+== Basic usage
 The most important classes in this library are the model classes
 MusicBrainz::Model::Artist, MusicBrainz::Model::Release,
 MusicBrainz::Model::Track and MusicBrainz::Model::Label
 together with MusicBrainz::Webservice::Query. The Query class
 provides an easy to use interface to query the MusicBrainz webservice.
-It will always return one of the model classes above or an
-array of those classes. The example below should make the usage clear:
+It will always return one of the model classes above or a
+MusicBrainz::Model::ScoredCollection of those classes. The example below
+should make the usage clear:
 
  require 'rbrainz'
  include MusicBrainz
  
  # Create an MBID object which represents a MusicBrainz artist ID.
- mbid = Model::MBID.from_uuid(:artist, 'c0b2500e-0cef-4130-869d-732b23ed9df5')
+ mbid = Model::MBID.new('c0b2500e-0cef-4130-869d-732b23ed9df5', :artist)
 
  # With the ArtistInclude object we can control what kind of information
  # the MusicBrainz server will include in its answer.
@@ -48,21 +53,45 @@ array of those classes. The example below should make the usage clear:
    :url_rels     => true
  )
  
- # Query the webservice for the artist with the above ID
- # The result will contain all the information specified
- # in artist_includes.
- q = Webservice::Query.new
- artist = q.get_artist_by_id(mbid, artist_includes)
+ # Query the webservice for the artist with the above ID. The result
+ # will contain all the information specified in artist_includes.
+ query = Webservice::Query.new
+ artist = query.get_artist_by_id(mbid, artist_includes)
+ 
+ # Display the fetched artist data together with all unique release titles.
+ print <<EOF
+ ID            : #{artist.id.uuid}
+ Name          : #{artist.name}
+ Sort name     : #{artist.sort_name}
+ Disambiguation: #{artist.disambiguation}
+ Type          : #{artist.type}
+ Begin date    : #{artist.begin_date}
+ End date      : #{artist.end_date}
+ Aliases       : #{artist.aliases.to_a.join('; ')}
+ Releases      : #{artist.releases.map{|r| r.title}.uniq.join("\r\n                ")}
+ EOF
 
-==The MusicBrainz webservice
+== The MusicBrainz webservice
 For more information about the MusicBrainz webservice visit the
 following resources:
 - MusicBrainzXMLWebService[http://musicbrainz.org/doc/XMLWebService]
 - MusicBrainzXMLMetaData[http://musicbrainz.org/doc/MusicBrainzXMLMetaData]
 
-==License
-RBrainz is Copyright (c) 2007 Philipp Wolfer.
+== Contact
+For more information about RBrainz visit http://rbrainz.rubyforge.org.
+
+If you have any questions or suggestions regarding RBrainz please write to
+the rbrainz-user mailinglist[http://rubyforge.org/mail/?group_id=3677].
+If you find bugs or if you have any feature requests please use the
+RBrainz bug tracker[http://rubyforge.org/tracker/?group_id=3677]. 
+
+== Authors
+* Nigel Graham
+* Philipp Wolfer
+
+== License
+RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
 It is free softare distributed under a BSD style license. See
 LICENSE[link:files/LICENSE.html] for details.
 
-$Id: README.rdoc 5 2007-05-21 16:51:22Z phw $
+$Id: README.rdoc 145 2007-07-19 13:11:44Z phw $

data/examples/getartist.rb

@@ -3,7 +3,7 @@
 # Example script which queries the database for an
 # artist and displays the artist's data.
 # 
-# $Id: getartist.rb 16 2007-05-23 15:49:06Z phw $
+# $Id: getartist.rb 145 2007-07-19 13:11:44Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -19,7 +19,7 @@ include MusicBrainz
 id = $*[0] ? $*[0] : '10bf95b6-30e3-44f1-817f-45762cdc0de0'
 
 # Generate a new artist MBID object from the ID:
-mbid = Model::MBID.from_uuid(:artist, id)
+mbid = Model::MBID.parse(id, :artist)
 
 # Define what information about the artist
 # should be included in the result.
@@ -32,11 +32,13 @@ artist_includes = Webservice::ArtistIncludes.new(
 )
 
 # Create a new Query object which will provide
-# us an interface to the MusicBrainz webservice.
+# us an interface to the MusicBrainz web service.
 query = Webservice::Query.new
 
 # Now query the MusicBrainz database for the artist
 # with the MBID defined above.
+# We could as well use the ID string directly instead
+# of the MBID object.
 artist = query.get_artist_by_id(mbid, artist_includes)
 
 # Display the fetched artist data together with all
@@ -49,6 +51,6 @@ Disambiguation: #{artist.disambiguation}
 Type          : #{artist.type}
 Begin date    : #{artist.begin_date}
 End date      : #{artist.end_date}
-Aliases       : #{artist.aliases.join('; ')}
+Aliases       : #{artist.aliases.to_a.join('; ')}
 Releases      : #{artist.releases.map{|r| r.title}.uniq.join("\r\n                ")}
 EOF

data/examples/getuser.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+#
+# Example script which queries the database for a
+# User
+# 
+# $Id: getuser.rb 145 2007-07-19 13:11:44Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+print 'Username: ' unless ARGV[0]
+username = ARGV[0] ? ARGV[0] : STDIN.gets.strip
+print 'Password: ' unless ARGV[1]
+password = ARGV[1] ? ARGV[1] : STDIN.gets.strip
+
+ws = Webservice::Webservice.new(:username=>username, :password=>password)
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new(ws)
+
+user = query.get_user_by_name(username)
+puts "Name   : " + user.name
+puts "ShowNag: " + user.show_nag?.to_s
+puts "Types  : " + user.types.join(' ')

data/examples/searchartists.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+#
+# Example script which searches the database for
+# artists and displays the artist's data.
+# 
+# $Id: searchartists.rb 145 2007-07-19 13:11:44Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+# Define the search parameters: Search for artists with the
+# name "Paradise Lost" and return a maximum of 10 artists.
+artist_filter = Webservice::ArtistFilter.new(
+  :name  => 'Paradise Lost',
+  :limit => 10
+)
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new
+
+# Now query the MusicBrainz database for artists
+# with the search parameters defined above.
+artists = query.get_artists(artist_filter)
+
+# Display the fetched artist's names and the score, which
+# indicates how good the artist matches the search parameters.
+artists.each do |entry|
+  print "%s (%i%%)\r\n" % [entry.entity.unique_name, entry.score]
+end

data/lib/rbrainz.rb

@@ -1,11 +1,16 @@
-# $Id: rbrainz.rb 4 2007-05-21 02:04:26Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
-
+# $Id: rbrainz.rb 145 2007-07-19 13:11:44Z phw $
+#
 # This is actually just a convenient shortcut that allows
 # the user to use RBrainz by just using <tt>require 'rbrainz'</tt>.
-# This will include the whole RBrainz webservice library, which 
+# This will include the whole RBrainz web service library, which 
 # should be ok most of the time.
+# 
+# If you want only the models use <tt>require 'rbrainz/model'</tt>.
+# 
+# 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/webservice'
+require 'rbrainz/webservice'
+require 'rbrainz/core_ext'