bassnode-discogs 0.3.2

data/README.markdown

@@ -0,0 +1,75 @@
+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.
+
+  Full support for everything in version 1.0 of the API:
+
+  * Artists
+  * Releases
+  * Labels
+  * Searching (all of the above)
+
+  Please, [see the Wiki](http://github.com/buntine/discogs/wiki) for helpful documentation.
+
+  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.
+    require 'discogs'
+
+    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.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("bassnode-discogs.gemspec"))
+ 
+Rake::GemPackageTask.new(spec) do |pkg|
+  # pkg.need_zip = true
+  # pkg.need_tar = true
+end

data/bassnode-discogs.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+
+  s.name = "bassnode-discogs"
+  s.version = "0.3.2"
+  s.date = "2011-04-12"
+  s.summary = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API"
+  s.homepage = "http://www.github.com/bassnode/discogs"
+  s.email = "info@andrewbuntine.com"
+  s.authors = ["Andrew Buntine", "Ed Hickey"]
+  s.rubyforge_project = 'bassnode-discogs'
+  s.description = "Discogs::Wrapper is a full wrapper for the http://www.discogs.com API"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
+
+  s.platform = Gem::Platform::RUBY
+
+end

data/lib/discogs.rb

@@ -0,0 +1,21 @@
+
+## 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::InvalidAPIKey < Exception; end
+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

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

data/lib/wrapper/resources/release_label.rb

@@ -0,0 +1,10 @@
+# Represents a Releases Label in the Discogs API.
+
+require File.dirname(__FILE__) + "/release"
+
+class Discogs::Release::Label < Discogs::Resource
+
+  attr_accessor :catno,
+                :name
+
+end

data/lib/wrapper/resources/search.rb

@@ -0,0 +1,61 @@
+# Represents a search resultset in the Discogs API.
+
+class Discogs::Search < Discogs::Resource
+
+  no_mapping
+
+  attr_accessor :exactresults,
+                :searchresults,
+                :start,
+                :end,
+                :numResults
+
+  def total_results
+    self.numResults.to_i
+  end
+
+  def current_page
+    (start.to_i / page_size) + 1
+  end
+
+  def total_pages
+    (total_results.to_f / page_size).ceil
+  end
+
+  def last_page?
+    current_page == total_pages
+  end
+
+  def exact(filter=nil)
+    filter_results(filter, self.exactresults)
+  end
+
+  def results(filter=nil)
+    filter_results(filter, self.searchresults)
+  end
+
+  # Returns the closest exact result for _filter_, or nil.
+  def closest(filter)
+    exact(filter)[0] rescue nil
+  end
+
+ private
+
+  # An easy way for filtering a particular "type" of result (Artist, Release, etc)
+  def filter_results(filter, results)
+    results ||= []
+
+    if filter.nil?
+      results
+    else
+      results.find_all do |result|
+        result.type == filter.to_s
+      end
+    end
+  end
+
+  def page_size
+    self.end.to_i - (self.start.to_i - 1)
+  end
+
+end

data/lib/wrapper/resources/search_result.rb

@@ -0,0 +1,16 @@
+# Represents a single search result in the Discogs API.
+
+require File.dirname(__FILE__) + "/search"
+
+class Discogs::Search::Result < Discogs::Resource
+
+  map_to_plural :exactresults, :searchresults
+
+  attr_accessor :num,
+                :type,
+                :title,
+                :uri,
+                :anv,
+                :summary
+
+end

data/lib/wrapper/resources/track.rb

@@ -0,0 +1,15 @@
+# Represents a track in the Discogs API.
+
+require File.dirname(__FILE__) + "/release"
+
+class Discogs::Release::Track < Discogs::Resource
+
+  map_to_plural :tracklist
+
+  attr_accessor :position,
+                :title,
+                :duration,
+                :artists,
+                :extraartists
+
+end