metal_archives 0.2.0

data/lib/metal_archives/models/band.rb

@@ -0,0 +1,291 @@
+require 'date'
+require 'countries'
+
+module MetalArchives
+
+  ##
+  # Represents an band (person or group)
+  #
+  class Band < BaseModel
+    ##
+    # :attr_reader: id
+    #
+    # Returns +Integer+
+    #
+    property :id, :type => Integer
+
+    ##
+    # :attr_reader: name
+    #
+    # Returns +String+
+    #
+    property :name
+
+    ##
+    # :attr_reader: aliases
+    #
+    # Returns +Array+ of +String+
+    #
+    property :aliases, :multiple => true
+
+    ##
+    # :attr_reader: country
+    #
+    # Returns +ISO3166::Country+
+    #
+    property :country, :type => ISO3166::Country
+
+    ##
+    # :attr_reader: location
+    #
+    # Returns +String+
+    #
+    property :location
+
+    ##
+    # :attr_reader: date_formed
+    #
+    # Returns +Date+
+    #
+    property :date_formed, :type => Date
+
+    ##
+    # :attr_reader: date_active
+    #
+    # Returns +Array+ of rdoc-ref:Range
+    #
+    property :date_active, :type => MetalArchives::Range, :multiple => true
+
+    ##
+    # :attr_reader: genres
+    #
+    # Returns +Array+ of +String+
+    #
+    property :genres, :multiple => true
+
+    ##
+    # :attr_reader: lyrical_themes
+    #
+    # Returns +Array+ of +String+
+    #
+    property :lyrical_themes, :multiple => true
+
+    ##
+    # :attr_reader: label
+    #
+    # Returns rdoc-ref:Label
+    #
+    property :label, :type => MetalArchives::Label
+
+    ##
+    # :attr_reader: independent
+    #
+    # Returns boolean
+    #
+    enum :independent, :values => [true, false]
+
+    ##
+    # :attr_reader: comment
+    #
+    # Returns raw HTML +String+
+    #
+    property :comment
+
+    ##
+    # :attr_reader: status
+    #
+    # Returns +:active+, +:split_up+, +:on_hold+, +:unknown+, +:changed_name+ or +:disputed+
+    #
+    enum :status, :values => [:active, :split_up, :on_hold, :unknown, :changed_name, :disputed]
+
+    # TODO: releases
+    # TODO: members
+
+    ##
+    # :attr_reader: similar
+    #
+    # Returns +Array+ of +Hash+ containing the following keys
+    #
+    # [+similar+]
+    #     - +:band+: rdoc-ref:Band
+    #     - +:score+: +Integer+
+    #
+    property :similar, :type => Hash, :multiple => true
+
+    ##
+    # :attr_reader: logo
+    #
+    # Returns +String+
+    #
+    property :logo
+
+    ##
+    # :attr_reader: photo
+    #
+    # Returns +String+
+    #
+    property :photo
+
+    ##
+    # :attr_reader: links
+    #
+    # Returns +Array+ of +Hash+ containing the following keys
+    #
+    # [+similar+]
+    #     - +:url+: +String+
+    #     - +:type+: +Symbol+, either +:official+ or +:merchandise+
+    #     - +:title+: +String+
+    #
+    property :links, :multiple => true
+
+    protected
+      ##
+      # Fetch the data and assemble the model
+      #
+      # Raises rdoc-ref:MetalArchives::Errors::APIError
+      #
+      def assemble # :nodoc:
+        ## Base attributes
+        url = "http://www.metal-archives.com/band/view/id/#{id}"
+        response = HTTPClient.get url
+
+        properties = Parsers::Band.parse_html response.body
+
+        ## Comment
+        url = "http://www.metal-archives.com/band/read-more/id/#{id}"
+        response = HTTPClient.get url
+
+        properties[:comment] = response.body
+
+        ## Similar artists
+        url = "http://www.metal-archives.com/band/ajax-recommendations/id/#{id}"
+        response = HTTPClient.get url
+
+        properties[:similar] = Parsers::Band.parse_similar_bands_html response.body
+
+        ## Related links
+        url = "http://www.metal-archives.com/link/ajax-list/type/band/id/#{id}"
+        response = HTTPClient.get url
+
+        properties[:links] = Parsers::Band.parse_related_links_html response.body
+
+        ## Use constructor to fill properties
+        initialize properties
+      end
+
+    class << self
+      ##
+      # Find by ID
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns rdoc-ref:Band, even when ID is invalid (because the data is lazily fetched)
+      #
+      # [+id+]
+      #     +Integer+
+      #
+      def find(id)
+        Band.new :id => id
+      end
+
+      ##
+      # Find by attributes
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns rdoc-ref:Band or nil when ID is invalid
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:name+: +String+
+      #     - +:exact+: +Boolean+
+      #     - +:genre+: +String+
+      #     - +:country+: +ISO366::Country+
+      #     - +:year_formation+: rdoc-ref:Range of +Date+
+      #     - +:comment+: +String+
+      #     - +:status+: see rdoc-ref:Band.status
+      #     - +:lyrical_themes+: +String+
+      #     - +:location+: +String+
+      #     - +:label+: rdoc-ref:Label
+      #     - +:independent+: boolean
+      #
+      def find_by(query)
+        url = 'http://www.metal-archives.com/search/ajax-advanced/searching/bands/'
+        params = Parsers::Band.map_params query
+
+        response = HTTPClient.get url, params
+        json = JSON.parse response.body
+
+        return nil if json['aaData'].empty?
+
+        data = json['aaData'].first
+        id = Nokogiri::HTML(data.first).xpath('//a/@href').first.value.gsub('\\', '').split('/').last.gsub(/\D/, '').to_i
+
+        Band.new :id => id
+      rescue Errors::APIError
+        nil
+      end
+
+      ##
+      # Search by attributes
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns (possibly empty) +Array+ of rdoc-ref:Band
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:name+: +String+
+      #     - +:exact+: +Boolean+
+      #     - +:genre+: +String+
+      #     - +:country+: +ISO366::Country+
+      #     - +:year_formation+: rdoc-ref:Range of +Date+
+      #     - +:comment+: +String+
+      #     - +:status+: see rdoc-ref:Band.status
+      #     - +:lyrical_themes+: +String+
+      #     - +:location+: +String+
+      #     - +:label+: rdoc-ref:Label
+      #     - +:independent+: boolean
+      #
+      def search_by(query)
+        objects = []
+
+        url = 'http://www.metal-archives.com/search/ajax-advanced/searching/bands/'
+        query[:iDisplayStart] = 0
+
+        loop do
+          params = Parsers::Band.map_params query
+
+          response = HTTPClient.get url, params
+          json = JSON.parse response.body
+
+          json['aaData'].each do |data|
+            # Create Band object for every ID in the results list
+            id = Nokogiri::HTML(data.first).xpath('//a/@href').first.value.gsub('\\', '').split('/').last.gsub(/\D/, '').to_i
+            objects << Band.new(:id => id)
+          end
+
+          break if objects.length == json['iTotalRecords']
+
+          query[:iDisplayStart] += 200
+        end
+
+        objects
+      end
+
+      ##
+      # Search by name, resolves to rdoc-ref:Band.search_by <tt>(:name => name)</tt>
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns (possibly empty) +Array+ of rdoc-ref:Band
+      #
+      # [+name+]
+      #     +String+
+      #
+      def search(name)
+        search_by :name => name
+      end
+    end
+  end
+end

data/lib/metal_archives/models/base_model.rb

@@ -0,0 +1,153 @@
+module MetalArchives
+  ##
+  # Base model class all models are derived from
+  #
+  class BaseModel # :nodoc:
+    ##
+    # Generic shallow copy constructor
+    #
+    def initialize(hash = {})
+      raise Errors::NotImplementedError, 'no :id property in model' unless self.respond_to? :id?, true
+
+      hash.each do |property, value|
+        instance_variable_set("@#{property}", value) if self.class.properties.include? property
+      end
+    end
+
+    protected
+      ##
+      # Eagerly fetch the data
+      #
+      # Raises rdoc-ref:MetalArchives::Errors::APIError
+      #
+      def fetch
+        raise Errors::DataError, 'no id present' unless !!id
+
+        raise Errors::NotImplementedError, 'no :assemble method in model' unless self.respond_to? :assemble, true
+
+        assemble
+      end
+
+    class << self
+      ##
+      # +Array+ of declared properties
+      #
+      attr_accessor :properties
+
+      protected
+        ##
+        # Defines a model property.
+        #
+        # [+name+]
+        #     Name of the property
+        #
+        # [+opts+]
+        #   [+type+]
+        #       Data type of property (a constant)
+        #
+        #       Default: +String+
+        #
+        #   [+multiple+]
+        #       Whether or not the property has multiple values (which
+        #       turns it into an +Array+ of +type+)
+        #
+        def property(name, opts = {})
+          (@properties ||= []) << name
+
+          # property
+          define_method(name) do
+            self.fetch unless instance_variable_defined?("@#{name}") or name == :id
+            instance_variable_get("@#{name}")
+          end
+
+          # property?
+          define_method("#{name}?") do
+            self.fetch unless instance_variable_defined?("@#{name}") or name == :id
+
+            property = instance_variable_get("@#{name}")
+            property.respond_to?(:empty?) ? !property.empty? : !!property
+          end
+
+          # property=
+          define_method("#{name}=") do
+            # Check value type
+            type = opts[:type] || String
+            if opts[:multiple]
+              raise MetalArchives::Errors::TypeError, "invalid type #{value.class}, must be Array for #{name}" unless value.is_a? Array
+              value.each do |val|
+                raise MetalArchives::Errors::TypeError, "invalid type #{val.class}, must be #{type} for #{name}" unless val.is_a? type
+              end
+            else
+              raise MetalArchives::Errors::TypeError, "invalid type #{value.class}, must be #{type} for #{name}" unless value.is_a? type
+            end
+
+            instance_variable_set name, value
+          end
+        end
+
+        ##
+        # Defines a model enum property.
+        #
+        # [+name+]
+        #     Name of the property
+        #
+        # [+opts+]
+        #   [+values+]
+        #       Required. An array of possible values
+        #
+        #   [+multiple+]
+        #       Whether or not the property has multiple values (which
+        #       turns it into an +Array+ of +type+)
+        #
+        def enum(name, opts)
+          raise ArgumentError, 'opts[:values] is required' unless opts and opts[:values]
+
+          (@properties ||= []) << name
+
+          # property
+          define_method(name) do
+            self.fetch unless instance_variable_defined?("@#{name}")
+            instance_variable_get("@#{name}")
+          end
+
+          # property?
+          define_method("#{name}?") do
+            self.fetch unless instance_variable_defined?("@#{name}")
+
+            property = instance_variable_get("@#{name}")
+            property.respond_to?(:empty?) ? !property.empty? : !!property
+          end
+
+          # property=
+          define_method("#{name}=") do |value|
+            # Check enum type
+            if opts[:multiple]
+              raise MetalArchives::Errors::TypeError, "invalid enum value #{value}, must be Array for #{name}" unless value.is_a? Array
+              value.each do |val|
+                raise MetalArchives::Errors::TypeError, "invalid enum value #{val} for #{name}" unless opts[:values].include? val
+              end
+            else
+              raise MetalArchives::Errors::TypeError, "invalid enum value #{value} for #{name}" unless opts[:values].include? value
+            end
+
+            instance_variable_set name, value
+          end
+        end
+
+        ##
+        # Defines a model boolean property. This method is an alias for +enum name, :values => [true, false]+
+        #
+        # [+name+]
+        #     Name of the property
+        #
+        # [+opts+]
+        #   [+multiple+]
+        #       Whether or not the property has multiple values (which
+        #       turns it into an +Array+ of +type+)
+        #
+        def boolean(name, opts = {})
+          enum name, opts.merge(:values => [true, false])
+        end
+    end
+  end
+end

data/lib/metal_archives/models/label.rb

@@ -0,0 +1,112 @@
+require 'date'
+require 'countries'
+
+module MetalArchives
+
+  ##
+  # Represents a record label
+  #
+  class Label < BaseModel
+    ##
+    # :attr_reader: id
+    #
+    # Returns +Integer+
+    #
+    property :id
+
+    ##
+    # :attr_reader: name
+    #
+    # Returns +String+
+    #
+    property :name
+
+    ##
+    # :attr_reader: address
+    #
+    # Returns multiline +String+
+    #
+    property :address
+
+    ##
+    # :attr_reader: country
+    #
+    # Returns +ISO316::Country+
+    #
+    property :country, :type => ISO3166::Country
+
+    ##
+    # :attr_reader: phone
+    #
+    # Returns +String+
+    #
+    property :phone
+
+    ##
+    # :attr_reader: specializations
+    #
+    # Returns +Array+ of +String+
+    #
+    property :specializations, :multiple => true
+
+    ##
+    # :attr_reader: date_founded
+    #
+    # Returns +Date+
+    #
+    property :date_founded, :type => Date
+
+    ##
+    # :attr_reader: sub_labels
+    #
+    # Returns +Array+ of rdoc-ref:Label
+    #
+    property :sub_labels, :type => MetalArchives::Label, :multiple => true
+
+    ##
+    # :attr_reader: online_shopping
+    #
+    # Returns +Boolean+
+    #
+    boolean :online_shopping
+
+    ##
+    # :attr_reader: contact
+    #
+    # Returns +Hash+ with the following keys: +title+, +content+
+    #
+    property :contact, :type => Hash, :multiple => true
+
+    ##
+    # :attr_reader: status
+    #
+    # Returns +:active+, +:closed+ or +:unknown+
+    #
+    enum :status, :values => [:active, :closed, :unknown]
+
+    class << self
+      ##
+      # Search by name.
+      #
+      # Returns +Array+ of rdoc-ref:Label
+      #
+      def search(name)
+        results = []
+        results
+      end
+
+      ##
+      # Find by name and id.
+      #
+      # Returns rdoc-ref:Band
+      #
+      def find_by_name(name, id)
+        client.find_resource(
+            :band,
+              :name => name,
+              :id => id
+        )
+      end
+    end
+  end
+end