steam-condenser 0.14.0 → 1.0.1

data/lib/steam/community/l4d/l4d2_weapon.rb

@@ -1,22 +1,36 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 require 'steam/community/l4d/abstract_l4d_weapon'
 
+# This class represents the statistics of a single weapon for a user in
+# Left4Dead 2
+#
+# @author Sebastian Staudt
 class L4D2Weapon
 
   include AbstractL4DWeapon
 
-  attr_reader :damage, :weapon_group
+  # Returns the amount of damage done by the player with this weapon
+  #
+  # @return [Fixnum] The damage done by this weapon
+  attr_reader :damage
+
+  # Returns the weapon group this weapon belongs to
+  #
+  # @return [String] The group this weapon belongs to
+  attr_reader :weapon_group
 
-  # Creates a new instance of L4D2Weapon based on the assigned XML data
+  # Creates a new instance of a weapon based on the given XML data
+  #
+  # @param [REXML::Element] weapon_data The XML data of this weapon
   def initialize(weapon_data)
     super weapon_data
 
     @damage          = weapon_data.elements['damage'].text.to_i
-    @kill_percentage = weapon_data.elements['pctkills'].text
+    @kill_percentage = weapon_data.elements['pctkills'].text.to_f * 0.01
     @weapon_group    = weapon_data.attribute('group')
   end
 

data/lib/steam/community/l4d/l4d_explosive.rb

@@ -1,15 +1,21 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 require 'steam/community/game_weapon'
 
+# This class represents the statistics of a single explosive weapon for a user
+# in Left4Dead
+#
+# @author Sebastian Staudt
 class L4DExplosive
 
   include GameWeapon
 
-  # Creates a new instance of L4DExplosive based on the assigned XML data
+  # Creates a new instance of an explosivve based on the given XML data
+  #
+  # @param [REXML::Element] weapon_data The XML data of this explosive
   def initialize(weapon_data)
     super weapon_data
 
@@ -17,7 +23,9 @@ class L4DExplosive
     @shots = weapon_data.elements['thrown'].text.to_i
   end
 
-  # Returns the average number of kills for one shot of this explosive.
+  # Returns the average number of killed zombies for one shot of this explosive
+  #
+  # @return [Float] The average number of kills per shot
   def avg_kills_per_shot
     1 / avg_shots_per_kill
   end

data/lib/steam/community/l4d/l4d_map.rb

@@ -1,20 +1,48 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
-# L4DMap holds statistical information about maps played by a player in
-# Survival mode of Left4Dead.
+# This class holds statistical information about a map played by a player in
+# Survival mode of Left4Dead
+#
+# @author Sebastian Staudt
 class L4DMap
 
-  attr_reader :best_time, :id, :medal, :name, :times_played
+  # Returns the best survival time of this player on this map
+  #
+  # @return [Float] The best survival time of this player on this map
+  attr_reader :best_time
+
+  # Returns the ID of this map
+  #
+  # @return [String] The ID of this map
+  attr_reader :id
+
+  # Returns the highest medal this player has won on this map
+  #
+  # @return [Fixnum] The highest medal won by this player on this map
+  attr_reader :medal
+
+  # Returns the name of the map
+  #
+  # @return [String] The name of the map
+  attr_reader :name
+
+  # Returns the number of times this map has been played by this player
+  #
+  # @return [Fixnum] The number of times this map has been played
+  attr_reader :times_played
 
   GOLD   = 1
   SILVER = 2
   BRONZE = 3
   NONE   = 0
 
-  # Creates a new instance of L4DMap based on the assigned XML data
+  # Creates a new instance of a Left4Dead Survival map based on the given
+  # XML data
+  #
+  # @param [REXML::Element] map_data The XML data for this map
   def initialize(map_data)
     @best_time    = map_data.elements['besttimeseconds'].text.to_f
     @id           = map_data.name

data/lib/steam/community/l4d/l4d_stats.rb

@@ -1,41 +1,54 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 require 'steam/community/l4d/abstract_l4d_stats'
 require 'steam/community/l4d/l4d_explosive'
 require 'steam/community/l4d/l4d_map'
 require 'steam/community/l4d/l4d_weapon'
 
+# This class represents the game statistics for a single user in Left4Dead
+#
+# @author Sebastian Staudt
 class L4DStats < GameStats
 
   include AbstractL4DStats
 
-  # Creates a L4DStats object by calling the super constructor with the game
-  # name "l4d".
+  # Creates a `L4DStats` object by calling the super constructor
+  # with the game name `'l4d'`
+  #
+  # @param [String] steam_id The custom URL or 64bit Steam ID of the user
   def initialize(steam_id)
     super steam_id, 'l4d'
   end
 
-  # Returns a Hash of Survival statistics for this user like revived teammates.
-  # If the Survival statistics haven't been parsed already, parsing is done now.
+  # Returns a hash of Survival statistics for this user like revived teammates
+  #
+  # If the Survival statistics haven't been parsed already, parsing is done
+  # now.
+  #
+  # @return [Hash<String, Object>] The stats for the Survival mode
   def survival_stats
     return unless public?
 
     if @survival_stats.nil?
       super
-      @survival_stats['maps'] = {}
+      @survival_stats[:maps] = {}
       @xml_data.elements.each('stats/survival/maps/*') do |map_data|
-        @survival_stats['maps'][map_data.name] = L4DMap.new(map_data)
+        @survival_stats[:maps][map_data.name] = L4DMap.new(map_data)
       end
     end
 
     @survival_stats
   end
 
-  # Returns a Hash of L4DWeapon for this user containing all Left4Dead weapons.
+  # Returns a hash of `L4DWeapon` for this user containing all Left4Dead
+  # weapons
+  #
   # If the weapons haven't been parsed already, parsing is done now.
+  #
+  # @return [Hash<String, Object>] The weapon statistics
   def weapon_stats
     return unless public?
 

data/lib/steam/community/l4d/l4d_weapon.rb

@@ -1,21 +1,25 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 require 'steam/community/l4d/abstract_l4d_weapon'
 
+# This class represents the statistics of a single weapon for a user in
+# Left4Dead
+#
+# @author Sebastian Staudt
 class L4DWeapon
 
   include AbstractL4DWeapon
 
-  attr_reader :accuracy, :headshots_percentage, :kill_percentage
-
-  # Creates a new instance of L4DWeapon based on the assigned XML data
+  # Creates a new instance of a weapon based on the given XML data
+  #
+  # @param [REXML::Element] weapon_data The XML data for this weapon
   def initialize(weapon_data)
     super weapon_data
 
-    @kill_percentage = weapon_data.elements['killpct'].text
+    @kill_percentage = weapon_data.elements['killpct'].text.to_f * 0.01
   end
 
 end

data/lib/steam/community/portal2/portal2_inventory.rb

@@ -7,6 +7,8 @@ require 'steam/community/game_inventory'
 require 'steam/community/portal2/portal2_item'
 
 # Represents the inventory (a.k.a. Robot Enrichment) of a Portal 2 player
+#
+# @author Sebastian Staudt
 class Portal2Inventory
 
   include Cacheable
@@ -14,8 +16,10 @@ class Portal2Inventory
 
   include GameInventory
 
+  # The Steam Application ID of Portal 2
   @@app_id = 620
 
+  # The class representing Portal 2 items
   @@item_class = Portal2Item
 
 end

data/lib/steam/community/portal2/portal2_item.rb

@@ -6,13 +6,20 @@
 require 'steam/community/game_item'
 
 # Represents a Portal 2 item
+#
+# @author Sebastian Staudt
 class Portal2Item
 
   include GameItem
 
+  # The names of the bots available in Portal 2
   BOTS = [ :pbody, :atlas ]
 
-  # Creates a new instance of a Portal2Item with the given data
+  # Creates a new instance of a Portal 2 item with the given data
+  #
+  # @param [Portal2Inventory] inventory The inventory this item is contained in
+  # @param [Hash<Symbol, Object>] item_data The data specifying this item
+  # @raise [WebApiError] on Web API errors
   def initialize(inventory, item_data)
     super
 
@@ -23,11 +30,16 @@ class Portal2Item
   end
 
   # Returns the symbols for each bot this player has equipped this item
+  #
+  # @return [Array<String>] The names of the bots this player has equipped this
+  #         item
   def bots_equipped?
     @equipped.reject { |bot_id, equipped| !equipped }
   end
 
   # Returns whether this item is equipped by this player at all
+  #
+  # @return [Boolean] `true` if the player has equipped this item at all
   def equipped?
     @equipped.has_value? true
   end

data/lib/steam/community/portal2/portal2_stats.rb

@@ -6,20 +6,24 @@
 require 'steam/community/game_stats'
 require 'steam/community/portal2/portal2_inventory'
 
-# The Portal2Stats class represents the game statistics for a single user in
-# Portal 2
+# This class represents the game statistics for a single user in Portal 2
+#
+# @author Sebastian Staudt
 class Portal2Stats < GameStats
 
-  attr_reader :accumulated_points
-
-  # Creates a Portal2Stats object by calling the super constructor with the
-  # game name "portal2"
+  # Creates a `Portal2Stats` object by calling the super constructor with the
+  # game name `'portal2'`
+  #
+  # @param [String, Fixnum] steam_id The custom URL or 64bit Steam ID of the
+  #        user
   def initialize(steam_id)
     super steam_id, 'portal2'
   end
 
   # Returns the current Portal 2 inventory (a.k.a Robot Enrichment) of this
   # player
+  #
+  # @return [TF2Inventory] This player's Portal 2 inventory
   def inventory
     @inventory = Portal2Inventory.new(steam_id64) if @inventory.nil?
     @inventory

data/lib/steam/community/steam_game.rb

@@ -0,0 +1,74 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+# This class represents a game available on Steam
+#
+# @author Sebastian Staudt
+class SteamGame
+
+  @@games = {}
+
+  # Returns the Steam application ID of this game
+  #
+  # @return [Fixnum] The Steam application ID of this game
+  attr_reader :app_id
+
+  # Returns the full name of this game
+  #
+  # @return [String] The full name of this game
+  attr_reader :name
+
+  # Returns the short name of this game (also known as "friendly name")
+  #
+  # @return [String] The short name of this game
+  attr_reader :short_name
+
+  # Creates a new or cached instance of the game specified by the given XML
+  # data
+  #
+  # @param [REXML::Element] game_data The XML data of the game
+  # @see #initialize
+  def self.new(game_data)
+    app_id = game_data.elements['appID'].text.to_i
+    @@games.key?(app_id) ? @@games[app_id] : super(app_id, game_data)
+  end
+
+  # Returns whether this game has statistics available
+  #
+  # @return [Boolean] `true` if this game has stats
+  def has_stats?
+    !@short_name.nil?
+  end
+
+  # Creates a stats object for the given user and this game
+  #
+  # @param [String, Fixnum] steam_id The custom URL or the 64bit Steam ID of
+  #        the user
+  # @return [GameStats] The stats of this game for the given user
+  def user_stats(steam_id)
+    return unless has_stats?
+
+    GameStats.create_game_stats steam_id, @short_name
+  end
+
+  private
+
+  # Creates a new instance of a game with the given data and caches it
+  #
+  # @param [Fixnum] app_id The application ID of the game
+  # @param [REXML::Element] game_data The XML data of the game
+  def initialize(app_id, game_data)
+    @app_id = app_id
+    @name   = game_data.elements['name'].text
+    if game_data.elements['globalStatsLink'].nil?
+      @short_name = nil
+    else
+      @short_name = game_data.elements['globalStatsLink'].text.match(/http:\/\/steamcommunity.com\/stats\/([^?\/]+)\/achievements\//)[1].downcase
+    end
+
+    @@games[@app_id] = self
+  end
+
+end

data/lib/steam/community/steam_group.rb

@@ -1,7 +1,7 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2008-2010, Sebastian Staudt
+# Copyright (c) 2008-2011, Sebastian Staudt
 
 require 'open-uri'
 require 'rexml/document'
@@ -10,14 +10,32 @@ require 'steam/community/cacheable'
 require 'steam/community/steam_id'
 
 # The SteamGroup class represents a group in the Steam Community
+#
+# @author Sebastian Staudt
 class SteamGroup
 
   include Cacheable
   cacheable_with_ids :custom_url, :group_id64
 
-  attr_reader :custom_url, :group_id64
-
-  # Creates a SteamGroup object with the given group ID
+  # Returns the custom URL of this group
+  #
+  # The custom URL is a admin specified unique string that can be used instead
+  # of the 64bit SteamID as an identifier for a group.
+  #
+  # @return [String] The custom URL of this group
+  attr_reader :custom_url
+
+  # Returns this group's 64bit SteamID
+  #
+  # @return [Fixnum] This group's 64bit SteamID
+  attr_reader :group_id64
+
+  # Creates a new `SteamGroup` instance for the group with the given ID
+  #
+  # @param [String, Fixnum] id The custom URL of the group specified by the
+  #        group admin or the 64bit group ID
+  # @param [Boolean] fetch if `true` the groups's data is loaded into the
+  #        object
   def initialize(id, fetch = true)
     begin
       if id.is_a? Numeric
@@ -28,11 +46,15 @@ class SteamGroup
 
       super(fetch)
     rescue REXML::ParseException
-      raise SteamCondenserException.new('Group could not be loaded.')
+      raise SteamCondenserError, 'Group could not be loaded.'
     end
   end
 
-  # Returns the URL to the group's Steam Community page
+  # Returns the base URL for this group's page
+  #
+  # This URL is different for groups having a custom URL.
+  #
+  # @return [String] The base URL for this group
   def base_url
     if @custom_url.nil?
       "http://steamcommunity.com/gid/#{@group_id64}"
@@ -41,7 +63,12 @@ class SteamGroup
     end
   end
 
-  # Parses the data about this groups members
+  # Loads the members of this group
+  #
+  # This might take several HTTP requests as the Steam Community splits this
+  # data over several XML documents if the group has lots of members.
+  #
+  # @see Cacheable#fetch
   def fetch
     @members = []
     page = 0
@@ -62,10 +89,13 @@ class SteamGroup
     super
   end
 
-  # Returns the number of members this group has.
-  # If the members have already been fetched with +fetch_members+ the size of
-  # the member array is returned. Otherwise the group size is separately
-  # fetched.
+  # Returns the number of members this group has
+  #
+  # If the members have already been fetched the size of the member array is
+  # returned. Otherwise the group size is separately fetched without needing
+  # multiple requests for big groups.
+  #
+  # @return [Fixnum] The number of this group's members
   def member_count
     if @members.nil?
       url = open("#{base_url}/memberslistxml", {:proxy => true})
@@ -76,7 +106,11 @@ class SteamGroup
   end
 
   # Returns the members of this group
-  # Calls +fetch+ if the members haven't been fetched already.
+  #
+  # If the members haven't been fetched yet, this is done now.
+  #
+  # @return [Array<SteamId>] The Steam ID's of the members of this group
+  # @see #fetch
   def members
     fetch if @members.nil? || @members[0].nil?
     @members