buntine-discogs 0.3.1

data/README

@@ -0,0 +1,61 @@
+Discogs::Wrapper
+--------------------------
+
+ABOUT
+
+  A 100% Ruby wrapper of the http://www.discogs.com API. No dependencies, no extra gems. :)
+
+  Discogs::Wrapper abstracts all the nasty boilerplate code needed to interact with the Discogs API. It gives you direct access to the information you need.
+
+  Full support for everything in version 1.0 of the API:
+
+    - Artists
+    - Releases
+    - Labels
+    - Searching
+
+  The API is documented here: http://www.discogs.com/help/api
+
+INSTALLATION
+
+  You can install the library via Rubygems:
+
+    $ gem sources -a http://gems.github.com
+    $ sudo gem install buntine-discogs
+
+
+USAGE
+
+  To use this library, you must supply a valid Discogs API key.
+
+    wrapper = Discogs::Wrapper.new("my_api_key")
+
+
+  Accessing information is easy:
+
+    artist = wrapper.get_artist("Master's Hammer")
+    release = wrapper.get_release("611973") # Supply an ID.
+    label = wrapper.get_label("Monitor Records")
+    search_results = wrapper.search("Necrovore")
+
+    artist.name                         # => Master's Hammer
+    artist.releases[0].title            # => Finished
+    artist.releases[1].year             # => 1989
+    artist.releases[4].extraartists     # => [ "Arakain", "Debustrol" ]
+
+    release.title                       # => "Ritual"
+    release.labels[0].name              # => "Osmose Productions"
+    release.formats[0].descriptions[0]  # => "LP"
+    release.styles                      # => [ "Black Metal", "Death Metal" ]
+    release.tracklist[1].title          # => "Pad modly"
+
+    label.images[0].width               # => "220"
+    label.releases.length               # => 22
+    label.releases[3].artist            # => "Root"
+    label.releases[7].catno             # => "MON007"
+
+    search.total_results                # => "124"
+    search.exactresults[0].type         # => "artist"
+    search.exactresults[0].title        # => "Necrovore"
+    search.searchresults[3].title       # => "Necrovore - Demo '87"
+    search.searchresults[3].summary     # => "First and only demo tape"

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake'
+require 'spec'
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+
+task :default => :spec
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ["--colour", "--format progress", "--loadby mtime", "--reverse"]
+  t.spec_files = FileList[ 'spec/**/*_spec.rb' ]
+end
+
+desc "Run all specs and generate RCov report"
+Spec::Rake::SpecTask.new('cov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ["--colour"]
+  t.rcov = true
+  t.rcov_opts = ['-T --no-html --exclude', 'spec\/,gems\/']
+end
+
+spec = eval(File.read("discogs.gemspec"))
+ 
+Rake::GemPackageTask.new(spec) do |pkg|
+  # pkg.need_zip = true
+  # pkg.need_tar = true
+end

data/discogs.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  
+  s.name = "discogs"
+  s.version = "0.3.1"
+  s.date = "2009-07-04"
+  s.summary = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API"
+  s.homepage = "http://www.github.com/buntine/discogs"
+  s.email = "info@andrewbuntine.com"
+  s.authors = ["Andrew Buntine"]
+  
+  s.description = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API"
+  
+  s.files = ["lib/wrapper", "lib/wrapper/resource_mappings.rb", "lib/wrapper/wrapper.rb", "lib/wrapper/resource.rb", "lib/wrapper/resources", "lib/wrapper/resources/format.rb", "lib/wrapper/resources/search.rb", "lib/wrapper/resources/label_release.rb", "lib/wrapper/resources/artist.rb", "lib/wrapper/resources/release_artist.rb", "lib/wrapper/resources/artist_release.rb", "lib/wrapper/resources/release_label.rb", "lib/wrapper/resources/generic_list.rb", "lib/wrapper/resources/search_result.rb", "lib/wrapper/resources/label.rb", "lib/wrapper/resources/image.rb", "lib/wrapper/resources/track.rb", "lib/wrapper/resources/release.rb", "lib/discogs.rb", "Rakefile", "README", "discogs.gemspec"]
+
+  s.test_files = ["spec/wrapper_methods/get_release_spec.rb", "spec/wrapper_methods/search_spec.rb", "spec/wrapper_methods/get_artist_spec.rb", "spec/wrapper_methods/get_label_spec.rb", "spec/resource_spec.rb", "spec/resources/label_spec.rb", "spec/resources/generic_list_spec.rb", "spec/resources/artist_release_spec.rb", "spec/resources/artist_spec.rb", "spec/resources/release_artist_spec.rb", "spec/resources/search_spec.rb", "spec/resources/label_release_spec.rb", "spec/resources/release_label_spec.rb", "spec/resources/release_spec.rb", "spec/resources/search_result_spec.rb", "spec/resources/image_spec.rb", "spec/resources/track_spec.rb", "spec/resources/format_spec.rb", "spec/wrapper_spec.rb", "spec/spec_helper.rb"]
+
+  s.platform = Gem::Platform::RUBY
+
+end

data/lib/discogs.rb

@@ -0,0 +1,10 @@
+
+# Application namespace.
+module Discogs; end
+
+# Custom exceptions.
+class Discogs::InvalidAPIKey < Exception; end
+class Discogs::UnknownResource < Exception; end
+
+# Loading sequence.
+require File.dirname(__FILE__) + "/wrapper/wrapper"

data/lib/wrapper/resource.rb

@@ -0,0 +1,75 @@
+# Represents a generic resource in the Discogs API.
+
+require File.dirname(__FILE__) + "/resource_mappings"
+
+class Discogs::Resource
+
+  include Discogs::ResourceMappings
+
+  def initialize(content)
+    @content = content
+  end
+
+  def original_content
+    @content
+  end
+
+  # Builds the resource with it's content.
+  def build!(remove_resp=true)
+    document = REXML::Document.new(@content, :ignore_whitespace_nodes => :all)
+    root_node = document.root
+
+    # Ignore the <resp> element if necessary.
+    if remove_resp and document.root.expanded_name == "resp"
+      root_node = root_node[0]
+    end
+
+    set_accessors_from_attributes(root_node)
+
+    # Traverse node children.
+    root_node.each_element do |element|
+      name = element.expanded_name.to_sym
+      setter = (name.to_s + "=").to_sym
+
+      singular = find_resource_for_name(name, :singular)
+      plural = singular ? nil : find_resource_for_name(name, :plural)
+
+      if !singular.nil?
+        nested_object = singular.send(:new, element.to_s)
+        self.send(setter, nested_object.build!)
+      elsif !plural.nil?
+        set_accessors_from_attributes(element)
+
+        self.send(setter, [])
+        element.each_element do |sub_element|
+          nested_object = plural.send(:new, sub_element.to_s)
+          self.send(name) << nested_object.build!
+        end
+      elsif self.respond_to? setter
+        self.send(setter, element.text)
+      end
+    end
+ 
+    self
+  end
+
+  def build_with_resp!
+    build!(false)
+  end
+
+ private
+
+  # Sets accessors on _self_ from the attributes of the given element.
+  def set_accessors_from_attributes(element)
+    element.attributes.each_attribute do |attribute|
+      setter = (attribute.expanded_name + "=").to_sym
+
+      if self.respond_to? setter
+        self.send(setter, attribute.value)
+      end
+    end
+  end
+
+end
+
+Dir[File.join(File.dirname(__FILE__), "resources", "*.rb")].each { |file| require file }

data/lib/wrapper/resource_mappings.rb

@@ -0,0 +1,80 @@
+# Abstracts the resource-mapping class methods. 
+
+module Discogs::ResourceMappings
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+
+    # Helper method to map resource to element in API response.
+    def map_to(*elements)
+      self.class_eval <<-EOF
+        def self.element_names
+          #{elements.inspect}
+        end
+      EOF
+    end
+
+    # Helper method to map pluralised resource to element in API response.
+    def map_to_plural(*elements)
+      self.class_eval <<-EOF
+        def self.plural_element_names
+          #{elements.inspect}
+        end
+      EOF
+    end
+
+    # Used by root classes (Discogs::Artist, etc) that should be built internally.
+    def no_mapping
+      self.class_eval <<-EOF
+        def self.element_names; []; end
+        def self.plural_element_names; []; end
+      EOF
+    end
+
+    # Element defaults to prevent excess boilerplate code.
+    def element_names
+      [ self.to_s.split("::")[-1].downcase.to_sym ]
+    end
+    def plural_element_names
+      [ (self.element_names[0].to_s + "s").to_sym ]
+    end
+
+  end
+
+ private
+
+  def find_resource_for_name(name, type=:singular)
+    method = if type == :singular
+      :element_names
+    else
+      :plural_element_names
+    end
+
+    find_resource do |klass|
+      klass.constants.find do |const|
+        if klass.const_get(const).respond_to? method
+          klass.const_get(const).send(method).any? { |element| element.eql?(name) }
+        end
+      end
+    end
+  end
+
+  # Look in _namespace_ for a matching resource class.
+  # First looks in the children of _self_ namespace, and then looks more 
+  # generally. Returns nil if nothing is found.
+  def find_resource(namespace=self.class, &matcher)
+    match = matcher.call(namespace)
+
+    if match
+      match = namespace.const_get(match)
+    elsif namespace == self.class
+      match = find_resource(Discogs, &matcher)
+    end
+
+    return match
+  end
+
+end

data/lib/wrapper/resources/artist.rb

@@ -0,0 +1,16 @@
+# Represents an artist in the Discogs API.
+
+class Discogs::Artist < Discogs::Resource
+
+  no_mapping
+
+  attr_accessor :name,
+                :realname,
+                :images,
+                :urls,
+                :namevariations,
+                :aliases,
+                :members,
+                :releases
+
+end

data/lib/wrapper/resources/artist_release.rb

@@ -0,0 +1,16 @@
+# Represents an artist's release in the Discogs API.
+
+require File.dirname(__FILE__) + "/artist"
+
+class Discogs::Artist::Release < Discogs::Resource
+
+  attr_accessor :id,
+                :status,
+                :type,
+                :title,
+                :format,
+		:year,
+                :label,
+                :trackinfo
+
+end

data/lib/wrapper/resources/format.rb

@@ -0,0 +1,11 @@
+# Represents a release format in the Discogs API.
+
+require File.dirname(__FILE__) + "/release"
+
+class Discogs::Release::Format < Discogs::Resource
+
+  attr_accessor :name,
+                :qty,
+                :descriptions
+
+end

data/lib/wrapper/resources/generic_list.rb

@@ -0,0 +1,29 @@
+# Represents a generic list of items in the Discogs API.
+
+class Discogs::GenericList < Discogs::Resource
+
+  map_to :descriptions, :genres, :aliases, :namevariations, :styles, :urls, :members, :sublabels
+
+  map_to_plural :lists
+
+  # Overload build method to provide custom process for
+  # converting contents into something useful.
+  def build!
+    @items = []
+    document = REXML::Document.new(@content)
+
+    document.root.each_element do |element|
+      @items << element.text
+    end
+
+    @items
+  end
+
+  # Provides post-build access to the list.
+  def [](index)
+    if @items.is_a?(Array)
+      @items[index]
+    end
+  end
+
+end

data/lib/wrapper/resources/image.rb

@@ -0,0 +1,11 @@
+# Represents an image in the Discogs API.
+
+class Discogs::Image < Discogs::Resource
+
+  attr_accessor :uri,
+                :uri150,
+                :width,
+                :height,
+                :type
+
+end

data/lib/wrapper/resources/label.rb

@@ -0,0 +1,16 @@
+# Represents a label in the Discogs API.
+
+class Discogs::Label < Discogs::Resource
+
+  no_mapping
+
+  attr_accessor :name,
+                :contactinfo,
+                :profile,
+                :parentlabel,
+                :images,
+                :urls,
+                :sublabels,
+                :releases
+
+end

data/lib/wrapper/resources/label_release.rb

@@ -0,0 +1,17 @@
+# Represents a labels release in the Discogs API.
+
+require File.dirname(__FILE__) + "/label"
+
+class Discogs::Label::Release < Discogs::Resource
+
+  attr_accessor :id,
+                :status,
+                :type,
+                :catno,
+                :artist,
+                :title,
+                :format,
+                :year,
+                :trackinfo
+
+end

data/lib/wrapper/resources/release.rb

@@ -0,0 +1,22 @@
+# Represents a release in the Discogs API.
+
+class Discogs::Release < Discogs::Resource
+
+  no_mapping
+
+  attr_accessor :id,
+                :status,
+                :title,
+                :country,
+                :released,
+                :notes,
+                :images,
+                :artists,
+                :extraartists,
+                :labels,
+                :formats,
+                :styles,
+                :genres,
+                :tracklist
+
+end

data/lib/wrapper/resources/release_artist.rb

@@ -0,0 +1,18 @@
+# Represents an release's artist in the Discogs API.
+
+require File.dirname(__FILE__) + "/track"
+
+class Discogs::Release::Artist < Discogs::Resource
+
+  map_to_plural :artists, :extraartists
+
+  attr_accessor :name,
+                :role,
+                :join,
+                :anv,
+                :tracks
+
+end
+
+# Define other classes that also replicate this structure.
+class Discogs::Release::Track::Artist < Discogs::Release::Artist; end