steam-condenser 0.14.0 → 1.0.1

data/lib/steam/community/game_achievement.rb

@@ -1,29 +1,57 @@
-# 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 'json'
+require 'multi_json'
 
 require 'steam/community/web_api'
 
 # The GameAchievement class represents a specific achievement for a single game
 # and for a single user
+#
+# It also provides the ability to load the global unlock percentages of all
+# achievements of a specific game.
+#
+# @author Sebastian Staudt
 class GameAchievement
 
-  attr_reader :app_id, :name, :steam_id64, :timestamp
+  # Return the unique Steam Application ID of the  game this achievement
+  # belongs to
+  #
+  # @return [Fixnum] The Steam Application ID of this achievement's game
+  attr_reader :app_id
+
+  # Returns the name of this achievement
+  #
+  # @return [String] The name of this achievement
+  attr_reader :name
+
+  # Returns the 64bit SteamID of the user who owns this achievement
+  #
+  # @return [Fixnum] The 64bit SteamID of this achievement's owner
+  attr_reader :steam_id64
 
-  # Loads the global unlock percentages of all achievements for the given game
+  # Returns the time this achievement has been unlocked by its owner
   #
-  # [+app_id+] The unique Steam Application ID of the game (e.g. +440+ for
-  #            Team Fortress 2). See
-  #            http://developer.valvesoftware.com/wiki/Steam_Application_IDs
-  #            for all application IDs
+  # @return [Time] The time this achievement has been unlocked
+  attr_reader :timestamp
+
+  # Loads the global unlock percentages of all achievements for the game with
+  # the given Steam Application ID
+  #
+  # @param [Fixnum] app_id The unique Steam Application ID of the game (e.g.
+  #        `440` for Team Fortress 2). See
+  #         http://developer.valvesoftware.com/wiki/Steam_Application_IDs for
+  #         all application IDs
+  # @raise [WebApiError] if the request to Steam's Web API fails
+  # @return [Hash<Symbol, Float>] The symbolic achievement names with their
+  #         corresponding unlock percentages
   def self.global_percentages(app_id)
     percentages = {}
 
-    data = WebApi.json('ISteamUserStats', 'GetGlobalAchievementPercentagesForApp', 1, { :gameid => app_id })
-    JSON.parse(data, { :symbolize_names => true })[:achievementpercentages][:achievements][:achievement].each do |percentage|
+    data = WebApi.json('ISteamUserStats', 'GetGlobalAchievementPercentagesForApp', 2, { :gameid => app_id })
+    MultiJson.decode(data, { :symbolize_keys => true })[:achievementpercentages][:achievements].each do |percentage|
       percentages[percentage[:name].to_sym] = percentage[:percent]
     end
 
@@ -33,13 +61,14 @@ class GameAchievement
   # Creates the achievement with the given name for the given user and game
   # and achievement data
   #
-  # [+steam_id64+]       The 64bit SteamID of the player this achievement
-  #                      belongs to
-  # [+app_id+]           The unique Steam Application ID of the game (e.g.
-  #                      +440+ for Team Fortress 2). See
-  #                      http://developer.valvesoftware.com/wiki/Steam_Application_IDs
-  #                      for all application IDs
-  # [+achievement_data+] The achievement data extracted from JSON
+  # @param [Fixnum] steam_id64 The 64bit SteamID of the player this achievement
+  #        belongs to
+  # @param [Fixnum] app_id The unique Steam Application ID of the game (e.g.
+  #        `440` for Team Fortress 2). See
+  #        http://developer.valvesoftware.com/wiki/Steam_Application_IDs for
+  #        all application IDs
+  # @param [REXML::Element] achievement_data The achievement data extracted
+  #        from XML
   def initialize(steam_id64, app_id, achievement_data)
     @app_id     = app_id
     @name       = achievement_data.elements['name'].text
@@ -52,6 +81,8 @@ class GameAchievement
   end
 
   # Returns whether this achievement has been unlocked by its owner
+  #
+  # @return [Boolean] `true` if the achievement has been unlocked by the user
   def unlocked?
     @unlocked
   end

data/lib/steam/community/game_class.rb

@@ -1,11 +1,22 @@
-# 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
 
-# Super class for classes representing player classes
+# A module implementing basic functionality for classes representing player
+# classes
+#
+# @author Sebastian Staudt
 module GameClass
 
-  attr_reader :name, :play_time
+  # Returns the name of this class
+  #
+  # @return [String] The name of this class
+  attr_reader :name
+
+  # Returns the time in minutes the player has played with this class
+  #
+  # @return [Fixnum] The time this class has been played
+  attr_reader :play_time
 
 end

data/lib/steam/community/game_inventory.rb

@@ -8,9 +8,19 @@ require 'steam/community/game_item'
 require 'steam/community/web_api'
 
 # Provides basic functionality to represent an inventory of player in a game
+#
+# @author Sebastian Staudt
 module GameInventory
 
-  attr_reader :items, :steam_id64
+  # Returns an array of all items in this players inventory.
+  #
+  # @return [Array<GameItem>] All items in the backpack
+  attr_reader :items
+
+  # Returns the 64bit SteamID of the player owning this inventory
+  #
+  # @return [String] The 64bit SteamID
+  attr_reader :steam_id64
 
   @@attribute_schema = {}
 
@@ -20,7 +30,9 @@ module GameInventory
 
   @@schema_language = 'en'
 
-  # Sets the language the schema should be fetched in (default is: +'en'+)
+  # Sets the language the schema should be fetched in (default is: `'en'`)
+  #
+  # @param [String] The ISO 639-1 code of the schema language
   def self.schema_language=(language)
     @@schema_language = language
   end
@@ -28,6 +40,10 @@ module GameInventory
   # Creates a new inventory object for the given AppID and SteamID64. This
   # calls update to fetch the data and create the item instances contained in
   # this players backpack
+  #
+  # @param [Fixnum] steam_id64 The 64bit SteamID of the player to get the
+  #        inventory for
+  # @param [Boolean] fetch_now if `true` the data will be fetched immediately
   def initialize(steam_id64, fetch_now = true)
     @steam_id64 = steam_id64
 
@@ -36,11 +52,15 @@ module GameInventory
 
   # Returns the item at the given position in the inventory. The positions
   # range from 1 to 100 instead of the usual array indices (0 to 99).
+  #
+  # @return [GameItem] The item at the given position in the inventory
   def [](index)
     @items[index - 1]
   end
 
-  # Returns the AppID of the game this inventory class belongs to
+  # Returns the application ID of the game this inventory class belongs to
+  #
+  # @return [Fixnum] The application ID of the game
   def app_id
     self.class.send :class_variable_get, :@@app_id
   end
@@ -48,6 +68,10 @@ module GameInventory
   # Returns the attribute schema
   #
   # The schemas are fetched first if not done already
+  #
+  # @return [Hash<String, Hash<String, Object>>] The attribute schema for the
+  #         game this inventory belongs to
+  # @see #update_schema
   def attribute_schema
     update_schema unless @@attribute_schema.key? app_id
 
@@ -71,6 +95,10 @@ module GameInventory
   # Returns the item schema
   #
   # The schemas are fetched first if not done already
+  #
+  # @return [Hash<Fixnum, Hash<String, Object>>] The item schema for the game
+  #         this inventory belongs to
+  # @see #upde_schema
   def item_schema
     update_schema unless @@item_schema.key? app_id
 
@@ -80,6 +108,9 @@ module GameInventory
   # Returns the quality schema
   #
   # The schemas are fetched first if not done already
+  #
+  # @return [Hash<Fixnum, String>] The quality schema for this game
+  # @see #update_schema
   def qualities
     update_schema unless @@qualities.key? app_id
 
@@ -87,6 +118,8 @@ module GameInventory
   end
 
   # Returns the number of items in the user's inventory
+  #
+  # @return [Fixnum] The number of items in the inventory
   def size
     @items.size
   end
@@ -94,7 +127,7 @@ module GameInventory
   protected
 
   # Updates the item schema (this includes attributes and qualities) using the
-  # +GetSchema+ method of interface +IEconItems_{AppID}+
+  # `GetSchema` method of interface `IEconItems_[AppID]`
   def update_schema
     params = {}
     params[:language] = @@schema_language unless @@schema_language.nil?

data/lib/steam/community/game_item.rb

@@ -5,13 +5,72 @@
 
 require 'steam/community/web_api'
 
-# Provides basic functionality to represent an item in a game
+# A module implementing basic functionality for classes representing an item in
+# a game
+#
+# @author Sebastian Staudt
 module GameItem
 
-  attr_reader :attributes, :backpack_position, :class, :count, :defindex, :id,
-              :level, :name, :quality, :slot, :type
+  # Return the attributes of this item
+  #
+  # @return [Hash<Symbol, Object>] The attributes of this item
+  attr_reader :attributes
+
+  # Returns the position of this item in the player's inventory
+  #
+  # @return [Fixnum] The position of this item in the player's inventory
+  attr_reader :backpack_position
+
+  # Returns the class of this item
+  #
+  # @return [String] The class of this item
+  attr_reader :class
+
+  # Returns the number of items the player owns of this item
+  #
+  # @return [Fixnum] The quanitity of this item
+  attr_reader :count
+
+  # Returns the index where the item is defined in the schema
+  #
+  # @return [Fixnum] The schema index of this item
+  attr_reader :defindex
+
+  # Returns the ID of this item
+  #
+  # @return [Fixnum] The ID of this item
+  attr_reader :id
+
+  # Returns the level of this item
+  #
+  # @return [Fixnum] The level of this item
+  attr_reader :level
+
+  # Returns the level of this item
+  #
+  # @return [String] The level of this item
+  attr_reader :name
+
+  # Returns the quality of this item
+  #
+  # @return [String] The quality of this item
+  attr_reader :quality
+
+  # Returns the slot where this item can be equipped in or `nil` if this item
+  # cannot be equipped
+  #
+  # @return [String] The slot where this item can be equipped in
+  attr_reader :slot
+
+  # Returns the type of this item
+  #
+  # @return [String] The type of this item
+  attr_reader :type
 
   # Creates a new instance of a GameItem with the given data
+  #
+  # @param [GameInventory] inventory The inventory this item is contained in
+  # @param [Hash<Symbol, Object>] item_data The data representing this item
   def initialize(inventory, item_data)
     @defindex          = item_data[:defindex]
     @backpack_position = item_data[:inventory] & 0xffff
@@ -31,6 +90,8 @@ module GameItem
   end
 
   # Returns whether this item is tradeable
+  #
+  # @return [Boolean] `true` if this item is tradeable
   def tradeable?
     @tradeable
   end

data/lib/steam/community/game_stats.rb

@@ -8,15 +8,57 @@ require 'rexml/document'
 
 require 'steam/community/game_achievement'
 
-# The GameStats class represents the game statistics for a single user and a
-# specific game
+# This class represents the game statistics for a single user and a specific
+# game
+#
+# It is subclassed for individual games if the games provide special statistics
+# that are unique to this game.
+#
+# @author Sebastian Staudt
 class GameStats
 
-  attr_reader :app_id, :custom_url, :game_friendly_name, :game_name,
-              :hours_played, :privacy_state, :steam_id64
-
-  # Creates a GameStats (or one of its subclasses) object for the given user
-  # depending on the game selected
+  # Returns the Steam application ID of the game these stats belong to
+  #
+  # @return [Fixnum] The Steam application ID of the game
+  attr_reader :app_id
+
+  # Returns the custom URL of the player these stats belong to
+  #
+  # @return [String] The custom URL of the player
+  attr_reader :custom_url
+
+  # Returns the friendly name of the game these stats belong to
+  #
+  # @return [String ]The frienldy name of the game
+  attr_reader :game_friendly_name
+
+  # Returns the full name of the game these stats belong to
+  #
+  # @return [String] The name of the game
+  attr_reader :game_name
+
+  # Returns the number of hours this game has been played by the player
+  #
+  # @return [String] The number of hours this game has been played
+  attr_reader :hours_played
+
+  # Returns the privacy setting of the Steam ID profile
+  #
+  # @return [String] The privacy setting of the Steam ID
+  attr_reader :privacy_state
+
+  # Returns the 64bit numeric SteamID of the player these stats belong to
+  #
+  # @return [Fixnum] The 64bit numeric SteamID of the player
+  attr_reader :steam_id64
+
+  # Creates a `GameStats` (or one of its subclasses) instance for the given
+  # user and game
+  #
+  # @param [String, Fixnum] steam_id The custom URL or the 64bit Steam ID of
+  #        the user
+  # @param [String] game_name The friendly name of the game
+  # @return [GameStats] The game stats object for the given user and game
   def self.create_game_stats(steam_id, game_name)
     case game_name
       when 'alienswarm'
@@ -48,8 +90,13 @@ class GameStats
     end
   end
 
-  # Creates a GameStats object and fetches data from the Steam Community for
+  # Creates a `GameStats` object and fetches data from the Steam Community for
   # the given user and game
+  #
+  # @param [String, Fixnum] id The custom URL or the 64bit Steam ID of the
+  #        user
+  # @param [String] game_name The friendly name of the game
+  # @raise [SteamCondenserError] if the stats cannot be fetched
   def initialize(id, game_name)
     if id.is_a? Numeric
       @steam_id64 = id
@@ -62,7 +109,7 @@ class GameStats
     @xml_data = REXML::Document.new(open(url, {:proxy => true}).read).root
 
     error = @xml_data.elements['error']
-    raise SteamCondenserException.new(error.text) unless error.nil?
+    raise SteamCondenserError, error.text unless error.nil?
 
     @privacy_state = @xml_data.elements['privacyState'].text
     if public?
@@ -74,8 +121,11 @@ class GameStats
     end
   end
 
-  # Returns the achievements for this stats' user and game. If the achievements
-  # haven't been parsed already, parsing is done now.
+  # Returns the achievements for this stats' user and game
+  #
+  # If the achievements' data hasn't been parsed yet, parsing is done now.
+  #
+  # @return [Array<GameAchievement>] All achievements belonging to this game
   def achievements
     return unless public?
 
@@ -91,20 +141,32 @@ class GameStats
     @achievements
   end
 
-  # Returns the count of achievements done by this player. If achievements
-  # haven't been parsed yet, parsing is done now.
+  # Returns the number of achievements done by this player
+  #
+  # If achievements haven't been parsed yet for this player and this game,
+  # parsing is done now.
+  #
+  # @return [Fixnum] The number of achievements completed
+  # @see #achievements
   def achievements_done
     achievements if @achievements_done.nil?
     @achievements_done
   end
 
-  # Returns a float value representing the percentage of achievements done by
-  # this player. If achievements haven't been parsed yet, parsing is done now.
+  # Returns the percentage of achievements done by this player
+  #
+  # If achievements haven't been parsed yet for this player and this game,
+  # parsing is done now.
+  #
+  # @return [Float] The percentage of achievements completed
+  # @see #achievements_done
   def achievements_percentage
     achievements_done.to_f / @achievements.size
   end
 
-  # Returns the base URL for this Steam Communtiy object
+  # Returns the base Steam Communtiy URL for the stats contained in this object
+  #
+  # @return [String] The base URL used for queries on these stats
   def base_url
     if @custom_url.nil?
       "http://steamcommunity.com/profiles/#{@steam_id64}/stats/#{@game_friendly_name}"
@@ -113,6 +175,9 @@ class GameStats
     end
   end
 
+  # Returns whether this Steam ID is publicly accessible
+  #
+  # @return [Boolean] `true` if this Steam ID is publicly accessible
   def public?
     @privacy_state == 'public'
   end