discogs-wrapper 1.0.0

data/README.markdown

@@ -0,0 +1,81 @@
+Discogs::Wrapper
+================
+
+ABOUT
+-----
+  A 100% Ruby wrapper of the 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.
+
+  The master branch aims to give full support for version 2.0 of the API. If you need support for everything in version 1.0, see the api-v1 branch.
+
+  Specifically:
+
+  * Artists
+  * Releases
+  * Labels
+  * Searching (all of the above)
+
+  Please, [see the Wiki](http://github.com/buntine/discogs/wiki) for helpful documentation.
+
+  The Discogs 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 User-agent value. For example:
+
+    require 'discogs'
+    wrapper = Discogs::Wrapper.new("Mozilla/5.0 (X11; Linux i686; rv:6.0.2) Gecko/20100101 Firefox/6.0.2")
+
+  I suggest passing on your users User-agent.
+
+  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.total_pages                  # => 7
+    search.current_page                 # => 1
+
+    # Exact results
+    search.exact[0].type                # => "artist"
+    search.exact[0].title               # => "Necrovore"
+    search.exact(:label)[0].title       # => "Necrovores Records"
+    search.closest(:artist)             # => <Discogs::Search::Result:0x324ad3e2>
+
+    # All results
+    search.results[3].title             # => "Necrovore - Demo '87"
+    search.results[3].summary           # => "First and only demo tape"
+    search.results(:release)[0]         # => <Discogs::Search::Result:0x343de34a>
+
+
+LICENSE
+-------
+
+<a rel="license" href="http://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/3.0/80x15.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">Discogs::Wrapper</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/buntine/discogs" property="cc:attributionName" rel="cc:attributionURL">Andrew Buntine</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="http://www.discogs.com/help/api" rel="dct:source">www.discogs.com</a>.

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-wrapper"
+  s.version = "1.0.0"
+  s.date = "2011-09-27"
+  s.summary = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API V2"
+  s.homepage = "http://www.github.com/buntine/discogs"
+  s.email = "info@andrewbuntine.com"
+  s.authors = ["Andrew Buntine", "Ed Hickey"]
+  
+  s.description = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API V2"
+  
+  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.markdown", "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,20 @@
+
+## Discogs::Wrapper
+##   by Andrew Buntine, 2009
+##   
+##   This library provides full access to the Discogs.com API v1.0
+##
+##   Please file all bug reports at http://www.github.com/buntine/discogs, or
+##   email me at info@andrewbuntine.com.
+##
+##   Enjoy!
+
+# Application namespace.
+module Discogs; end
+
+# Custom exceptions.
+class Discogs::UnknownResource < Exception; end
+class Discogs::InternalServerError < Exception; end
+
+# Loading sequence.
+require File.dirname(__FILE__) + "/wrapper/wrapper"

data/lib/wrapper/resource.rb

@@ -0,0 +1,79 @@
+# 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)
+
+      # Create an instance of the named resource and build it.
+      if !singular.nil?
+        nested_object = singular.send(:new, element.to_s)
+        self.send(setter, nested_object.build!)
+
+      # Setup an array and build each child.
+      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,84 @@
+# Abstracts the resource-mapping class methods. 
+#
+# Each "resource" in the wrapper maps to one or more elements 
+# in the API response. This way they can be recursively built
+# without having to manually specify it in each class.
+
+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,37 @@
+# Represents an artist in the Discogs API.
+
+class Discogs::Artist < Discogs::Resource
+
+  no_mapping
+
+  attr_accessor :name,
+                :realname,
+                :images,
+                :urls,
+                :namevariations,
+                :aliases,
+                :members,
+                :releases
+
+  def main_releases
+    filter_releases("Main")
+  end
+
+  def bootlegs
+    filter_releases("UnofficialRelease")
+  end
+
+  def appearances
+    filter_releases("Appearance")
+  end
+
+ private
+
+  # Simple helper for filtering a particular type of release.
+  def filter_releases(type)
+    self.releases.find_all do |release|
+      release.type == type
+    end
+  end
+
+end

data/lib/wrapper/resources/artist_release.rb

@@ -0,0 +1,17 @@
+# 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,
+                :artist,
+                :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