srl-api 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0f91b1fa2a4677c8f682dc2b4a67a6d663430958
+  data.tar.gz: 2ca3b63a2e19f54087825cf3f476ef45d50ef3a0
+SHA512:
+  metadata.gz: '0181c321261059c20869a9dcfccd53b9313c45e118cc0e7c0d43905a5f0c3baa72cda609b81d1c614101ac88b4490f6f67cd50355717aea1153f7f315d96ec68'
+  data.tar.gz: 3120014cc38f42ef7d6066122e46d842d291f76bb51da0931e310df46bc599f017164f8dc706d656fd14a3d18c2b569b38bc7817a0a9d81f56e42e9b0e463f6f

data/README.md

@@ -0,0 +1,35 @@
+SpeedRunsLive Ruby Client
+=========================
+
+Ruby library to retrieve data from SpeedRunsLive.com.
+
+
+## Installation
+
+The gem is hosted on RubyGems, so you can either install it 
+with `gem install srl-api` or, if you are using bundler, by adding
+it to your program's Gemfile and running `bundle install`.
+
+
+## Documentation
+
+`rdoc lib/` from the project root, or let RubyGems do it for you in $GEM_HOME.
+
+## Usage
+
+Short version: 
+
+    require 'srl'
+
+    puts SRL.past_races(player: 'Artea', game: 'ffhacks').size # => Some number probably in the low 20s.
+
+The `examples/` directory should provide you with an adequate amount
+of usable, real-world examples.
+
+Client code should focus on the `SRL` module, with its relevant functions 
+being found in `lib/srl/api.rb`.
+
+
+## Maintainer
+
+Brian Edmonds "Artea" <brian@bedmonds.net>

data/lib/srl.rb

@@ -0,0 +1,11 @@
+require_relative 'srl/api'
+
+module SRL
+  # The current version of srl-api.
+  RELEASE = '0.2.0'.freeze
+
+  # Return the current release version as a dotted string.
+  def self.release
+    RELEASE
+  end
+end

data/lib/srl/api.rb

@@ -0,0 +1,89 @@
+require 'net/http'
+require 'json'
+
+require_relative 'typedefs'
+require_relative 'utils'
+
+module SRL
+  class << self
+    # Fetch usage data about a specific game, identified 
+    # by its abbreviation.
+    #
+    # call-seq: game(abbreviation) -> obj
+    def game(abbrev)
+      res = query("stat", game: abbrev)
+      game = Game.from_hash(res.fetch('game'))
+      game.stats = res.fetch('stats')
+
+      game
+    end
+
+    # Fetch a player's public profile, by name.
+    # Raises a NameError if the given name does not exist.
+    #
+    # call-seq: player(name) -> obj
+    def player(name)
+      player = Player.from_hash(query("players/#{name}"))
+
+      raise NameError, "Player '#{name}' not found." unless player.exists?
+
+      player
+    end
+
+    # Fetch the leaderboard for a specific game, identified 
+    # by its abbreviation.
+    #
+    # call-seq: leaderboard(abbrev) -> obj
+    def leaderboard(abbrev)
+      SRL::Utils.collection(
+        query("leaderboard/#{abbrev}").fetch('leaders'),
+        Player
+      )
+    end
+
+    # Return an array of Race objects for races currently being
+    # run or set up.
+    #
+    # call-seq: current_races -> array
+    def current_races
+      SRL::Utils.collection(query('races').fetch('races'), Race)
+    end
+
+    # Return an array of PastRace objects for completed races.
+    # call-seq: current_races -> array
+    def current_races
+    def completed_races(args = {})
+      res = query('pastraces', args)
+      ResultSet.new(
+        SRL::Utils.collection(res.fetch('pastraces'), PastRace),
+        count: res.fetch('count'),
+        page: args.fetch(:page, 1),
+        page_size: args.fetch(:page_size, 25)
+      )
+    end
+    alias past_races completed_races
+
+    private
+
+    # SpeedRunsLive API URL.
+    API = 'http://api.speedrunslive.com/'.freeze
+
+    # Return a hash with the results of a query to the SRL API.
+    def query(url, params = {})
+      url = URI([API, url].join) # *hiss* "URI" has been wrong for years!
+      url.query = URI.encode_www_form(params) unless params.empty?
+
+      res = Net::HTTP.get_response(url)
+      raise NetworkError, res unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+  end
+  # Raised when an HTTP request to the SRL API server fails,
+  # whether due to a malformed request or the server being down.
+  #
+  # [FIXME] Add actual descriptions of what fucked up and 
+  #         possible solutions to the issue.
+  class NetworkError < StandardError; end
+end

data/lib/srl/typedefs.rb

@@ -0,0 +1,337 @@
+require 'time'
+
+require_relative 'unmarshalable'
+
+module SRL
+  class Game
+    include Unmarshalable
+
+    # This game's ID as per the SRL data.
+    attr_reader :oid
+    alias game_id oid
+
+    # This game's complete name.
+    attr_reader :name
+
+    # This game's abbreviation, as used by RaceBot.
+    attr_reader :abbrev
+    alias abbreviation abbrev
+    alias short_name abbrev
+
+    # This game's popularity rating, according to SRL data.
+    attr_reader :popularity
+
+    # This game's position in the popularity contest,
+    # according to SRL data.
+    attr_reader :popularityrank
+    alias popularity_rank popularityrank
+
+    # The amount of ranked players on this game's leaderboard.
+    attr_reader :leadersCount
+    alias leaders_count leadersCount
+    alias num_leaders leadersCount
+
+    # This game's leaderboard, as an array of Players.
+    #
+    # While generally sorted by rank, this method does not
+    # guarantee the order of the players return.
+    #
+    # If you absolutely need them sorted, use the `leaders_by_rank`
+    # method or call `sort_by(&:rank)` on this value.
+    attr_reader :leaders
+    def leaders=(arr)
+      @leaders = SRL::Utils.collection(arr, Runner)
+    end
+
+    # Statistics about this game. Things like the number of races, 
+    # number of players, total time played and raced.
+    # 
+    # [SEE] SRL::Statistics
+    attr_accessor :stats
+    def stats=(val)
+      @statistics =
+        val.is_a?(Statistics) ? val
+                              : Statistics.from_hash(val)
+    end
+    alias statistics stats
+
+    # An array of players on this game's leaderboard, sorted by their
+    # rank.
+    #
+    # 
+    def leaders_by_rank(dir = :asc)
+      raise ArgumentError unless %i(asc desc).include?(dir)
+      
+      dir == :asc ? leaders.sort_by(&:rank) 
+                  : leaders.sort_by(&:rank).reverse
+    end
+
+    class Runner
+      include Unmarshalable
+
+      # This player's name on the SRL website.
+      attr_reader :name
+      
+      # This player's TrueSkill rating for a particular game.
+      attr_reader :trueskill
+      alias rating trueskill
+
+      # This player's position on the leaderboards for a specific game.
+      attr_reader :rank
+      alias position rank
+    end
+  end
+
+  class Race
+    include Unmarshalable
+
+    STATES = [
+      :open,
+      :unknown,
+      :in_progress,
+      :complete
+    ].freeze
+
+    # The IRC channel suffix for this race.
+    attr_reader :oid
+    alias channel oid
+
+    # The state of this race. Entry Open / In Progress / Completed
+    # [FIXME] Switch to enum-like behaviour with symbols.
+    attr_reader :state
+
+    def status
+      STATES[state - 1]
+    rescue
+      :unknown
+    end
+
+    # The game associate with this race.
+    attr_reader :game
+    def game=(game)
+      @game = game.is_a?(Game) ? game
+                               : Game.from_hash(game)
+    end
+
+    # The players enlisted in this race as an array of Entrants.
+    attr_reader :entrants
+    def entrants=(arr)
+      # Account for the api returning a hash with the entrants' name
+      # as key instead of an array, despite repeating the entrants name 
+      # in `displayname`.
+      arr = arr.is_a?(Hash) ? arr.values : arr
+      @entrants = SRL::Utils.collection(arr, Entrant)
+    end
+
+    class Entrant
+      include Unmarshalable
+
+      # This entrant's player name.
+      attr_reader :displayname
+      alias name displayname
+
+      # This entrant's Twitch account name.
+      attr_reader :twitch
+
+      # The position that this entrant finished this race in.
+      attr_reader :place
+      alias position place
+
+      # The comment entered by this entrant for this race,
+      # if applicable.
+      attr_reader :message
+      alias comment message 
+
+      # The number of seconds that this entrant took to complete
+      # the race goal. 
+      #
+      # = Notes
+      # A time of -1 indicates a forfeit.
+      attr_reader :time
+
+      # Did this entrant forfeit the race?
+      def forfeit?
+        time == -1
+      end
+
+      # The state of this entrant in the race. 
+      # Is he ready, finished, neither?
+      #
+      # [FIXME] Switch to an enum-like implementation with symbols.
+      attr_reader :statetext
+    end
+  end
+
+  class PastRace
+    include Unmarshalable
+
+    attr_reader :game
+    def game=(game)
+      @game = game.is_a?(Game) ? game : Game.from_hash(game)
+    end
+
+    attr_reader :date
+    def date=(val)
+      @date = Time.at(val.to_i).utc.to_datetime
+    end
+
+    attr_reader :goal
+
+    attr_reader :results
+    def results=(arr)
+      @results = SRL::Utils.collection(arr, Result)
+    end
+
+    # Result of an individual racer's time and rating adjustments.
+    class Result
+      include Unmarshalable
+
+      # ID of the race this result entry is associated with.
+      #
+      # [NOTE] Not to be confused with the SRL Channel ID.
+      attr_reader :race
+      alias race_id race
+
+      # Which place did this runner finish in?
+      attr_reader :place
+      alias position place
+
+      # The runner's name
+      attr_reader :player
+      alias name player
+
+      # Number of seconds the run lasted.
+      attr_reader :time
+
+      # Optional comment entered by the runner.
+      attr_reader :message
+      alias comment message
+
+      attr_reader :oldtrueskill
+      alias old_rating oldtrueskill
+
+      attr_reader :newtrueskill
+      alias new_rating newtrueskill
+
+      attr_reader :trueskillchange
+      alias rating_adjustment trueskillchange
+    end
+  end
+
+  class Statistics
+    include Unmarshalable
+
+    # Number of races that a particular game has had.
+    attr_reader :totalRaces
+    alias total_races totalRaces
+
+    # Number of players that have participated in a race of a
+    # given game.
+    attr_reader :totalPlayers
+    alias total_players totalPlayers
+
+    # The ID of the race with the highest number of entrants.
+    attr_reader :largestRace
+    alias largest_race_id largestRace
+
+    # Number of entrants in the largest race of the game associated
+    # with these Statistics.
+    attr_reader :largestRaceSize
+    alias largest_race_player_count largestRaceSize
+    alias largest_race_size largestRaceSize
+
+    # Number of seconds that this game has been raced.
+    # A sum of the worst time of each race.
+    attr_reader :totalRaceTime
+    alias total_race_time totalRaceTime
+
+    # Number of seconds that this game has been played for.
+    # A sum of all the times in all races.
+    attr_reader :totalTimePlayed
+    alias total_time_played totalTimePlayed
+  end
+
+  # A registered user of SpeedRunsLive.com
+  class Player
+    include Unmarshalable
+
+    attr_reader :oid
+    alias player_id oid
+
+    # This player's registered name on SpeedRunsLive.
+    # [NOTE] This might not be the same name that he has registered on IRC.
+    attr_reader :name
+
+    # --
+    # Stream information for the player
+    # ++
+    # This player's profile name on a streaming service.
+    attr_reader :channel
+
+    # Streaming platform used by this player. For example: Twitch.
+    attr_reader :api
+    def api=(val)
+      @api = val.intern
+    end
+
+    # This player's YouTube channel.
+    attr_reader :youtube
+
+    # This player's Twitter name.
+    attr_reader :twitter
+
+    # URL to this player's stream.
+    #
+    # [FIXME] Add support for non-twitch streams.
+    def stream
+      api == :twitch ? "https://twitch.tv/#{channel}/"
+                     : 'Unsupported'
+    end
+
+    # Does this player exist?
+    def exists?
+      player_id != 0
+    end
+  end
+
+  # Wrapper around various calls to paginated data, such as past races.
+  # Contains pagination information, and information on all records,
+  # on top of the current page's records.
+  class ResultSet
+    # Records for this result set.
+    # [NOTE]
+    # Always an array, though the type of object contained in the array
+    # can vary depending on the query that spawned it.
+    attr_reader :results
+    alias data results
+    alias records results
+    alias items results
+
+    # The page of this result set.
+    attr_reader :page
+
+    attr_reader :page_size
+    alias per_page page_size
+
+    # Total number of records matching the query for this result set.
+    attr_reader :count
+    alias total_records count
+    alias num_records count
+
+    def initialize(results, params = {})
+      @results = results
+      @page = params.fetch(:page)
+      @page_size = params.fetch(:page_size)
+      @count = params.fetch(:count)
+    end
+
+    def num_pages
+      (count.to_f / page_size.to_f).ceil
+    end
+    alias pages num_pages
+
+    def last_page?
+      page == num_pages
+    end
+  end
+end

data/lib/srl/unmarshalable.rb

@@ -0,0 +1,61 @@
+module SRL
+  # = Summary
+  # Extension class method to allow easy instantiation of objects from
+  # a hash, such as the ones returned in JSON form from the SRL API.
+  # 
+  # = Notes
+  # Any "id" key is converted to "oid" to not overwrite the default
+  # Ruby Object.id behavior.
+  # 
+  # = Usage
+  # Simply include this module in any class to add a `.from_hash` class
+  # method to instantiate it from a hash.
+  #
+  # So long as the hash passed to `from_hash` has keys, in string or 
+  # symbol form, that match the name of methods that an instance of 
+  # the class responds to, instance variables with that same name will 
+  # be assigned the value pointed at in this hash.
+  #
+  # = Example
+  #
+  #   class Player
+  #     include SRL::Unmarshalable
+  #
+  #     attr_reader :name
+  #     attr_reader :rank
+  #     attr_reader :trueskill
+  #   end
+  #
+  #   p = Player.from_hash({
+  #     name: "Foobar", 
+  #     trueskill: 0xDEADBEEF, 
+  #     rank: 9001
+  #   })
+  #   
+  #   puts "It's over 9000!" if p.rank > 9000 # => outputs "It's over 9000!"
+  module Unmarshalable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def from_hash(hash = {})
+        obj = new
+
+        hash.each do |k, v|
+          # Be a good boy and do not overwrite the standard ruby Object.id
+          k = :oid if k.intern == :id
+          next unless obj.respond_to?(k)
+
+          if obj.respond_to?("#{k}=")
+            obj.send("#{k}=", v)
+          else
+            obj.instance_variable_set(:"@#{k}", v) 
+          end
+        end
+
+        obj
+      end
+    end
+  end
+end

data/lib/srl/utils.rb

@@ -0,0 +1,19 @@
+module SRL
+  module Utils
+    # Return an array of +klass+ objects from a source array
+    # of hashes.
+    #
+    # = Notes
+    # If +src+ is already an array of +klass+, this function simply
+    # returns +src+.
+    def self.collection(src, klass)
+      raise ArgumentError unless src.is_a?(Array)
+      raise ArgumentError unless klass.respond_to?(:from_hash)
+
+      return [] if src.empty?
+      return src if src.first.is_a?(klass)
+
+      src.map { |i| klass.from_hash(i) }
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: srl-api
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Brian 'Artea' Edmonds
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-13 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Library to query the SpeedRunsLive.com API and deal with the results
+  in plain old Ruby.
+email:
+- brian@bedmonds.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/srl.rb
+- lib/srl/api.rb
+- lib/srl/typedefs.rb
+- lib/srl/unmarshalable.rb
+- lib/srl/utils.rb
+homepage: https://github.com/bedmonds/srl-api/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Ruby Client for the SpeedRunsLive.com API
+test_files: []