metal_archives 2.1.1 → 3.1.0

data/lib/metal_archives/models/base.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module MetalArchives
+  ##
+  # Abstract model class
+  #
+  class Base
+    ##
+    # Generic shallow copy constructor
+    #
+    def initialize(attributes = {})
+      raise Errors::NotImplementedError, "no :id property in model" unless respond_to? :id
+
+      set(**attributes)
+    end
+
+    ##
+    # Set properties
+    #
+    def set(**attributes)
+      attributes.each { |key, value| instance_variable_set(:"@#{key}", value) }
+    end
+
+    ##
+    # Returns true if two objects have the same type and id
+    #
+    def ==(other)
+      other.is_a?(self.class) &&
+        id == other.id
+    end
+
+    ##
+    # Fetch, parse and load the data
+    #
+    # [Raises]
+    # - rdoc-ref:Errors::InvalidIDError when no id
+    # - rdoc-ref:Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    def load!
+      raise Errors::InvalidIDError, "no id present" unless id
+
+      # Use constructor to set attributes
+      set(**assemble)
+
+      @loaded = true
+      MetalArchives.cache[id] = self
+    rescue StandardError => e
+      # Don't cache invalid requests
+      MetalArchives.cache.delete id
+      raise e
+    end
+
+    ##
+    # Whether or not the object is currently loaded
+    #
+    def loaded?
+      @loaded ||= false
+    end
+
+    ##
+    # Whether or not the object is currently cached
+    #
+    def cached?
+      loaded? && MetalArchives.cache.include?(id)
+    end
+
+    ##
+    # String representation
+    #
+    def inspect
+      "#<#{self.class.name} @id=#{@id} @name=\"#{@name}\">"
+    end
+
+    protected
+
+    ##
+    # Fetch the data and assemble the model
+    #
+    # Override this method
+    #
+    # [Raises]
+    # - rdoc-ref:Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    def assemble
+      raise Errors::NotImplementedError, "method :assemble not implemented"
+    end
+
+    class << self
+      ##
+      # Declared properties
+      #
+      def properties
+        @properties ||= {}
+      end
+
+      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] = opts
+
+        # property
+        define_method(name) do
+          # Load only when not loaded or id property
+          load! unless loaded? || name == :id
+
+          instance_variable_get(:"@#{name}")
+        end
+
+        # property?
+        define_method("#{name}?") do
+          send(name).present?
+        end
+
+        # property=
+        define_method("#{name}=") do |value|
+          return instance_variable_set(:"@#{name}", value) if value.nil?
+
+          # Check value type
+          type = opts[:type] || String
+          if opts[:multiple]
+            raise Errors::TypeError, "invalid type #{value.class}, must be Array for #{name}" unless value.is_a? Array
+
+            value.each do |val|
+              raise Errors::TypeError, "invalid type #{val.class}, must be #{type} for #{name}" unless val.is_a? type
+            end
+          else
+            raise 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 && opts[:values]
+
+        properties[name] = opts
+
+        # property
+        define_method(name) do
+          load! unless loaded?
+
+          instance_variable_get(:"@#{name}")
+        end
+
+        # property?
+        define_method("#{name}?") do
+          load! unless loaded? && instance_variable_defined?("@#{name}")
+
+          property = instance_variable_get(:"@#{name}")
+          property.respond_to?(:empty?) ? !property.empty? : !property.nil?
+        end
+
+        # property=
+        define_method("#{name}=") do |value|
+          # Check enum type
+          if opts[:multiple]
+            raise Errors::TypeError, "invalid enum value #{value}, must be Array for #{name}" unless value.is_a? Array
+
+            value.each do |val|
+              raise Errors::TypeError, "invalid enum value #{val} for #{name}" unless opts[:values].include? val
+            end
+          else
+            raise 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 <tt>enum name, :values => [true, false]</tt>
+      #
+      # [+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

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'countries'
+require "date"
+require "countries"
 
 module MetalArchives
   ##
   # Represents a record label
   #
-  class Label < MetalArchives::BaseModel
+  class Label < Base
     ##
     # :attr_reader: id
     #
     # Returns +Integer+
     #
-    property :id, :type => Integer
+    property :id, type: Integer
 
     ##
     # :attr_reader: name
@@ -46,7 +46,7 @@ module MetalArchives
     # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
     # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
     #
-    property :country, :type => ISO3166::Country
+    property :country, type: ISO3166::Country
 
     ##
     # :attr_reader: phone
@@ -68,25 +68,25 @@ module MetalArchives
     # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
     # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
     #
-    property :specializations, :multiple => true
+    property :specializations, multiple: true
 
     ##
     # :attr_reader: date_founded
     #
-    # Returns +NilDate+
+    # Returns +Date+
     #
     # [Raises]
     # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
     # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
     #
-    property :date_founded, :type => NilDate
+    property :date_founded, type: Date
 
     ##
     # :attr_reader: sub_labels
     #
     # Returns +Array+ of rdoc-ref:Label
     #
-    property :sub_labels, :type => MetalArchives::Label, :multiple => true
+    property :sub_labels, type: Label, multiple: true
 
     ##
     # :attr_reader: online_shopping
@@ -100,14 +100,14 @@ module MetalArchives
     #
     # Returns +Hash+ with the following keys: +title+, +content+
     #
-    property :contact, :type => Hash, :multiple => true
+    property :contact, type: Hash, multiple: true
 
     ##
     # :attr_reader: status
     #
     # Returns +:active+, +:closed+ or +:unknown+
     #
-    enum :status, :values => %i[active closed unknown]
+    enum :status, values: [:active, :closed, :unknown]
 
     class << self
       ##
@@ -116,8 +116,7 @@ module MetalArchives
       # Returns +Array+ of rdoc-ref:Label
       #
       def search(_name)
-        results = []
-        results
+        []
       end
 
       ##
@@ -128,8 +127,8 @@ module MetalArchives
       def find_by_name(name, id)
         client.find_resource(
           :band,
-          :name => name,
-          :id => id
+          name: name,
+          id: id,
         )
       end
     end

data/lib/metal_archives/models/release.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "date"
+require "nokogiri"
+
+module MetalArchives
+  ##
+  # Represents a release
+  #
+  class Release < Base
+    ##
+    # :attr_reader: id
+    #
+    # Returns +Integer+
+    #
+    property :id, type: Integer
+
+    ##
+    # :attr_reader: title
+    #
+    # Returns +String+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :title
+
+    # TODO: band
+
+    ##
+    # :attr_reader: type
+    #
+    # Returns +:full_length+, +:live+, +:demo+, +:single+, +:ep+, +:video+, +:boxed_set+, +:split+, +:compilation+, +:split_video+, +:collaboration+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    enum :type, values: [:full_length, :live, :demo, :single, :ep, :video, :boxed_set, :split, :compilation, :split_video, :collaboration]
+
+    ##
+    # :attr_reader: date_released
+    #
+    # Returns rdoc-ref:Date
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :date_released, type: Date
+
+    ##
+    # :attr_reader_: catalog_id
+    #
+    # Return +String+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :catalog_id
+
+    ##
+    # :attr_reader_: version_description
+    #
+    # Return +String+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :version_description
+
+    # TODO: label
+
+    ##
+    # :attr_reader: format
+    #
+    # Returns +:cd+, +:cassette+, +:vinyl+, +:vhs+, +:dvd+, +:digital+, +:blu_ray+, +:other+, +:unknown+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :format
+
+    ##
+    # :attr_reader: limitation
+    #
+    # Returns +Integer+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :limitation
+
+    # TODO: reviews
+    # TODO: songs
+    # TODO: lineup
+    # TODO: other versions
+    # TODO: links
+
+    ##
+    # :attr_reader: notes
+    #
+    # Returns raw HTML +String+
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    property :notes
+
+    protected
+
+    ##
+    # Fetch the data and assemble the model
+    #
+    # [Raises]
+    # - rdoc-ref:MetalArchives::Errors::InvalidIDError when receiving a status code == 404
+    # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+    #
+    def assemble # :nodoc:
+      ## Base attributes
+      response = MetalArchives.http.get "/albums/view/id/#{id}"
+
+      Parsers::Release.parse_html response.to_s
+    end
+
+    class << self
+      ##
+      # Find by ID
+      #
+      # Returns rdoc-ref:Release, even when ID is invalid (because the data is lazily fetched)
+      #
+      # [+id+]
+      #     +Integer+
+      #
+      def find(id)
+        return MetalArchives.cache[id] if MetalArchives.cache.include? id
+
+        Release.new id: id
+      end
+
+      ##
+      # Find by ID (no lazy loading)
+      #
+      # Returns rdoc-ref:Release
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::InvalidIDError when no or invalid id
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400 (except 404)
+      # - rdoc-ref:MetalArchives::Errors::ParserError when parsing failed. Please report this error.
+      #
+      # [+id+]
+      #     +Integer+
+      #
+      def find!(id)
+        obj = find id
+        obj.load! if obj && !obj.loaded?
+
+        obj
+      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:Release or nil when no results
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400
+      # - rdoc-ref:MetalArchives::Errors::ParserError when parsing failed. Please report this error.
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:band_name+: +String+
+      #     - +:title+: +String+
+      #     - +:from_year+: +Integer+
+      #     - +:from_month+: +Integer+
+      #     - +:to_year+: +Integer+
+      #     - +:to_month+: +Integer+
+      #     - +:country+: +ISO3166::Country+ or +Array+ of ISO3166::Country
+      #     - +:location+: +String+
+      #     - +:label_name+: +String+
+      #     - +:indie+: +Boolean+
+      #     - +:catalog_id+: +String+
+      #     - +:identifier+: +String+, identifier (barcode, matrix, etc.)
+      #     - +:recording_info+: +String+, recording information (studio, city, etc.)
+      #     - +:version_description+: +String+, version description (country, digipak, etc.)
+      #     - +:notes+: +String+
+      #     - +:genre+: +String+
+      #     - +:types+: +Array+ of +Symbol+, see rdoc-ref:Release.type
+      #     - +:formats+: +Array+ of +Symbol+, see rdoc-ref:Release.format
+      #
+      def find_by(query)
+        params = Parsers::Release.map_params query
+
+        response = MetalArchives.http.get "/search/ajax-advanced/searching/albums", params
+        json = JSON.parse response.to_s
+
+        return nil if json["aaData"].empty?
+
+        data = json["aaData"].first
+        id = Nokogiri::HTML(data[1]).xpath("//a/@href").first.value.delete('\\').split("/").last.gsub(/\D/, "").to_i
+
+        find id
+      end
+
+      ##
+      # Find by attributes (no lazy loading)
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns rdoc-ref:Release or nil when no results
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400
+      # - rdoc-ref:MetalArchives::Errors::ParserError when parsing failed. Please report this error.
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:band_name+: +String+
+      #     - +:title+: +String+
+      #     - +:from_year+: +Integer+
+      #     - +:from_month+: +Integer+
+      #     - +:to_year+: +Integer+
+      #     - +:to_month+: +Integer+
+      #     - +:country+: +ISO3166::Country+ or +Array+ of ISO3166::Country
+      #     - +:location+: +String+
+      #     - +:label_name+: +String+
+      #     - +:indie+: +Boolean+
+      #     - +:catalog_id+: +String+
+      #     - +:identifier+: +String+, identifier (barcode, matrix, etc.)
+      #     - +:recording_info+: +String+, recording information (studio, city, etc.)
+      #     - +:version_description+: +String+, version description (country, digipak, etc.)
+      #     - +:notes+: +String+
+      #     - +:genre+: +String+
+      #     - +:types+: +Array+ of +Symbol+, see rdoc-ref:Release.type
+      #     - +:formats+: +Array+ of +Symbol+, see rdoc-ref:Release.format
+      #
+      def find_by!(query)
+        obj = find_by query
+        obj.load! if obj && !obj.loaded?
+
+        obj
+      end
+
+      ##
+      # Search by attributes
+      #
+      # Refer to {MA's FAQ}[http://www.metal-archives.com/content/help?index=3#tab_db] for search tips.
+      #
+      # Returns rdoc-ref:Collection of rdoc-ref:Release
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400
+      # - rdoc-ref:MetalArchives::Errors::ParserError when parsing failed. Please report this error.
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:band_name+: +String+
+      #     - +:title+: +String+
+      #     - +:from_year+: +Integer+
+      #     - +:from_month+: +Integer+
+      #     - +:to_year+: +Integer+
+      #     - +:to_month+: +Integer+
+      #     - +:country+: +ISO3166::Country+ or +Array+ of ISO3166::Country
+      #     - +:location+: +String+
+      #     - +:label_name+: +String+
+      #     - +:indie+: +Boolean+
+      #     - +:catalog_id+: +String+
+      #     - +:identifier+: +String+, identifier (barcode, matrix, etc.)
+      #     - +:recording_info+: +String+, recording information (studio, city, etc.)
+      #     - +:version_description+: +String+, version description (country, digipak, etc.)
+      #     - +:notes+: +String+
+      #     - +:genre+: +String+
+      #     - +:types+: +Array+ of +Symbol+, see rdoc-ref:Release.type
+      #     - +:formats+: +Array+ of +Symbol+, see rdoc-ref:Release.format
+      #
+      def search_by(query)
+        params = Parsers::Release.map_params query
+
+        l = lambda do
+          @start ||= 0
+
+          if @max_items && @start >= @max_items
+            []
+          else
+            response = MetalArchives.http.get "/search/ajax-advanced/searching/albums", params.merge(iDisplayStart: @start)
+            json = JSON.parse response.to_s
+
+            @max_items = json["iTotalRecords"]
+
+            objects = []
+
+            json["aaData"].each do |data|
+              # Create Release object for every ID in the results list
+              id = Nokogiri::HTML(data.first).xpath("//a/@href").first.value.delete('\\').split("/").last.gsub(/\D/, "").to_i
+              objects << Release.find(id)
+            end
+
+            @start += 200
+
+            objects
+          end
+        end
+
+        MetalArchives::Collection.new l
+      end
+
+      ##
+      # Search by title, resolves to rdoc-ref:Release.search_by <tt>(:title => title)</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:Release
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400
+      # - rdoc-ref:MetalArchives::Errors::ArgumentError when +title+ isn't a +String+
+      #
+      # [+title+]
+      #     +String+
+      #
+      def search(title)
+        raise MetalArchives::Errors::ArgumentError unless title.is_a? String
+
+        search_by title: title
+      end
+
+      ##
+      # Get all releases
+      #
+      # Returns rdoc-ref:Collection of rdoc-ref:Release
+      #
+      # [Raises]
+      # - rdoc-ref:MetalArchives::Errors::APIError when receiving a status code >= 400
+      # - rdoc-ref:MetalArchives::Errors::ParserError when parsing failed. Please report this error.
+      #
+      def all
+        search ""
+      end
+    end
+  end
+end