eaal 0.1.4 → 0.1.5

data/History.txt

@@ -1,3 +1,9 @@
+== 0.1.5 2009-04-10
+ * 1 fix:
+   * code cleanup by JamesHarrison
+ * New Feature:
+   * memcached handler by JamesHarrison
+
 == 0.1.4 2009-04-02
 
  * 1 fix:

data/Manifest.txt

@@ -1,19 +1,22 @@
 History.txt
+LICENSE.txt
 Manifest.txt
 README.rdoc
-LICENSE.txt
 Rakefile
 lib/eaal.rb
-lib/eaal/eaal.rb
-lib/eaal/eaal_cache.rb
-lib/eaal/eaal_exception.rb
-lib/eaal/eaal_result.rb
-lib/eaal/eaal_rowset.rb
+lib/eaal/api.rb
+lib/eaal/cache/base.rb
+lib/eaal/cache/file.rb
+lib/eaal/cache/memcached.rb
+lib/eaal/exception.rb
+lib/eaal/result.rb
+lib/eaal/rowset.rb
 script/console
 script/destroy
 script/generate
-test/test_helper.rb
-test/test_eaal.rb
 test/fixtures/test/test/account/Characters/Request_.xml
-test/fixtures/test/test/char/Killlog/Request_characterID:12345.xml
 test/fixtures/test/test/char/Killlog/Request_.xml
+test/fixtures/test/test/char/Killlog/Request_characterID:12345.xml
+test/fixtures/test/test/eve/AllianceList/Request_.xml
+test/test_eaal.rb
+test/test_helper.rb

data/README.rdoc

@@ -88,6 +88,10 @@ the XML file will be load.
 
 * sudo gem install eaal
 
+== THANKS:
+special thanks go to James "Ix_Forres" Harrison for his code cleanups and 
+his memcache cache handler
+
 == LICENSE:
 
 (The MIT License)
@@ -111,4 +115,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,27 +1,27 @@
-%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
-require File.dirname(__FILE__) + '/lib/eaal.rb'
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.new('eaal', EAAL.version) do |p|
-  p.developer('Peter Petermann', 'PeterPetermann@gmx.net')
-  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  p.rubyforge_name       = p.name # TODO this is default value
-  p.extra_deps         = [
-    ['activesupport','>= 2.0.2'], ['hpricot', '>= 0.6']
-  ]
-  p.extra_dev_deps = [
-    ['newgem', ">= #{::Newgem::VERSION}"]
-  ]
-  
-  p.clean_globs |= %w[**/.DS_Store tmp *.log]
-  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
-  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
-  p.rsync_args = '-av --delete --ignore-errors'
-end
-
-require 'newgem/tasks' # load /tasks/*.rake
-Dir['tasks/**/*.rake'].each { |t| load t }
-
-# TODO - want other tests/tasks run by default? Add them to the list
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/eaal.rb'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('eaal', EAAL.version) do |p|
+  p.developer('Peter Petermann', 'PeterPetermann@gmx.net')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.rubyforge_name       = p.name # TODO this is default value
+  p.extra_deps         = [
+    ['activesupport','>= 2.0.2'], ['hpricot', '>= 0.6'], ['memcache-client','>= 1.7.1']
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
 # task :default => [:spec, :features]

data/lib/eaal.rb

@@ -1,6 +1,45 @@
-path = File.dirname(__FILE__) + '/eaal/'
-require path + 'eaal_cache.rb'
-require path + 'eaal_exception.rb'
-require path + 'eaal_result.rb'
-require path + 'eaal_rowset.rb'
-require path + 'eaal.rb'
+#--
+# EAAL by Peter Petermann <PeterPetermann@gmx.net>
+# This library is licensed under the terms found in
+# the LICENSE file distributed with it
+#
+# TODO: 
+#  - more documenation
+#  - write tests (i know, i know, i fail badly)
+#  - more error handling (im certain i missed a few possibles)
+#  - cleanup (you can see that this is my first project in ruby, cant you?)
+#
+# THANKS:
+#  thanks go to all people on irc.coldfront.net, channel #eve-dev
+#  special thanks go to lisa (checkout her eve api library, reve,
+#  much more mature then mine) for answering my endless questions 
+#  about ruby stuff (and for one or two snippets i stole from reve)
+#++
+# Neat little hack to get around path issues on require
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+# External libs
+require 'rubygems'
+require 'hpricot'
+require 'activesupport'
+require 'net/http'
+require 'uri'
+require 'cgi'
+# And now EAAL stuff
+require 'eaal/cache/base'
+require 'eaal/cache/file'
+require 'eaal/cache/memcached'
+require 'eaal/exception'
+require 'eaal/result'
+require 'eaal/rowset'
+module EAAL
+  mattr_reader :version_string, :version
+  @@version = "0.1.5"
+  @@version_string = "EAAL" +  EAAL.version # the version string, used as client name in http requests
+    
+  mattr_accessor :api_base, :additional_request_parameters, :cache
+  @@api_base = "http://api.eve-online.com/"  # the url used as basis for all requests, you might want to use gatecamper url or a personal proxy instead
+  @@additional_request_parameters = {}       # hash, if :key => value pairs are added those will be added to each request    
+  @@cache = EAAL::Cache::NoCache.new         # caching object, see EAAL::Cache::FileCache for an Example
+end
+require 'eaal/api'

data/lib/eaal/api.rb

@@ -0,0 +1,77 @@
+
+# EAAL::API class
+# Usage Example:
+#  api = EAAL::API.new("my userid", "my API key")
+#  result = api.Characters
+#  result.characters.each{|character|
+#      puts character.name
+#  }
+class EAAL::API
+  attr_accessor :userid, :key, :scope
+      
+  # constructor
+  # Expects:
+  # * userid (String | Integer) the users id
+  # * key (String) the apikey Full or Restricted
+  # * scope (String) defaults to account
+  def initialize(userid, key, scope="account")
+    self.userid = userid.to_s
+    self.key = key.to_s
+    self.scope = scope.to_s
+  end
+  
+  # create an xml request according to the method called
+  # this is used to dynamicaly create api calls and 
+  # should usually not be called directly
+  # * method (const) 
+  # * args 
+  def method_missing(method, *args)
+    scope = self.scope
+    args_hash = args.first
+    args_hash = {} unless args_hash
+    self.request_xml(scope, method.id2name, args_hash)
+  end
+    
+  # make a request to the api. will use cache if set.
+  # usually not called by the user directly
+  # * scope (String)
+  # * name (String)
+  # * opts (Hash)
+  def request_xml(scope, name, opts)
+    opts = EAAL.additional_request_parameters.merge(opts)
+    xml = EAAL.cache.load(self.userid, self.key, scope, name,opts)
+    if not xml
+      source = URI.parse(EAAL.api_base + scope + '/' + name +'.xml.aspx')
+      req_path = source.path + format_url_request(opts.merge({
+        :userid => self.userid, 
+        :apikey => self.key}))
+      req = Net::HTTP::Get.new(req_path)
+      req[EAAL.version_string]
+      res = Net::HTTP.new(source.host, source.port).start {|http| http.request(req) } #one request for now  
+      case res
+      when Net::HTTPOK
+      when Net::HTTPNotFound
+        raise EAAL::Exception::APINotFoundError.new("The requested API (#{scope} / #{name}) could not be found.")
+      else 
+        raise EAAL::Exception::HTTPError.new("An HTTP Error occured, body: " + res.body)
+      end
+      EAAL.cache.save(self.userid, self.key, scope,name,opts, res.body)
+      xml = res.body
+    end
+    doc = Hpricot.XML(xml)
+    result = EAAL::Result.new(scope.capitalize + name, doc)
+  end
+              
+  # Turns a hash into ?var=baz&bam=boo
+  # stolen from Reve (thx lisa)
+  # * opts (Hash)
+  def format_url_request(opts)
+    req = "?"
+    opts.stringify_keys!
+    opts.keys.sort.each do |key|
+      req += "#{CGI.escape(key.to_s)}=#{CGI.escape(opts[key].to_s)}&" if opts[key]
+    end
+    req.chop # We are lazy and append a & to each pair even if it's the last one. FIXME: Don't do this.
+  end
+
+end

data/lib/eaal/cache/base.rb

@@ -0,0 +1,27 @@
+#--
+# EAAL by Peter Petermann <PeterPetermann@gmx.net>
+# This library is licensed under the terms found in
+# the LICENSE file distributed with it
+#++
+require 'fileutils'
+
+module EAAL
+  # The Classes in this module are objects that may be used as value
+  # of EAAL.cache.
+  # By default EAAL uses the NoCache class, where no caching is done.
+  # If a working cache class is used it will store the xml data
+  # and return it, so no requests to the API are done (as long as valid xml is available)
+  module Cache
+    # NoCache class
+    # dummy class which is used for non-caching behaviour (default)
+    class NoCache
+      def load(userid, apikey, scope, name, args)
+        false
+      end
+      def save(userid, apikey, scope, name, args, xml)
+      end
+    end
+    
+  end
+end
+

data/lib/eaal/cache/file.rb

@@ -0,0 +1,62 @@
+# EAAL::Cache::FileCache
+# File based xml cache which respects the cachedUntil of the Eve API
+# Usage:
+#  EAAL.cache = EAAL::Cache::FileCache.new
+# Or
+#  EAAL.cache = EAAL::Cache::FileCache.new("/path/to/place/to/store/xml/data")
+class EAAL::Cache::FileCache
+  attr_accessor :basepath
+  
+  # constructor, takes one argument which is the path
+  # where files should be written
+  # * basepath (String) path which should be used to store cached data. defaults to $HOME/.eaal/cache/
+  def initialize(basepath = "#{ENV['HOME']}/.eaal/cache")
+    if basepath[(basepath.length) -1, basepath.length] != "/"
+      basepath += "/" 
+    end
+    @basepath = basepath
+  end
+  
+  # create the path/filename for the cache file
+  def filename(userid, apikey, scope, name, args)
+    ret =""
+    args.delete_if { |k,v| (v || "").to_s.length == 0 }
+    h = args.stringify_keys
+    ret += h.sort.flatten.collect{ |e| e.to_s }.join(':')
+    hash = ret.gsub(/:$/,'')
+    "#{@basepath}#{userid}/#{apikey}/#{scope}/#{name}/Request_#{hash}.xml"
+  end
+  
+  # load xml if available, return false if not available, or cachedUntil ran out
+  def load(userid, apikey, scope, name, args)
+    filename = self.filename(userid, apikey,scope,name,args)
+    if not File.exist?(filename)
+      ret = false
+    else
+      xml = File.open(filename).read
+      if self.validate_cache(xml, name)
+        ret = xml
+      else
+        ret = false
+      end
+    end
+    ret
+  end
+  
+  # validate cached datas cachedUntil
+  def validate_cache(xml, name)
+    doc = Hpricot.XML(xml)
+    if name == "WalletJournal"
+            Time.at((doc/"/eveapi/cachedUntil").inner_html.to_time.to_i + 3600) > Time.now
+          else 
+      (doc/"/eveapi/cachedUntil").inner_html.to_time > Time.now
+    end
+  end
+  
+  # save xml data to file
+  def save(userid, apikey, scope, name, args, xml)
+    filename = self.filename(userid, apikey,scope,name,args)
+    FileUtils.mkdir_p(File.dirname(filename))
+    File.open(filename,'w') { |f| f.print xml }        
+  end
+end

data/lib/eaal/cache/memcached.rb

@@ -0,0 +1,30 @@
+# EAAL::Cache::Memcached
+# Cache class to allow use of Memcached server(s) as a local cache option.
+require 'memcache'
+class EAAL::Cache::MemcachedCache
+
+  def initialize(servers="localhost:11211",options={})
+    o = {:namespace => 'eaal'}.merge(options)
+    $cache = MemCache.new(servers,o)
+  end
+  # Returns the memcached key for a given set of args.
+  # Does not use the full API key string as the risk of a collision is astronomically high.
+  def key(userid, apikey, scope, name, args)
+    "#{userid}#{apikey[0..25]}#{scope}#{name}#{args}"
+  end
+  # Saves to cache. It is worth noting that memcached handles expiry for us unlike FileCache
+  # as a result, there is no requirement for a validate_cache method- we just get MC to expire
+  # the key when we can go get a new copy.
+  def save(userid, apikey, scope, name, args, xml)
+    k = key(userid, apikey, scope, name, args)
+    cached_until = xml.match(/<cachedUntil>(.+)<\/cachedUntil>/)[1].to_time
+    expires_in = (name=='WalletJournal' ? cached_until.to_i+3600 : cached_until.to_i )-Time.now.to_i
+    $cache.delete(k)
+    $cache.add(k,xml,expires_in)
+  end
+  # Loads from the cache if there's a value for it.
+  def load(userid, apikey, scope, name, args)
+    k = key(userid, apikey, scope, name, args)
+    ($cache.get(k,xml,expires_in) or false) rescue false
+  end
+end

data/lib/eaal/exception.rb

@@ -0,0 +1,40 @@
+#--
+# EAAL by Peter Petermann <PeterPetermann@gmx.net>
+# This library is licensed under the terms found in
+# the LICENSE file distributed with it
+#++
+module EAAL::Exception
+  # creates the class for an EveAPIException
+  def self.EveAPIException(nr)
+    classname = "EveAPIException#{nr}" 
+    if not Object.const_defined? classname
+      klass = Object.const_set(classname, Class.new(EAAL::Exception::EveAPIException))
+    else
+      klass = Object.const_get(classname)
+    end
+    klass
+  end
+  
+  # raise the eve API exceptions, class will be dynamicaly created by classname
+  # EveAPIException followed by the APIs exception Number
+  def self.raiseEveAPIException(nr, msg)
+      raise EAAL::Exception.EveAPIException(nr).new(msg)
+  end
+  
+  # all EAAL exceptions should extend this.
+  class EAALError < StandardError
+  end
+  
+  # Used when an http error is encountered
+  class HTTPError < EAALError
+  end
+  
+  # Used when the Eve API returns a 404
+  class APINotFoundError < HTTPError
+  end
+  
+  # All API Errors should be derived from this
+  class EveAPIException < EAALError
+  end
+      
+  end

data/lib/eaal/{eaal_result.rb → result.rb}

@@ -1,123 +1,123 @@
-#--
-# EAAL by Peter Petermann <PeterPetermann@gmx.net>
-# This library is licensed under the terms found in
-# the LICENSE file distributed with it
-#++
-module EAAL
-
-    module Result
-      
-        # base class for automated result class creation
-        class ResultBase
-            attr_accessor :request_time, :cached_until
-        end
-        
-        # Result Container class, ...  
-        class ResultContainer
-            attr_accessor :container
-
-            def initialize
-                self.container = {}
-            end
-            
-            def add_element(key, val)
-                self.container.merge!({key => val})
-            end
-
-            def method_missing(method, *args)
-                self.container[method.id2name]
-            end
-        end
-
-        # result element
-        class ResultElement
-            attr_accessor :name, :value, :attribs
-            def initialize(name, value)
-                self.name = name
-                self.value = value     
-                self.attribs = {}
-            end
-
-            def add_attrib(key, val)
-                self.attribs.merge!({key => val})
-            end
-
-            def method_missing(method, *args)
-                if self.attribs.has_key?(method.id2name)
-                    self.attribs[method.id2name]
-                else
-                    self.value.send(method, *args)                    
-                end
-                
-            end
-                    
-            # parses an xml element to create either the ResultElement, ResultContainer or Rowset 
-            # necessary
-            def self.parse_element(prefix, element)
-                if element.name == "rowset"
-                    re = EAAL::Rowset.new(prefix, element)
-                else
-                    key = element.name
-                    if element.children && element.containers.length > 0
-                        container = ResultContainer.new
-                        element.containers.each { |celement|
-                            cel = EAAL::Result::ResultElement.parse_element(prefix, celement)
-                            if element.attributes.length > 0
-                                container.add_element(cel.name, cel)
-                            else 
-                                container.add_element(cel.name, cel.value)
-                            end
-                        }
-                        value = container
-                    else
-                        value = element.inner_html
-                    end
-                    re = ResultElement.new(key, value)
-                    if element.attributes.length > 0
-                        re.attribs.merge!(element.attributes)
-                    end
-                end
-                re
-            end
-        end
-
-	# create a new result derived from ResultBase
-        def self.new(prefix, xml)
-            classname = prefix + 'Result'
-            members = []
-            values = {}
-            if (xml/"eveapi/error").length > 0
-              error = (xml/"eveapi/error").first
-              raise EAAL::Exception.raiseEveAPIException(error["code"], error.inner_html)
-            end
-            if (xml/"eveapi/result").length < 1
-              raise EAAL::Exception::EAALError.new("Unknown API error, no result element was found")
-            end
-            elements = (xml/"eveapi/result").first.containers
-            elements.each {|element|
-                el = EAAL::Result::ResultElement.parse_element(prefix, element)
-                members << el.name
-                if el.kind_of? EAAL::Rowset::RowsetBase
-                    values.merge!({el.name => el})
-                else
-                    values.merge!({el.name => el.value})
-                end
-            }
-            if not Object.const_defined? classname
-                klass = Object.const_set(classname, Class.new(EAAL::Result::ResultBase))    
-                klass.class_eval do
-                    attr_accessor *members
-                end
-            else
-                klass = Object.const_get(classname)
-            end
-            result = klass.new
-            result.request_time = (xml/"eveapi/currentTime").first.inner_html
-            result.cached_until = (xml/"eveapi/cachedUntil").first.inner_html
-            values.each { |key,value|
-                result.send(key + "=", value)
-            }
-            result
-        end
-    end
-end
+#--
+# EAAL by Peter Petermann <PeterPetermann@gmx.net>
+# This library is licensed under the terms found in
+# the LICENSE file distributed with it
+#++
+module EAAL
+
+    module Result
+      
+        # base class for automated result class creation
+        class ResultBase
+            attr_accessor :request_time, :cached_until
+        end
+        
+        # Result Container class, ...  
+        class ResultContainer
+            attr_accessor :container
+
+            def initialize
+                self.container = {}
+            end
+            
+            def add_element(key, val)
+                self.container.merge!({key => val})
+            end
+
+            def method_missing(method, *args)
+                self.container[method.id2name]
+            end
+        end
+
+        # result element
+        class ResultElement
+            attr_accessor :name, :value, :attribs
+            def initialize(name, value)
+                self.name = name
+                self.value = value     
+                self.attribs = {}
+            end
+
+            def add_attrib(key, val)
+                self.attribs.merge!({key => val})
+            end
+
+            def method_missing(method, *args)
+                if self.attribs.has_key?(method.id2name)
+                    self.attribs[method.id2name]
+                else
+                    self.value.send(method, *args)                    
+                end
+                
+            end
+                    
+            # parses an xml element to create either the ResultElement, ResultContainer or Rowset 
+            # necessary
+            def self.parse_element(prefix, element)
+                if element.name == "rowset"
+                    re = EAAL::Rowset.new(prefix, element)
+                else
+                    key = element.name
+                    if element.children && element.containers.length > 0
+                        container = ResultContainer.new
+                        element.containers.each { |celement|
+                            cel = EAAL::Result::ResultElement.parse_element(prefix, celement)
+                            if element.attributes.length > 0
+                                container.add_element(cel.name, cel)
+                            else 
+                                container.add_element(cel.name, cel.value)
+                            end
+                        }
+                        value = container
+                    else
+                        value = element.inner_html
+                    end
+                    re = ResultElement.new(key, value)
+                    if element.attributes.length > 0
+                        re.attribs.merge!(element.attributes)
+                    end
+                end
+                re
+            end
+        end
+
+	# create a new result derived from ResultBase
+        def self.new(prefix, xml)
+            classname = prefix + 'Result'
+            members = []
+            values = {}
+            if (xml/"eveapi/error").length > 0
+              error = (xml/"eveapi/error").first
+              raise EAAL::Exception.raiseEveAPIException(error["code"], error.inner_html)
+            end
+            if (xml/"eveapi/result").length < 1
+              raise EAAL::Exception::EAALError.new("Unknown API error, no result element was found")
+            end
+            elements = (xml/"eveapi/result").first.containers
+            elements.each {|element|
+                el = EAAL::Result::ResultElement.parse_element(prefix, element)
+                members << el.name
+                if el.kind_of? EAAL::Rowset::RowsetBase
+                    values.merge!({el.name => el})
+                else
+                    values.merge!({el.name => el.value})
+                end
+            }
+            if not Object.const_defined? classname
+                klass = Object.const_set(classname, Class.new(EAAL::Result::ResultBase))    
+                klass.class_eval do
+                    attr_accessor(*members)
+                end
+            else
+                klass = Object.const_get(classname)
+            end
+            result = klass.new
+            result.request_time = (xml/"eveapi/currentTime").first.inner_html
+            result.cached_until = (xml/"eveapi/cachedUntil").first.inner_html
+            values.each { |key,value|
+                result.send(key + "=", value)
+            }
+            result
+        end
+    end
+end