Class: Greeve::BaseItem

Inherits:
Object
  • Object
show all
Extended by:
Helpers::AddAttribute, Helpers::DefineDSLMethods
Includes:
Helpers::AttributeToHash
Defined in:
lib/greeve/base_item.rb

Overview

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.

Direct Known Subclasses

API::CallList, Account::APIKeyInfo, Account::AccountStatus, Account::Characters, Character::AccountBalance, Character::AssetList, Character::Blueprints, Character::CalendarEventAttendees, Character::CharacterSheet, Character::Clones, Character::ContactList, Character::ContactNotifications, Character::ContractBids, Character::ContractItems, Character::Contracts, Character::FacWarStats, Character::IndustryJobs, Character::IndustryJobsHistory, Character::Locations, Character::MailBodies, Character::MailMessages, Character::MailingLists, Character::MarketOrders, Character::Medals, Character::Notifications, Character::PlanetaryColonies, Character::PlanetaryLinks, Character::PlanetaryPins, Character::PlanetaryRoutes, Character::Research, Character::SkillInTraining, Character::SkillQueue, Character::Skills, Character::Standings, Character::UpcomingCalendarEvents, Character::WalletJournal, Character::WalletTransactions, Corporation::AccountBalance, Corporation::Contracts, Corporation::CorporationSheet, Corporation::IndustryJobs, Corporation::IndustryJobsHistory, Corporation::Locations, Corporation::MarketOrders, Corporation::MemberTracking, Corporation::Standings, Corporation::StarbaseDetail, Corporation::StarbaseList, Corporation::WalletJournal, Corporation::WalletTransactions, Eve::AllianceList, Eve::CharacterAffiliation, Eve::CharacterID, Eve::CharacterInfo, Eve::CharacterName, Eve::ConquerableStationList, Eve::ErrorList, Eve::RefTypes, Eve::TypeName, Map::FacWarSystems, Map::Jumps, Map::Kills, Map::Sovereignty, Server::ServerStatus

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers::AttributeToHash

#to_h

Constructor Details

#initialize(opts = {}) ⇒ BaseItem

This method is abstract.

Subclass and use the DSL methods to map API endpoints to objects

Returns a new instance of BaseItem

Examples:

super(query_params: {
  "characterID" => character_id,
})

Parameters:

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :key (String, Fixnum)

    API key

  • :vcode (String)

    API vCode

  • :query_params (Hash<String, String>)

    a hash of HTTP query params that specify how a value maps to the API request

Raises:

  • (TypeError)


124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
# File 'lib/greeve/base_item.rb', line 124

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

Class Method Details

.attribute(name, opts = {}) ⇒ Object

A DSL method to map an XML attribute to a Ruby object.

Examples:

attribute :character_id, xpath: "characterID/?[0]", type: :integer

Parameters:

  • name (Symbol)

    the Ruby name for this attribute

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :xpath (Symbol)

    the xpath string used to locate the attribute in the XML element

  • :type (:integer, :numeric, :string)

    method used to coerce the XML value



31
32
33
34
35
36
# File 'lib/greeve/base_item.rb', line 31

def self.attribute(name, opts = {})
  @attributes ||= {}

  add_attribute(name, opts)
  define_attribute_method(:class, name, opts)
end

.endpoint(path) ⇒ Object

A DSL method to specify the API endpoint.

Examples:

endpoint "eve/CharacterInfo"

Parameters:

  • path (String)

    path of the API endpoint. It shouldn't include the leading slash `/`, or the extension `.xml.aspx`

Raises:

  • (ArgumentError)


106
107
108
109
110
111
# File 'lib/greeve/base_item.rb', line 106

def self.endpoint(path)
  raise ArgumentError, "Endpoint shouldn't start with a slash" \
    if path.start_with?("/")

  @endpoint = path
end

.namespace(name, opts = {}, &block) ⇒ Object

A DSL method to nest a set of attributes within a namespace.

Examples:

namespace :general_settings, xpath: "eveapi/result/generalSettings" do
  attribute :usage_flags, xpath: "usageFlags/?[0]", type: :integer
end

Parameters:

  • name (Symbol)

    the Ruby name for this namespace

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :xpath (Symbol)

    the xpath string used to locate the namespace in the XML element



49
50
51
52
53
54
55
56
# File 'lib/greeve/base_item.rb', line 49

def self.namespace(name, opts = {}, &block)
  @attributes ||= {}

  opts[:type] = :namespace

  add_attribute(name, opts)
  define_namespace_method(:class, name, opts, &block)
end

.rowset(name, opts = {}, &block) ⇒ Object

A DSL method to map an XML rowset to a Ruby object.

Examples:

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

Parameters:

  • name (Symbol)

    the Ruby name for this attribute

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :xpath (Symbol)

    the xpath string used to locate the attribute in the XML element



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
# File 'lib/greeve/base_item.rb', line 72

def self.rowset(name, opts = {}, &block)
  @attributes ||= {}

  opts[:type] = :rowset

  add_attribute(name, opts)

  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

Instance Method Details

#cache_expired?Boolean

Returns true if the API cache timer has expired and this object can be refreshed

Returns:

  • (Boolean)

    true if the API cache timer has expired and this object can be refreshed



155
156
157
# File 'lib/greeve/base_item.rb', line 155

def cache_expired?
  !(cached_until && cached_until > Time.now)
end

#cached_untilTime?

Returns time when the cache expires and the resource can be refreshed (sends an HTTP request)

Returns:

  • (Time, nil)

    time when the cache expires and the resource can be refreshed (sends an HTTP request)



161
162
163
164
165
166
# File 'lib/greeve/base_item.rb', line 161

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

#inspectObject

:nodoc:



169
170
171
172
173
174
175
176
177
178
# File 'lib/greeve/base_item.rb', line 169

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

#refreshObject

Query the API, refreshing this object's data.

Returns:

  • true if the endpoint was fetched (HTTP request sent), false if the cache hasn't expired



146
147
148
149
150
151
# File 'lib/greeve/base_item.rb', line 146

def refresh
  return false unless cache_expired?

  fetch
  true
end

#to_sString

Returns a string representation of the non-nil attributes

Returns:

  • (String)

    a string representation of the non-nil attributes



181
182
183
184
185
186
187
188
# File 'lib/greeve/base_item.rb', line 181

def to_s
  to_h
    .map { |k, v|
      v = v.to_s("F") if v.is_a?(BigDecimal)
      "#{k}: #{v}"
    }
    .join("\n")
end