wowr 0.2.2 → 0.3.0

data/README

@@ -1,62 +1,29 @@
 Wowr
 ----
-
 Ruby Library for the World of Warcraft Armory
 
 
 
 Introduction
 ------------
-
 Wowr is an API for accessing data in the World of Warcraft Armory. Using the XML data provided by the armory, it allows developers to query World of Warcraft items, characters, guilds and arena teams. It is designed to support developers that wish to add WoW information to their Ruby-powered site, as well as larger guild or portal sites for many users.
 
 
 
 Usage
 -----
-
-When initialising the library, it is possible to set a number of parameters to be used as defaults in other API functions.
-
-# all parameters optional
-api = Wowr::API.new(:character_name => 'Foo',
-                    :guild_name => 'Bar',
-                    :realm => 'Baz',
-                    :locale => 'eu', # defaults to US www
-                    :lang => 'fr_fr', # remove for locale default language
-                    :caching => true # defaults to false)
-
-# Character requests
-my_char = api.get_character_sheet # gets character with API default values
-char_boo = api.get_character_sheet(:character_name => 'Boo')
-chars = api.search_characters(:search => 'Cake')
-
-# Guild requests
-guilds = api.search_guilds(:search => 'Cake')
-cake_guild = api.get_guild(:guild_name => 'Cake', :realm => 'Silver Hand')
-
-# Items
-items = api.search_items(:search => 'Cake')
-item_info = api.get_item_info(:item_id => 33924)
-item_tooltip = api.get_item_tooltip(:item_id => 33924)
-
-# Arena Teams
-arena_teams = api.search_arena_teams(:search => 'Lemon')
-arena_team = api.get_arena_team(:team_name => 'Lemon', :realm => 'Hakkar', :team_size => 5)
-
-This API is under development, and is one of my first API projects, so I would greatly appreciate any feedback about it's usefulness or any requests for features/changes. Feel free to drop me a line at benhumphreys[at]gmail
+See example.rb
 
 
 
 Documentation
 -------------
-
 Please view the RubyDoc for more information on usage. http://wowr.rubyforge.org/doc/
 
 
 
 Installation
 ------------
-
 Wowr can be installed through RubyGems using the command below:
   gem install wowr
 
@@ -64,3 +31,8 @@ Alternatively, the latest version can be downloaded from SVN with:
   svn checkout http://wowr.rubyforge.org/svn/trunk/lib/
 
 
+
+Author
+------
+Ben Humphreys
+benhumphreys[at]gmail.com

data/changelog.txt

@@ -0,0 +1,31 @@
+0.3.0
+* It is now possible to use shorter method calls
+  api.get_item_tooltip(29242)
+  api.get_item_tooltip(29242, :caching => false, :lang => 'fr_fr')
+  
+  Old method calls using hashes are still supported
+  api.get_item_tooltip(:item_id => 29242)
+  
+  api.get_character_sheet("Smith")
+  
+  The same applies for searches, instead of
+  api.search_characters(:search => "cake")
+  it is now possible to write
+  api.search_characters("cake")
+
+* A new request get_character has been created which gets the full character details provided by the character_sheet.xml, character_skills.xml and character_reputation.xml.  It is still possible to use get_character_sheet, but this is deprecated
+
+* A new method Wowr::API.get_item has been created, which provides the details from get_item_info and get_item_tooltip returned in one object.
+
+* The API is now more strict and will throw exceptions if the correct parameters are not provided.
+
+* For consistency, the get requests now throws exceptions whenever the item or character is not found.  Search requests still return empty arrays if nothing is found, but will return an exception if empty search parameters are provided.
+
+* Skill information is now in a hash my_char.skill_categories['weaponskills'].skills['maces']
+
+* Reputation information is accessible by hash: my_char.rep['alliance'].factions['darnassus']
+
+* More informative exception messages.
+
+* Caching is now on by default.
+

data/lib/wowr.rb

@@ -1,114 +1,67 @@
+# 
 # Wowr - Ruby library for the World of Warcraft Armory
 # http://wowr.rubyforge.org/
-
-# written by Ben Humphreys
+# Written by Ben Humphreys
 # http://benhumphreys.co.uk/
+# 
+# Author:: Ben Humphreys
+# May not be used for commercial applications
+# 
 
 begin
 	require 'hpricot' # version 0.6
 rescue LoadError
 	require 'rubygems'
-	require 'hpricot' # version 0.6
+	require 'hpricot'
 end
 require 'net/http'
 require 'cgi'
-require 'fileutils' # for making directories :S
+require 'fileutils'
 
-# TODO: what does this do?
 $:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
-
-# require 'lib/wowr/exceptions.rb'
-# require 'lib/wowr/extensions.rb'
-# require 'lib/wowr/classes.rb'
+$LOAD_PATH.unshift(File.dirname(__FILE__))
 
 require 'wowr/exceptions.rb'
 require 'wowr/extensions.rb'
-require 'wowr/classes.rb'
 
+require 'wowr/character.rb'
+require 'wowr/guild.rb'
+require 'wowr/item.rb'
+require 'wowr/arena_team.rb'
 
 module Wowr
 	class API
-
+		VERSION = '0.3.0'
+		
 		@@armory_url_base = 'wowarmory.com/'
-		# @@eu_armory_url = 'http://eu.wowarmory.com/'
 		
 		@@search_url = 'search.xml'
 		
-		@@character_sheet_url = 'character-sheet.xml'
-		@@character_talents_url = 'character-talents.xml'
-		@@character_skills_url = 'character-skills.xml'
-		@@character_reputation_url = 'character-reputation.xml'
+		@@character_sheet_url				= 'character-sheet.xml'
+		@@character_talents_url			= 'character-talents.xml'
+		@@character_skills_url			= 'character-skills.xml'
+		@@character_reputation_url	= 'character-reputation.xml'
 		
-		@@guild_info_url = 'guild-info.xml'
+		@@guild_info_url		= 'guild-info.xml'
+		
+		@@item_info_url			= 'item-info.xml'
+		@@item_tooltip_url	= 'item-tooltip.xml'
 		
-		@@item_info_url = 'item-info.xml'
-		@@item_tooltip_url = 'item-tooltip.xml'
-
 		@@arena_team_url = 'team-info.xml'
 		
 		@@max_connection_tries = 10
 		
 		@@cache_directory_path = 'cache/'
-
-		# Tiny forum-used race/class icons
-		# @@icon_url = 'http://wowbench.com/images/icons/32x32/'		
-		# http://forums.worldofwarcraft.com/images/icon/class/4.gif
-		# http://forums.worldofwarcraft.com/images/icon/race/3-0.gif
-		# http://forums.worldofwarcraft.com/images/icon/pvpranks/rank_default_0.gif
-		
-		# Spell stuff
-		# http://armory.worldofwarcraft.com/images/icons/21x21/spell_nature_thorns.png
-		# http://armory.worldofwarcraft.com/images/icons/21x21/ability_mount_mountainram.png
-		
-		# Part of the rails plugin stuff?
-		# @@profession_icons = {
-		# 	:alchemy => "Trade_Alchemy.png",
-		# 	:blacksmithing => "Trade_BlackSmithing.png",
-		# 	:engineering => "Trade_Engineering.png",
-		# 	:enchanting => "Trade_Engraving.png",
-		# 	:jewelcrafting => "INV_Hammer_21.png",
-		# 	:herbalism => "Trade_Herbalism.png",
-		# 	:leatherworking => "Trade_LeatherWorking.png",
-		# 	:mining => "Trade_Mining.png",
-		# 	:tailoring => "Trade_Tailoring.png",
-		# 	:skinning => "INV_Weapon_ShortBlade_01.png"
-		# }
-		
-		@@classes = {
-			1 => 'Warrior',
-			2 => 'Paladin',
-			3 => 'Hunter',
-			4 => 'Rogue',
-			5 => 'Priest',
-			#6 => 'Gold Farmer', # there is no class 6
-			7 => 'Shaman',
-			8 => 'Mage',
-			9 => 'Warlock',
-			#10 => 'Purveyor of Baked Goods', # there is no class 10
-			11 => 'Druid'
-		}
 		
-		@@genders = {
-			0 => 'Male',
-			1 => 'Female'
-		}
+		cattr_accessor :armory_url_base, :search_url,
+									 :character_sheet_url, :character_talents_url, :character_skills_url, :character_reputation_url,
+									 :guild_info_url,
+									 :item_info_url, :item_tooltip_url,
+									 :arena_team_url,
+									 :max_connection_tries,
+									 :cache_directory_path
 		
-		@@races = {
-			1 => 'Human',
-			1 => 'Orc',
-			3 => 'Dwarf',
-			4 => 'Night Elf',
-			5 => 'Undead',
-			6 => 'Tauren',
-			7 => 'Gnome',
-			8 => 'Troll',
-			#9 => 'Pandaren', # there is no race 9
-			10 => 'Blood Elf',
-			11 => 'Draenei'
-		}
-
 		@@search_types = {
-			#:all => 'all',	# TODO: All is too complex at the moment, API doesn't return all results in one query
 			:item => 'items',
 			:character => 'characters',
 			:guild => 'guilds',
@@ -116,68 +69,58 @@ module Wowr
 		}
 		
 		@@arena_team_sizes = [2, 3, 5]
-
+		
 		attr_accessor :character_name, :guild_name, :realm, :locale, :lang, :caching, :debug
 		
-		# You can set up the API with an optional default guild and realm
-		# These will be used in all your API requests unless you specify otherwise
-		# For item requests, the locale will not matter in results, but may affect the speed of replies
-		# Caching is off by default
-		# TODO: are these nil declarations pointless?
-		# :character_name => nil,
-		# 													:guild_name => nil,
-		# 													:realm => nil,
-		# 													:locale => 'us',
-		# 													:caching => false,
-		# 													:debug => false
+		
+		# Constructor
+		# Accepts an optional hash of parameters to create defaults for all API requests
+		# * options (Hash) - Hash used to set default values for all API requests
 		def initialize(options = {})
 			@character_name = options[:character_name]
 			@guild_name			= options[:guild_name]
 			@realm					= options[:realm]
-			@locale					= options[:locale] || :us
-			@caching				= options[:caching]
-			
-			if (options[:lang].nil?)
-				@lang = 'default'
-			else
-				@lang					= options[:lang]
-			end
-						
-			@debug					= options[:debug]
+			@locale					= options[:locale] || 'us'
+			@caching				= options[:caching] == nil ? true : false
+			@lang						= options[:lang].nil? ? 'default' : options[:lang]
+			@debug					= options[:debug] || false
 		end
 		
 		
-		# def self.test
-		# 	puts @debug
-		# 	puts @caching
-		# 	puts @locale
-		# end
-		
-				
 		# General-purpose search
-		# All specific searches are wrappers around this method.
-		# Caching is disabled for searching
-		def search(options = {:search => nil, :type => nil})
+		# All specific searches are wrappers around this method. Best to use those instead.
+		# Returns an array of results of the type requested (Wowr::Classes::SearchCharacter etc.) or an empty array.
+		# Searches across all realms.
+		# Caching is disabled for searching.
+		# * string (String) Search string
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def search(string, options = {})
+			if (string.is_a?(Hash))
+				options = string
+			else
+				options.merge!(:search => string)
+			end
+			
 			options = merge_defaults(options)
 			
-			if @@search_types.include? options[:type]
-				raise Wowr::Exceptions::InvalidSearchType.new
+			if options[:search].nil? || options[:search].empty?
+				raise Wowr::Exceptions::NoSearchString.new
 			end
 			
-			if options[:search].nil?
-				raise Wowr::Exceptions::NoSearchString.new
+			if !@@search_types.has_value?(options[:type])
+				raise Wowr::Exceptions::InvalidSearchType.new(options[:type])
 			end
 			
 			options.merge!(:caching => false)
-			
+			options.delete(:realm) # all searches are across realms
+						
 			xml = get_xml(@@search_url, options)
 			
 			results = []
-			
+						
 			if (xml) && (xml%'armorySearch') && (xml%'armorySearch'%'searchResults')
 				case options[:type]
 					
-					# TODO: Filter stuff
 					when @@search_types[:item]
 						(xml%'armorySearch'%'searchResults'%'items'/:item).each do |item|
 							results << Wowr::Classes::SearchItem.new(item)
@@ -185,17 +128,17 @@ module Wowr
 					
 					when @@search_types[:character]
 						(xml%'armorySearch'%'searchResults'%'characters'/:character).each do |char|
-							results << Wowr::Classes::Character.new(char)
+							results << Wowr::Classes::SearchCharacter.new(char, self)
 						end
 					
 					when @@search_types[:guild]
 						(xml%'armorySearch'%'searchResults'%'guilds'/:guild).each do |guild|
-							results << Wowr::Classes::Guild.new(guild)
+							results << Wowr::Classes::SearchGuild.new(guild)
 						end
 					
 					when @@search_types[:arena_team]
 						(xml%'armorySearch'%'searchResults'%'arenaTeams'/:arenaTeam).each do |team|
-							results << Wowr::Classes::ArenaTeam.new(team)
+							results << Wowr::Classes::SearchArenaTeam.new(team)
 						end
 				end
 			end
@@ -204,159 +147,322 @@ module Wowr
 		end
 		
 		
-		
 		# Characters
-		# Note searches go across all realms by default
-		# Caching is disabled for searching
-		def search_characters(options = {:name => nil})
+		# Returns an array of results of Wowr::Classes::SearchCharacter or an empty array.
+		# Searches across all realms.
+		# Caching is disabled for searching.
+		# Parameters
+		# * name (String) Name of the character to search for
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def search_characters(name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:search => name)
+			end
+			
 			options.merge!(:type => @@search_types[:character])
 			return search(options)
 		end
 		
-		def get_character_sheet(options = {})
-			
-			options = {:character_name => @character_name}.merge(options) if (!@character_name.nil?)
+		
+		# Get the full details of a character.
+		# Requires realm.
+		# * name (String) Name of the character to get, defaults to that specified in constructor
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_character(name = @character_name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:character_name => name)
+				
+				# TODO check
+				options = {:character_name => @character_name}.merge(options) if (!@character_name.nil?)
+			end
 			
 			options = merge_defaults(options)
-					
-			xml = get_xml(@@character_sheet_url, options)
-			
-			# resist_types = ['arcane', 'fire', 'frost', 'holy', 'nature', 'shadow']
-			# @resistances = {}
-			# resist_types.each do |res|
-			# 	@resistances[res] = Wowr::Classes::Resistance.new(xml%'resistances'%res)
-			# end
-			# puts @resistances.to_yaml
-			return Wowr::Classes::CharacterSheet.new(xml)
+			
+			if options[:character_name].nil? || options[:chracter_name] == ""
+				raise Wowr::Exceptions::CharacterNameNotSet.new
+			elsif options[:realm].nil? || options[:realm] == ""
+				raise Wowr::Exceptions::RealmNotSet.new
+			end
+			
+			character_sheet = get_xml(@@character_sheet_url, options)
+			character_skills = get_xml(@@character_skills_url, options)
+			character_reputation = get_xml(@@character_reputation_url, options)
+			
+			if true
+				return Wowr::Classes::FullCharacter.new(character_sheet,
+																								character_skills,
+																								character_reputation,
+																								self)
+			else
+				raise Wowr::Excceptions::CharacterNotFound.new(options[:character_name])
+			end
 		end
 		
 		
+		# DEPRECATED
+		# See get_character
+		def get_character_sheet(name = @character_name, options = {})
+			return get_character(name, options)
+		end
+
+		# TODO
+		# def get_character_skills
+		# 	
+		# end
+		# 
+		# def get_character_reputation
+		# 	
+		# end
+		
 		
-		# Guilds
-		# Note searches go across all realms by default
-		# Caching is disabled for searching
-		def search_guilds(options = {:search => nil})
-			options.merge!(:type => @@search_types[:guild],
-										 :caching => false)
+		# Find all guilds with the given string, return array of Wowr::Classes::SearchGuild.
+		# Searches across all realms.
+		# Caching is disabled for searching.
+		# * name (String) Name of the guild to search for
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def search_guilds(name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:search => name)
+			end
+			options.delete(:realm)
 			
+			options.merge!(:type => @@search_types[:guild])
 			return search(options)
 		end
 		
-		def get_guild(options = {})
-			# overwrite default with parameters, but only if the defaults aren't blank
-			options = {:guild_name => @guild_name}.merge(options) if (!@guild_name.nil?)
+		
+		# Get the guild details.
+		# Guild name is optional, assuming it's set in the api constructor.
+		# Requires realm.
+		# * name (String) Name of the guild to retrieve, defaults to that specified in constructor
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_guild(name = @guild_name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:guild_name => name)
+			end
 			
 			options = merge_defaults(options)
 			
+			if options[:guild_name].nil? || options[:guild_name] == ""
+				raise Wowr::Exceptions::GuildNameNotSet.new
+			elsif options[:realm].nil? || options[:realm].empty?
+				raise Wowr::Exceptions::RealmNotSet.new
+			end
+			
 			xml = get_xml(@@guild_info_url, options)
-			return Wowr::Classes::Guild.new(xml)
+			
+			if (xml%'guildKey') && !(xml%'guildInfo').children.empty?
+				return Wowr::Classes::FullGuild.new(xml)
+			else
+				raise Wowr::Exceptions::GuildNotFound.new(options[:guild_name])
+			end
 		end
 		
 		
-		# Items
-		# Items are not realm-specific
-		# Caching is disabled for searching
-		def search_items(options = {:search => nil})
+		# Search for items with the specified name.
+		# Returns an array of Wowr::Classes::SearchItem.
+		# Searches across all realms.
+		# Caching is disabled for searching.
+		# * name (String) Name of the item
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def search_items(name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:search => name)
+			end
+			
 			options.merge!(:type => @@search_types[:item])
 			return search(options)
 		end
 		
-		# TODO: Is not finding the item an exception or just return nil?
-		#def get_item(options = {:item_id => nil, :locale => @locale})
+		
+		# Get the full item details (Wowr::Classes::FullItem) with the given id.
+		# Composite of Wowr::Classes::ItemInfo and Wowr::Classes::ItemTooltip data.
+		# Item requests are identical across realms.
+		# * id (Fixnum) ID of the item
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_item(id, options = {})
+			if (id.is_a?(Hash))
+				options = id
+			else
+				options.merge!(:item_id => id)
+			end
+			
+			options = merge_defaults(options)
+			options.delete(:realm)
 			
-			#return Wowr::Classes::ItemTooltip.new(xml%'itemTooltip')
-		#end
+			info = get_xml(@@item_info_url, options)
+			tooltip = get_xml(@@item_tooltip_url, options)
+			
+			if (info%'itemInfo'%'item') && !tooltip.nil?
+				return Wowr::Classes::FullItem.new(info%'itemInfo'%'item', tooltip%'itemTooltip', self)
+			else
+				raise Wowr::Exceptions::ItemNotFound.new(options[:item_id])
+			end
+		end
 		
-		def get_item_info(options = {:item_id => nil})
+		
+		# Get the basic item information Wowr::Classes::ItemInfo.
+		# Item requests are identical across realms.
+		# * id (Fixnum) ID of the item
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_item_info(id, options = {})
+			if (id.is_a?(Hash))
+				options = id
+			else
+				options.merge!(:item_id => id)
+			end
+			
 			options = merge_defaults(options)
+			options.delete(:realm)
 			
 			xml = get_xml(@@item_info_url, options)
+			
 			if (xml%'itemInfo'%'item')
-				return Wowr::Classes::ItemInfo.new(xml%'itemInfo'%'item')
+				return Wowr::Classes::ItemInfo.new(xml%'itemInfo'%'item', self)
 			else
-				return nil
+				raise Wowr::Exceptions::ItemNotFound.new(options[:item_id])
 			end
 		end
 		
-		def get_item_tooltip(options = {:item_id => nil})
+		
+		# Get full item details including stats Wowr::Classes::ItemTooltip.
+		# Item requests are identical across realms.
+		# * id (Fixnum) ID of the item
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_item_tooltip(id, options = {})
+			if (id.is_a?(Hash))
+				options = id
+			else
+				options.merge!(:item_id => id)
+			end
+			
 			options = merge_defaults(options)
+			options.delete(:realm)
 			
 			xml = get_xml(@@item_tooltip_url, options)
 			
-			# tooltip returns empty document when not found
-			if xml.nil?
-				return nil
-				#raise Wowr::Exceptions::ItemNotFound.new("Item not found with id: #{options[:item_id]}")
+			if !xml.nil?
+				return Wowr::Classes::ItemTooltip.new(xml%'itemTooltip')
+			else
+				raise Wowr::Exceptions::ItemNotFound.new(options[:item_id])
 			end
-			return Wowr::Classes::ItemTooltip.new(xml%'itemTooltip')
 		end
 		
 		
-		
-		# Arena Teams
-		# Caching is disabled for searching
-		def search_arena_teams(options = {})
+		# Search for arena teams with the given name of any size.
+		# Returns an array of Wowr::Classes::SearchArenaTeam
+		# Searches across all realms.
+		# Caching is disabled for searching.
+		# * name (String) Name of the arena team to seach for
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def search_arena_teams(name, options = {})
+			if (name.is_a?(Hash))
+				options = name
+			else
+				options.merge!(:search => name)
+			end
+			
 			options.merge!(:type => @@search_types[:arena_team])
 			return search(options)
 		end
 		
-		def get_arena_team(options = {})
+		
+		# Get the arena team of the given name and size, on the specified realm.
+		# Returns Wowr::Classes::FullArenaTeam
+		# Requires realm.
+		# * name (String) Team arena name
+		# * size (Fixnum) Must be 2, 3 or 5
+		# * options (Hash) Optional hash of arguments identical to those used in the API constructor (realm, debug, cache etc.)
+		def get_arena_team(name, size = nil, options = {})
+			if name.is_a?(Hash)
+				options = name
+			elsif size.is_a?(Hash)
+				options = size
+				options.merge!(:team_name => name)
+			else
+				options.merge!(:team_name => name, :team_size => size)
+			end
+			
 			options = merge_defaults(options)
+						
+			if options[:team_name].nil? || options[:team_name].empty?
+				raise Wowr::Exceptions::ArenaTeamNameNotSet.new
+			end
+			
+			if options[:realm].nil? || options[:realm].empty?
+				raise Wowr::Exceptions::RealmNotSet.new
+			end
 			
 			if !@@arena_team_sizes.include?(options[:team_size])
 				raise Wowr::Exceptions::InvalidArenaTeamSize.new("Arena teams size must be: #{@@arena_team_sizes.inspect}")
 			end
 			
 			xml = get_xml(@@arena_team_url, options)
-			return Wowr::Classes::ArenaTeam.new(xml%'arenaTeam')
+			
+			if !(xml%'arenaTeam').children.empty?
+				return Wowr::Classes::ArenaTeam.new(xml%'arenaTeam')
+			else
+				raise Wowr::Exceptions::ArenaTeamNotFound.new(options[:team_name])
+			end
 		end
 		
-		# this is more of a rails-plugin thing
-		# def icon(icon_url)
-		# 	@@icon_url + icon_url
-		# end
-		
 		
-		# Clear the cache, optional filename
+		# Clear the cache, optional directory name.
+		# * cache_path (String) Relative path of the cache directory to be deleted
 		def clear_cache(cache_path = @@cache_directory_path)
 			begin
 				FileUtils.remove_dir(cache_path)
 			rescue Exception => e 
-
+				
 			end
 		end
 		
 		
+		# Return the base url for the armory, e.g. http://eu.wowarmory.com/
+		# * locale (String) The locale, defaults to that specified in the API constructor
+		def base_url(locale = @locale)
+			if locale == 'us'
+				'http://www.' + @@armory_url_base
+			else
+				'http://' + locale + '.' + @@armory_url_base
+			end
+		end
 		
+		
+		protected
+		
+		# Merge the defaults specified in the constructor with those supplied,
+		# overriding any defaults with those supplied
 		def merge_defaults(options = {})
-			# defaults[:name] = @charater_name if @charater_name
-			# defaults[:name] = @charater_name if @charater_name
 			defaults = {}
+			# defaults[:character_name] = @charater_name if @charater_name
+			# defaults[:guild_name]	= @guild_name if @guild_name
 			defaults[:realm] 		= @realm 		if @realm
 			defaults[:locale] 	= @locale 	if @locale
 			defaults[:lang] 		= @lang 		if @lang
 			defaults[:caching] 	= @caching 	if @caching
 			defaults[:debug] 		= @debug 		if @debug
-
-			# defaults = {:realm			=> @realm,
-			# 						:locale			=> @locale,
-			# 						:lang 			=> @lang,
-			# 						:caching		=> @caching,
-			# 						:debug			=> @debug}
 			
 			# overwrite defaults with any given options
 			defaults.merge!(options)
 		end
 		
-		
-		protected
-		
-		# TODO: pretty damn hacky
+		# Return an Hpricot document for the given URL
+		# TODO: Tidy up?
 		def get_xml(url, options = {})
-			# puts options.to_yaml
 			
 			# better way of doing this?
-			# Map custom keys to the HTTP request values 
+			# Map custom keys to the HTTP request values
 			reqs = {
 				:character_name => 'n',
 				:realm => 'r',
@@ -370,122 +476,72 @@ module Wowr
 			
 			params = []
 			options.each do |key, value|
-				if reqs[key]
-					params << "#{reqs[key]}=#{u(value)}"
-				end
-			end
-			
-			if params.size > 0
-				query = '?' + params.join('&')
+				params << "#{reqs[key]}=#{u(value)}" if reqs[key]
 			end
 			
-			# locale = options[:locale] || @locale
+			query = '?' + params.join('&') if params.size > 0
 			
 			base = self.base_url(options[:locale])
 			full_query = base + url + query
 			
-			if options[:debug]
-				puts full_query
-			end
+			puts full_query if options[:debug]
 			
 			if options[:caching]
 				response = get_cache(full_query, options)
 			else
-				response = http_request(full_query)
+				response = http_request(full_query, options)
 			end
-			
-			if options[:debug]
-				# puts response
-			end
-			
+						
 			doc = Hpricot.XML(response)
-			begin
-				errors = doc.search("*[@errCode]")
-				#errors.to_yaml
-				if errors.size > 0
-					errors.each do |error|
-						raise Wowr::Exceptions::raise_me(error[:errCode])
-					end
-				# elsif (doc%'page').nil?
-				# 	puts full_query
-				# 	puts response
-				# 	raise Wowr::Exceptions::EmptyPage
-				else
-					return (doc%'page')
+			errors = doc.search("*[@errCode]")
+			if errors.size > 0
+				errors.each do |error|
+					raise Wowr::Exceptions::raise_me(error[:errCode], options)
 				end
-			rescue Exception => e 
-				$stderr.puts "Fatal error ((#{e.to_s})): Couldn't search the XML document."
-				$stderr.puts doc
-				exit 1
+			elsif (doc%'page').nil?
+				raise Wowr::Exceptions::EmptyPage
+			else
+				return (doc%'page')
 			end
-			
 		end
 		
-		# TODO Rename
+		# Perform an HTTP request and return the contents of the document
 		def http_request(url, options = {})
-			
-			req = Net::HTTP::Get.new(url)#, headers)
-			req["user-agent"] = "Mozilla/5.0 Gecko/20070219 Firefox/2.0.0.2"
+			req = Net::HTTP::Get.new(url)
+			req["user-agent"] = "Mozilla/5.0 Gecko/20070219 Firefox/2.0.0.2" # ensure returns XML
 			req["cookie"] = "cookieMenu=all; cookieLangId=" + options[:lang] + "; cookies=true;"
 			
 			uri = URI.parse(url)
 			
 		  http = Net::HTTP.new(uri.host, uri.port)
-		
+			
 			begin
-		
 			  http.start do
 			    res = http.request req
-					response = res.body
+					# response = res.body
+					
+					tries = 0
+					response = case res
+						when Net::HTTPSuccess, Net::HTTPRedirection
+							res.body
+						else
+							tries += 1
+							if tries > @@max_connection_tries
+								raise Wowr::Exceptions::NetworkTimeout.new('Timed out')
+							else
+								retry
+							end
+						end
 			  end
 			rescue 
 				raise Wowr::Exceptions::ServerDoesNotExist.new('Specified server at ' + url + ' does not exist.');
 			end
-			
-			# tries = 0
-			# 			response = case res
-			# 			when Net::HTTPSuccess, Net::HTTPRedirection
-			# 				res.body
-			# 			else
-			# 				tries += 1
-			# 				if tries > @@max_connection_tries
-			# 					raise Wowr::Exceptions::NetworkTimeout.new('Timed out')
-			# 				else
-			# 					retry
-			# 				end
-			# 			end
-			
-			
-			#response = res.body
-			
-			# while
-			# 				tries += 1
-			# 				if tries > @@max_connection_tries
-			# 					raise Wowr::Exceptions::NetworkTimeout.new('Timed out')
-			# 				else
-			# 					retry
-			# 				end
-			# 			end
-			# 			
-			# 			begin
-			# 				res = Net::HTTP.new(uri.host, uri.port).start {|http| http.request(req) }
-			# 			rescue Timeout::Error => e
-			# 				retry  
-			# 				#raise Wowr::Exceptions::NetworkTimeout.new('Timed out')
-			# 			end
-			# 			
-			# 			tries = 0
-			# response = case res
-			# when Net::HTTPSuccess, Net::HTTPRedirection
-			# 	res.body
-			# else
-			# 	
-			# end
 		end
 		
 		
+		# Translate the specified URL to the cache location, and return the file
+		# If the cache does not exist, get the contents using http_request and create it
 		def get_cache(url, options = {})
-			
 			path = @@cache_directory_path + options[:lang] + '/' + url_to_filename(url)
 			
 			# file doesn't exist, make it
@@ -494,25 +550,19 @@ module Wowr
 					puts 'Cache doesn\'t exist, making: ' + path
 				end
 				
+				# make sure dir exists
 				FileUtils.mkdir_p(localised_cache_path(options[:lang])) unless File.directory?(localised_cache_path(options[:lang]))
 				
-				# TODO: Hacky
-				# FileUtils.mkdir_p(@@cache_directory_path + 'us/') unless File.directory?(@@cache_directory_path + 'us/')
-				# FileUtils.mkdir_p(@@cache_directory_path + 'eu/') unless File.directory?(@@cache_directory_path + 'eu/')
-				
 				xml_content = http_request(url, options)
 				
 				# write the cache
 				file = File.open(path, File::WRONLY|File::TRUNC|File::CREAT)
-				#file = File.open(path, 'w')
 				file.write(xml_content)
 				file.close
 			
 			# file exists, return the contents
 			else
-				if options[:debug]
-					puts 'Cache already exists, read: ' + path
-				end
+				puts 'Cache already exists, read: ' + path if options[:debug]
 				
 				file = File.open(path, 'r')
 				xml_content = file.read
@@ -523,41 +573,21 @@ module Wowr
 		
 		
 		
-		# :nodoc:
-		# remove http://
+		# remove http://*.wowarmory.com/ leaving just xml file part and request parameters
 		# Kind of assuming incoming URL is the same as the current locale
-		def url_to_filename(url)
-			path = url[7..-1]
-			
-			
-			path = url.gsub(base_url, '')
-			# if (url.include?(@@armory_url))
-			# 	path = 'us/' + url.gsub(@@eu_armory_url, '')
-			# elsif (url.include?(@@eu_armory_url))
-			# 	path = 'eu/' + url.gsub(@@eu_armory_url, '')
-			# end
-			# 
-			return path
+		def url_to_filename(url) #:nodoc:
+			return url.gsub(base_url, '')
 		end
 		
 		
-		def localised_cache_path(lang = @lang)
-			@@cache_directory_path + lang
-		end
-		
 		
-		# :nodoc:
-		def base_url(locale = @locale)
-			if locale == :us
-				'http://www.' + @@armory_url_base
-			else
-				'http://' + locale + '.' + @@armory_url_base
-			end
+		def localised_cache_path(lang = @lang) #:nodoc:
+			return @@cache_directory_path + lang
 		end
 		
 		
-		# :nodoc:
-		def u(str)
+		
+		def u(str) #:nodoc:
 			if str.instance_of?(String)
 				return CGI.escape(str)
 			else