quakelive_api 0.0.1

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.ruby-version
+.rvmrc
+.ruby-gemset
+coverage/

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in quakelive_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Rafal Wojsznis
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+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.

data/README.md

@@ -0,0 +1,76 @@
+[![Code Climate](https://codeclimate.com/github/emq/quakelive_api.png)](https://codeclimate.com/github/emq/quakelive_api) [![Build Status](https://travis-ci.org/emq/quakelive_api.png?branch=master)](https://travis-ci.org/emq/quakelive_api)
+
+# QuakeliveApi
+
+This gem fetches (basic) publicly available data from [QuakeLive site][1]. Unfortunately currently there is no real API provided by ID so we're forced to parse html to get what we can. It will go down in flames if QL changes its internal html structure, so be prepared for that too.
+
+The dirty job is made under `Parser` module (nothing pretty there, but response from QL is not pretty as well).
+
+It is currently used in production environment, but consider it as work in progress for you own safety.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'quakelive_api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install quakelive_api
+
+## Usage
+
+There is a main class called `QuakeliveApi::Profile` that will accept *player_name* (nickname from QL) as argument.
+This class delegates its methods to other classes that *speaks* with quakelive.com. Each method call will execute a single query (using standard `Net::HTTP` Ruby library), parse the response using `Nokogiri` and returns the result (cached as instance variables).
+
+Usage:
+
+``` ruby
+profile = QuakeliveApi::Profile.new(player_name)
+
+profile.summary           # instance variable of QuakeliveApi::Profile::Summary
+profile.statistics        # instance variable of QuakeliveApi::Profile::Statistics
+profile.awards_milestones # instance variable of QuakeliveApi::Profile::Awards::CareerMilestones
+profile.awards_experience # instance variable of QuakeliveApi::Profile::Awards::Experience
+profile.awards_skillz     # instance variable of QuakeliveApi::Profile::Awards::MadSkillz
+profile.awards_social     # instance variable of QuakeliveApi::Profile::Awards::SocialLife
+profile.awards_success    # instance variable of QuakeliveApi::Profile::Awards::SweetSuccess
+
+# there is also helper method called .each_award that will execute given block for all awards
+# Note: those classes can be used separately (the initializer argument is the same)
+
+# calling those methods may raise:
+# - QuakeliveApi::Error::PlayerNotFound on invalid player_name
+# - QuakeliveApi::Error::RequestError when ql site returns 'An Error Has Occurred' page
+```
+
+### Methods (should be self-explanatory)
+
+- `QuakeliveApi::Profile::Summary`: country, nick, clan, model, memeber_since, last_game, time_played, wins, accuracy, losses, quits, frags, deaths, hits, shots, favourite, recent_awards, recent_games, recent_competitors
+
+- `QuakeliveApi::Profile::Statistics` - weapons, records (each is array of _Struct_ objects)
+
+- `QuakeliveApi::Profile::Awards` (each kind) - earned, unearned (same as above)
+
+## Known issues
+
+- I noticed that sometimes QL site returns incomplete response for awards, that will trigger exception inside parser, unfortunately I can't quite narrow it down atm :(
+
+## TODO
+
+- RDoc?
+- it would be great to provide support for all stats like matches, competitors, friends etc.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+[1]: http://quakelive.com

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r quakelive_api"
+end
+
+task default: :test

data/lib/quakelive_api/base.rb

@@ -0,0 +1,52 @@
+module QuakeliveApi
+  class Base
+    attr_accessor :player_name
+
+    def initialize(player_name)
+      @player_name = player_name
+
+      set_parser Nokogiri::HTML(get)
+      setup_variables!
+    end
+
+    def inspect
+      "#{self.class}:#{object_id}\n" + instance_variables.map do |v|
+        next if v.to_s == "@parser"
+        "#{v}=#{instance_variable_get(v).inspect}"
+      end.compact.join("\n")
+    end
+
+    private
+
+      def get
+        Net::HTTP.get(URI.parse(URI::encode("#{QuakeliveApi.site}#{url}")))
+      end
+
+      def url
+        raise NotImplementedError
+      end
+
+      def parser
+        @parser
+      end
+
+      def set_parser(document)
+        @parser ||= ::QuakeliveApi::Parser.const_get(self.class.class_name).new(document)
+      end
+
+      def self.class_name
+        name.split('::').last
+      end
+
+      def setup_variables!
+        raise Error::PlayerNotFound if parser.invalid_player?
+        raise Error::RequestError   if parser.request_error?
+
+        setup_variables
+      end
+
+      def setup_variables
+        raise NotImplementedError
+      end
+  end
+end

data/lib/quakelive_api/error/player_not_found.rb

@@ -0,0 +1,6 @@
+module QuakeliveApi
+  module Error
+    class PlayerNotFound < StandardError
+    end
+  end
+end

data/lib/quakelive_api/error/request_error.rb

@@ -0,0 +1,6 @@
+module QuakeliveApi
+  module Error
+    class RequestError < StandardError
+    end
+  end
+end

data/lib/quakelive_api/game_time.rb

@@ -0,0 +1,34 @@
+module QuakeliveApi
+  class GameTime
+    attr_accessor :ranked, :unranked
+
+    class Interval < Struct.new(:seconds, :minutes, :hours, :days)
+      def total
+        members.sum { |m| send(m).send(m) } # see what I did there?
+      end
+    end
+
+    # accepts unparsed string directly from QL profile, for example:
+    # * Ranked Time: 21:50 Unranked Time: 04:54
+    # * Ranked Time: 50.06:18:30 Unranked Time: 02:31:02
+    def initialize(unparsed_string)
+      matches = unparsed_string.match(/Ranked Time: ([\d:.]+) Unranked Time: ([\d:.]+)/)
+      return unless matches
+
+      @ranked   = reverse_match(matches[1])
+      @unranked = reverse_match(matches[2])
+    end
+
+    def ==(other)
+      return ranked == other.ranked && unranked == other.unranked
+    end
+
+    private
+
+      def reverse_match(string)
+        attrs = string.split(/\.|:/).reverse.map { |a| a.to_i }
+        (4 - attrs.size).times { attrs << 0 }
+        Interval.new(*attrs)
+      end
+  end
+end

data/lib/quakelive_api/items/award.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Award < Struct.new(:icon, :info, :name, :awarded, :description)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/competitor.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Competitor < Struct.new(:icon, :nick, :played)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/favourite.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Favourite < Struct.new(:arena, :game_type, :weapon)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/model.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Model < Struct.new(:name, :image)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/recent_game.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class RecentGame < Struct.new(:gametype, :finish, :played, :image)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/record.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Record < Struct.new(:title, :played, :finished, :wins, :quits, :completed, :wins_percentage)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/items/structurable.rb

@@ -0,0 +1,13 @@
+module QuakeliveApi
+  module Items
+    module Structurable
+
+      def initialize(*args)
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        super(*args)
+        opts.each { |k, v| send("#{k}=", v) }
+      end
+
+    end
+  end
+end

data/lib/quakelive_api/items/weapon.rb

@@ -0,0 +1,7 @@
+module QuakeliveApi
+  module Items
+    class Weapon < Struct.new(:name, :frags, :accuracy, :hits, :shots, :usage)
+      include Structurable
+    end
+  end
+end

data/lib/quakelive_api/parser/awards.rb

@@ -0,0 +1,50 @@
+module QuakeliveApi
+  module Parser
+    class Awards < Base
+
+      def earned
+        awards = document.css(selector(:earned))
+        if awards
+          awards.map { |node| parse_node(node) }
+        end
+      end
+
+      def unearned
+        document.css(selector(:unearned)).map { |node| parse_node(node) }
+      end
+
+      private
+
+        def selectors
+          {
+            :earned   => ".detailArea",
+            :unearned => ".detailArea_off"
+          }
+        end
+
+        def parse_node(node)
+          attrs = {
+            :icon        => node.at('img')['src'],
+            :info        => node.at('img')['title'],
+            :name        => node.at('span.bigRedTxt').content,
+            :description => node.at('span.blktxt_11').content,
+            :awarded     => awarded_at(node)
+          }
+          Items::Award.new(attrs)
+        end
+
+        def awarded_at(node)
+          return unless node.css('ul.fl li').count >= 3
+
+          matches = node.at('ul.fl li:first-child').content.match(/(\d{2})\/(\d{2})\/(\d{4})/)
+          Date.new(matches[3].to_i, matches[1].to_i, matches[2].to_i) unless matches.nil?
+        end
+    end
+
+    class CareerMilestones < Awards; end
+    class Experience       < Awards; end
+    class MadSkillz        < Awards; end
+    class SocialLife       < Awards; end
+    class SweetSuccess     < Awards; end
+  end
+end

data/lib/quakelive_api/parser/base.rb

@@ -0,0 +1,33 @@
+module QuakeliveApi
+  module Parser
+    class Base
+      def initialize(document)
+        @document = document
+      end
+
+      def invalid_player?
+        document.css('.prf_header span').text =~ /Player not found/
+      end
+
+      def request_error?
+        document.css('#sorry_content p:first-child').text =~ /An error has occurred while handling your request/
+      end
+
+      private
+
+      attr_reader :document
+
+      def selectors
+        raise NotImplementedError
+      end
+
+      def selector(name)
+        selectors.fetch(name)
+      end
+
+      def to_integer(val)
+        val.gsub(',','').to_i
+      end
+    end
+  end
+end

data/lib/quakelive_api/parser/statistics.rb

@@ -0,0 +1,81 @@
+module QuakeliveApi
+  module Parser
+    class Statistics < Base
+
+      def weapons
+        document.css(selector(:weapon)).each_with_index.map do |node, idx|
+          attrs = {
+            :name     => node.text,
+            :frags    => frags(weapon_next(:frags, idx)),
+            :accuracy => accuracy(weapon_next(:accuracy, idx)),
+            :usage    => usage(weapon_next(:usage, idx))
+          }
+
+          hits, shots = hits_shots(weapon_next(:accuracy, idx))
+          attrs.merge!(:hits => hits, :shots => shots)
+
+          Items::Weapon.new(attrs)
+        end
+      end
+
+      def records
+        return if no_records?
+
+        document.css(selector(:record)).map do |node|
+
+          next if no_records?
+
+          attrs = {
+            :title           => node.at('.col_st_gametype').text.strip,
+            :played          => to_integer(node.at('.col_st_played').text),
+            :finished        => to_integer(node.at('.col_st_finished').text),
+            :wins            => to_integer(node.at('.col_st_wins').text),
+            :quits           => to_integer(node.at('.col_st_withdraws').text),
+            :completed       => to_integer(node.at('.col_st_completeperc').text.gsub('%','')),
+            :wins_percentage => to_integer(node.at('.col_st_winperc').text.gsub('%',''))
+          }
+          Items::Record.new(attrs)
+        end
+      end
+
+      private
+
+      def selectors
+        {
+          :weapon   => ".prf_weapons .col_weapon",
+          :frags    => ".col_frags",
+          :accuracy => ".col_accuracy",
+          :usage    => ".col_usage",
+          :record   => ".qlv_profile_section_statistics .prf_record > div"
+        }
+      end
+
+      def no_records?
+        document.at(selector(:record)).nil?
+      end
+
+      def hits_shots(node)
+        return [nil, nil] unless node['title']
+        res = node['title'].match(/Hits: ([\d,]+) Shots: ([\d,]+)/)
+        [res[1], res[2]].map { |r| to_integer r }
+      end
+
+      def usage(node)
+        to_integer node.text.gsub("%", '')
+      end
+
+      def weapon_next(css, index)
+        document.css(".prf_weapons #{selector(css)}")[index]
+      end
+
+      def frags(node)
+        to_integer node.text
+      end
+
+      def accuracy(node)
+        return if node.text == 'N/A'
+        to_integer node.at('span').text.gsub("%","")
+      end
+    end
+  end
+end

data/lib/quakelive_api/parser/summary.rb

@@ -0,0 +1,174 @@
+module QuakeliveApi
+  module Parser
+    class Summary < Base
+
+      def country
+        document.at(selector(:country))['title']
+      end
+
+      def nick
+        document.at(selector(:nick)).text
+      end
+
+      def clan
+        (c = document.at(selector(:clan))) ? c.text : nil
+      end
+
+      def model
+        div = document.at(selector(:model))
+        name  = div['title']
+        image = decode_background(div['style'])
+        Items::Model.new(name, image)
+      end
+
+      def member_since
+        Date.parse vitals.at(selector(:member)).next.text.match(/([\w.\s,]+)/)[1]
+      end
+
+      def last_game
+        node = vitals.at selector(:last)
+        node ? decode_time(node['title']) : nil
+      end
+
+      def time_played
+        node = vitals.at selector(:played)
+        node ? GameTime.new(node['title']) : nil
+      end
+
+      def wins
+        to_integer vitals.at(selector(:wins)).next.text
+      end
+
+      def accuracy
+        vitals.at(selector(:accuracy)).next.text.match(/([\d.]+)%/)[1].to_f
+      end
+
+      def losses_quits
+        parse_slashed vitals.at(selector(:losses))
+      end
+
+      def frags_deaths
+        parse_slashed vitals.at(selector(:frags))
+      end
+
+      def hits_shots
+        parse_slashed vitals.at(selector(:hits))
+      end
+
+      def favourites
+        Items::Favourite.new(*document.css(selector(:favs))
+          .map { |n| n.next.text.strip }
+          .map { |n| n == "None" ? nil : n })
+      end
+
+      def awards
+        awards = document.css(selector(:awards)).map do |node|
+          title = node.at('.vcenter_data b')
+
+          next if title.text =~ /No recent award/
+
+          info        = node['title']
+          icon        = node.at('img')['src']
+          awarded     = title.next.next
+          description = awarded.next.next
+
+          Items::Award.new(icon, info, title.text.strip, awarded.text.strip, description.text.strip.gsub("\n",""))
+        end.compact
+
+        awards.any? ? awards : nil
+      end
+
+      def recent_games
+        games = document.css(selector(:games)).map do |node|
+          gametype = decode_gametype node.at('img.gametype')['src']
+          finish   = node.at('span.finish').text.strip.match(/Finish:\s+(\w+)/i)[1]
+          played   = node.at('span.played').text.strip.match(/Played:\s+([\w ]+)/i)[1]
+          image    = node.at('img.levelshot')['src']
+
+          Items::RecentGame.new(gametype, finish, played, image)
+        end.compact
+
+        games.any? ? games : nil
+      end
+
+      def recent_competitors
+        competitors = document.css(selector(:competitors)).map do |node|
+          next if node.at('.rcmp_none')
+
+          icon   = decode_background node.at('.usericon_standard_lg')['style']
+          nick   = node.at('a.player_nick_dark').text
+          played = decode_time(node.at('span.text_tooltip')['title'])
+
+          Items::Competitor.new(icon, nick, played )
+        end.compact
+
+        competitors.any? ? competitors : nil
+      end
+
+      private
+
+      def selectors
+        {
+          :country     => ".playername img",
+          :nick        => "#prf_player_name",
+          :clan        => ".playername a.clan",
+          :model       => ".prf_imagery div",
+          :vitals      => ".prf_vitals p",
+          :member      => "b:contains('Member Since')",
+          :last        => "b:contains('Last Game') + span",
+          :played      => "b:contains('Time Played') + span",
+          :wins        => "b:contains('Wins')",
+          :losses      => "b:contains('Losses')",
+          :frags       => "b:contains('Frags')",
+          :hits        => "b:contains('Hits')",
+          :accuracy    => "b:contains('Accuracy')",
+          :favs        => ".prf_faves b",
+          :awards      => ".prf_awards .awd_details",
+          :games       => ".recent_match",
+          :competitors => "#qlv_profileBottomInset .rcmp_block"
+        }
+      end
+
+      def decode_time(string)
+        Time.strptime(string, '%m/%d/%Y %H:%M %p')
+      end
+
+      # FIXME: not really fully implemented
+      def decode_gametype(string)
+        if string =~ /ca_/
+          'CA'
+        elsif string =~ /tdm_/
+          'TDM'
+        elsif string =~ /ctf_/
+          'CTF'
+        elsif string =~ /duel_/
+          'Duel'
+        elsif string =~ /ad_/
+          'Attack&Defend'
+        elsif string =~ /ffa_/
+          'FFA'
+        elsif string =~ /ft_/
+          'FreezeTag'
+        elsif string =~ /race_/
+          'Race'
+        elsif string =~ /rr_/
+          'Red Rover'
+        end
+      end
+
+      def decode_background(string)
+        string.strip.match(/background(?:-image)?: url\(([\w:\/.]+)/)[1]
+      end
+
+      def vitals
+        document.at(selector(:vitals))
+      end
+
+      def parse_slashed(node)
+        match = node.next.text.match(/([\d,]+) \/ ([\d,]+)/)
+        [match[1], match[2]].map { |r| to_integer(r) }
+      end
+
+    end
+  end
+end