greeve 0.0.1

data/lib/greeve.rb

@@ -0,0 +1,29 @@
+require "bigdecimal"
+require "ox"
+require "typhoeus"
+
+require_relative "greeve/version"
+
+require_relative "greeve/base_item"
+require_relative "greeve/row"
+require_relative "greeve/rowset"
+require_relative "greeve/eve/character_info"
+
+# A Ruby wrapper for the EVE Online XML API.
+module Greeve
+  # Base URL of the EVE XML API.
+  EVE_API_BASE_URL = "https://api.eveonline.com".freeze
+
+  # API resources.
+  module API; end
+  # Character resources.
+  module Character; end
+  # Corporation resources.
+  module Corporation; end
+  # Eve resources.
+  module Eve; end
+  # Map resources.
+  module Map; end
+  # Server resources.
+  module Server; end
+end

data/lib/greeve/base_item.rb

@@ -0,0 +1,237 @@
+require "bigdecimal"
+require "time"
+
+require_relative "rowset"
+
+module Greeve
+  # An abstract class used to map XML responses from the EVE XML API into Ruby
+  # objects. This class is designed to be subclassed by classes representing
+  # the specific EVE API resources.
+  class BaseItem
+    # A DSL method to map an XML attribute to a Ruby object.
+    #
+    # @param name [Symbol] the Ruby name for this attribute
+    #
+    # @option opts [Symbol] :xpath the xpath string used to locate the attribute
+    #   in the XML element
+    # @option opts [:integer, :numeric, :string] :type method used to coerce the
+    #   XML value
+    #
+    # @example
+    #   attribute :character_id, xpath: "characterID/?[0]", type: :integer
+    def self.attribute(name, opts = {})
+      name = name.to_sym
+      @attributes ||= {}
+
+      raise "Attribute `#{name}` defined more than once" if @attributes[name]
+      raise "`:xpath` not specified for `#{name}`" unless opts[:xpath]
+
+      @attributes[name] = {
+        xpath: opts[:xpath],
+        type: opts[:type],
+      }
+
+      define_method(name) do
+        ivar = instance_variable_get(:"@#{name}")
+        return ivar unless ivar.nil?
+
+        value = @xml_element.locate(opts[:xpath]).first
+
+        unless value.nil?
+          value =
+            case opts[:type]
+            when :integer
+              value.to_i
+            when :numeric
+              BigDecimal.new(value)
+            when :string
+              value.to_s
+            when :datetime
+              Time.parse(value + " UTC")
+            end
+        end
+
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
+
+    # A DSL method to map an XML rowset to a Ruby object.
+    #
+    # @param name [Symbol] the Ruby name for this attribute
+    #
+    # @option opts [Symbol] :xpath the xpath string used to locate the attribute
+    #   in the XML element
+    #
+    # @example
+    #   rowset :employment_history, xpath: "eveapi/result/rowset[@name='employmentHistory']" do
+    #     attribute :record_id,        xpath: "@recordID",        type: :integer
+    #     attribute :corporation_id,   xpath: "@corporationID",   type: :integer
+    #     attribute :corporation_name, xpath: "@corporationName", type: :string
+    #     attribute :start_date,       xpath: "@startDate",       type: :datetime
+    #   end
+    def self.rowset(name, opts = {}, &block)
+      name = name.to_sym
+      @attributes ||= {}
+
+      raise "Attribute `#{name}` defined more than once" if @attributes[name]
+      raise "`:xpath` not specified for `#{name}`" unless opts[:xpath]
+
+      @attributes[name] = {
+        xpath: opts[:xpath],
+        type: :rowset,
+      }
+
+      define_method(name) do
+        ivar = instance_variable_get(:"@#{name}")
+        return ivar unless ivar.nil?
+
+        # Since Ox doesn't support the xpath [@k='v'] syntax, parse it out
+        # with a regex (captures :path, :attr, :attr_value).
+        attr_regex = %r{\A(?<path>.*?)\[@(?<attr>\w+)=['"](?<attr_value>\w+)['"]\]\z}
+        match = opts[:xpath].match(attr_regex)
+
+        rowset_element =
+          @xml_element
+            .locate(match[:path])
+            .find { |e| e.attributes[match[:attr].to_sym] == match[:attr_value] }
+
+        rowset = Rowset.new(name, rowset_element, &block)
+
+        instance_variable_set(:"@#{name}", rowset)
+      end
+    end
+
+    # A DSL method to specify the API endpoint.
+    #
+    # @param path [String] path of the API endpoint. Doesn't need to include the
+    #   leading slash `/`, or the extension `.xml.aspx`
+    #
+    # @example
+    #   endpoint "eve/CharacterInfo"
+    def self.endpoint(path)
+      # Remove leading slash and file extension.
+      @endpoint = path.gsub(/\A\/*(.*?)(?:\.xml)?(?:\.aspx)?\z/, '\1')
+    end
+
+    # @abstract Subclass and use the DSL methods to map API endpoints to objects
+    #
+    # @option opts [String, Fixnum] :key API key
+    # @option opts [String] :vcode API vCode
+    # @option opts [Hash<String, String>] :query_params a hash of HTTP query
+    #   params that specify how a value maps to the API request
+    #
+    # @example
+    #   super(query_params: {
+    #     "characterID" => character_id,
+    #   })
+    def initialize(opts = {})
+      raise TypeError, "Cannot instantiate an abstract class" \
+        if self.class.superclass != Greeve::BaseItem
+
+      @api_key = opts[:key]
+      @api_vcode = opts[:vcode]
+      @query_params = opts[:query_params] || {}
+
+      if @api_key && @api_vcode
+        @query_params.merge!({
+          "keyID" => @api_key,
+          "vCode" => @api_vcode,
+        })
+      end
+
+      refresh
+    end
+
+    # Query the API, refreshing this object's data.
+    #
+    # @return true if the endpoint was fetched (HTTP request sent), false if
+    #   the cache hasn't expired
+    def refresh
+      return false unless cache_expired?
+
+      fetch
+      true
+    end
+
+    # @return true if the API cache timer has expired and this object can
+    #   be refreshed
+    def cache_expired?
+      !(cached_until && cached_until > Time.now)
+    end
+
+    # @return [Time, nil] time when the cache expires and the resource can be
+    #   refreshed (sends an HTTP request)
+    def cached_until
+      return unless @xml_element
+
+      _cached_until = @xml_element.locate("eveapi/cachedUntil/?[0]").first
+      _cached_until ? Time.parse(_cached_until + " UTC") : nil
+    end
+
+    # :nodoc:
+    def inspect
+      attrs = to_s
+
+      unless attrs.empty?
+        attrs = attrs.split("\n").map { |l| "  #{l}" }.join("\n")
+        attrs = "\n#{attrs}\n"
+      end
+
+      "#<#{self.class.name}:#{object_id}#{attrs}>"
+    end
+
+    # @return [String] a string representation of the non-nil attributes
+    def to_s
+      to_h
+        .map { |k, v|
+          v = v.to_s("F") if v.is_a?(BigDecimal)
+          "#{k}: #{v}"
+        }
+        .join("\n")
+    end
+
+    # @return [Hash] a hash of non-nil attributes
+    def to_h
+      attributes
+        .keys
+        .map { |name|
+          value = __send__(name)
+          value = value.to_a if value.is_a?(Rowset)
+
+          [name, value]
+        }
+        .to_h
+        .reject { |k, v| v.nil? }
+    end
+
+    private
+
+    # @return [Hash] the hash of attributes for this object
+    def attributes
+      self.class.instance_variable_get(:@attributes) || {}
+    end
+
+    # @return [String] the class's endpoint path
+    def endpoint
+      self.class.instance_variable_get(:@endpoint)
+    end
+
+    # Fetch data from the API HTTP endpoint.
+    def fetch
+      url = "#{Greeve::EVE_API_BASE_URL}/#{endpoint}.xml.aspx"
+      response = Typhoeus.get(url, params: @query_params)
+
+      # TODO: Use a better error class.
+      raise TypeError, "HTTP error #{response.code}" \
+        unless (200..299).include?(response.code.to_i)
+
+      @xml_element = Ox.parse(response.body)
+
+      attributes.keys.each do |name|
+        instance_variable_set(:"@#{name}", nil)
+      end
+
+      @xml_element
+    end
+  end
+end

data/lib/greeve/eve/character_info.rb

@@ -0,0 +1,45 @@
+require_relative "../base_item"
+
+module Greeve
+  module Eve
+    # Public character info.
+    class CharacterInfo < Greeve::BaseItem
+      endpoint "eve/CharacterInfo"
+
+      attribute :character_id,        xpath: "eveapi/result/characterID/?[0]",       type: :integer
+      attribute :character_name,      xpath: "eveapi/result/characterName/?[0]",     type: :string
+      attribute :race,                xpath: "eveapi/result/race/?[0]",              type: :string
+      attribute :bloodline_id,        xpath: "eveapi/result/bloodlineID/?[0]",       type: :integer
+      attribute :bloodline,           xpath: "eveapi/result/bloodline/?[0]",         type: :string
+      attribute :ancestry_id,         xpath: "eveapi/result/ancestryID/?[0]",        type: :integer
+      attribute :ancestry,            xpath: "eveapi/result/ancestry/?[0]",          type: :string
+      attribute :account_balance,     xpath: "eveapi/result/accountBalance/?[0]",    type: :numeric
+      attribute :skill_points,        xpath: "eveapi/result/skillPoints/?[0]",       type: :integer
+      attribute :next_training_ends,  xpath: "eveapi/result/nextTrainingEnds/?[0]",  type: :datetime
+      attribute :ship_name,           xpath: "eveapi/result/shipName/?[0]",          type: :string
+      attribute :ship_type_id,        xpath: "eveapi/result/shipTypeID/?[0]",        type: :integer
+      attribute :ship_type_name,      xpath: "eveapi/result/shipTypeName/?[0]",      type: :string
+      attribute :corporation_id,      xpath: "eveapi/result/corporationID/?[0]",     type: :integer
+      attribute :corporation,         xpath: "eveapi/result/corporation/?[0]",       type: :string
+      attribute :corporation_date,    xpath: "eveapi/result/corporationDate/?[0]",   type: :datetime
+      attribute :alliance_id,         xpath: "eveapi/result/allianceID/?[0]",        type: :integer
+      attribute :alliance,            xpath: "eveapi/result/alliance/?[0]",          type: :string
+      attribute :alliance_date,       xpath: "eveapi/result/allianceDate/?[0]",      type: :datetime
+      attribute :last_known_location, xpath: "eveapi/result/lastKnownLocation/?[0]", type: :string
+      attribute :security_status,     xpath: "eveapi/result/securityStatus/?[0]",    type: :numeric
+
+      rowset :employment_history, xpath: "eveapi/result/rowset[@name='employmentHistory']" do
+        attribute :record_id,        xpath: "@recordID",        type: :integer
+        attribute :corporation_id,   xpath: "@corporationID",   type: :integer
+        attribute :corporation_name, xpath: "@corporationName", type: :string
+        attribute :start_date,       xpath: "@startDate",       type: :datetime
+      end
+
+      # @param character_id [Integer] EVE character ID
+      def initialize(character_id, opts = {})
+        opts[:query_params] = { "characterID" => character_id }
+        super(opts)
+      end
+    end
+  end
+end

data/lib/greeve/row.rb

@@ -0,0 +1,72 @@
+module Greeve
+  # Represents an XML `row` element, contained in a {Rowset}.
+  class Row
+    # @param xml_element [Ox::Element] the xml row element for this item
+    # @param attributes [Hash] the hash of attribute definitions for this row
+    def initialize(xml_element, attributes)
+      @xml_element = xml_element
+      @attributes = attributes
+
+      attributes.each do |name, opts|
+        define_singleton_method(name) do
+          ivar = instance_variable_get(:"@#{name}")
+          return ivar unless ivar.nil?
+
+          value = @xml_element.locate(opts[:xpath]).first
+
+          unless value.nil?
+            value =
+              case opts[:type]
+              when :integer
+                value.to_i
+              when :numeric
+                BigDecimal.new(value)
+              when :string
+                value.to_s
+              when :datetime
+                Time.parse(value + " UTC")
+              end
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+    end
+
+    # :nodoc:
+    def inspect
+      attrs = to_s
+
+      unless attrs.empty?
+        attrs = attrs.split("\n").map { |l| "  #{l}" }.join("\n")
+        attrs = "\n#{attrs}\n"
+      end
+
+      "#<#{self.class.name}:#{object_id}#{attrs}>"
+    end
+
+    # @return [String] a string representation of the non-nil attributes
+    def to_s
+      to_h
+        .map { |k, v|
+          v = v.to_s("F") if v.is_a?(BigDecimal)
+          "#{k}: #{v}"
+        }
+        .join("\n")
+    end
+
+    # @return [Hash] a hash of non-nil attributes
+    def to_h
+      @attributes
+        .keys
+        .map { |name|
+          value = __send__(name)
+          value = value.to_a if value.is_a?(Rowset)
+
+          [name, value]
+        }
+        .to_h
+        .reject { |k, v| v.nil? }
+    end
+  end
+end

data/lib/greeve/rowset.rb

@@ -0,0 +1,71 @@
+require_relative "row"
+
+module Greeve
+  # Represents an XML `rowset` element.
+  class Rowset
+    include Enumerable
+
+    # @return [Symbol] name of the rowset
+    attr_reader :name
+
+    # @param name [Symbol] name of the rowset
+    # @param xml_element [Ox::Element] the xml rowset element for this item
+    # @yield a block containing the attribute definitions for {Row}
+    def initialize(name, xml_element, &block)
+      @name = name
+      @xml_element = xml_element
+      @attributes = {}
+      @rows = nil
+
+      # Load the attribute configuration in the rowset block.
+      instance_eval(&block)
+
+      # Disable the #attribute method since the attributes have been configured.
+      define_singleton_method(:attribute) { raise NoMethodError, "private method" }
+    end
+
+    # :nodoc:
+    def each(&block)
+      rows.each(&block)
+    end
+
+    # @return [Array] an array of rows and their non-nil attributes
+    def to_a
+      map(&:to_h)
+    end
+
+    # :nodoc:
+    def inspect
+      "#<#{self.class.name}:#{object_id} name: #{@name}>"
+    end
+
+    # Map an XML attribute to a Ruby object.
+    #
+    # @!visibility private
+    # @see {Greeve::BaseItem.attribute}
+    def attribute(name, opts = {})
+      name = name.to_sym
+
+      raise "Attribute `#{name}` defined more than once" if @attributes[name]
+      raise "`:xpath` not specified for `#{name}`" unless opts[:xpath]
+
+      @attributes[name] = {
+        xpath: opts[:xpath],
+        type: opts[:type],
+      }
+    end
+
+    private
+
+    # @return [Array<Row>] an array of rows in the rowset
+    def rows
+      return @rows unless @rows.nil?
+
+      rows = @xml_element.locate("row").map do |row_element|
+        Row.new(row_element, @attributes)
+      end
+
+      @rows = rows
+    end
+  end
+end