kappa 0.3.0 → 0.4.0

data/lib/kappa/game.rb

@@ -1,9 +1,11 @@
-module Kappa::V2
+module Twitch::V2
   # Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels.
   # Games can be searched for by query.
+  # @see Games#top Games#top
+  # @see Games#find Games#find
   # @see Games
   class Game
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
     def initialize(hash)
@@ -18,12 +20,18 @@ module Kappa::V2
       @logo_images = Images.new(game['logo'])
     end
 
+    # @example
+    #   21799
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
+    # @example
+    #   "League of Legends"
     # @return [String] User-friendly game name.
     attr_reader :name
 
+    # @example
+    #   24024
     # @return [Fixnum] Unique game ID for GiantBomb.com. 
     attr_reader :giantbomb_id
 
@@ -33,17 +41,21 @@ module Kappa::V2
     # @return [Images] Set of images for the game's logo.
     attr_reader :logo_images
 
+    # @example
+    #   802
     # @return [Fixnum] Total number of channels currently streaming this game on Twitch.
     attr_reader :channel_count
 
+    # @example
+    #   68592
     # @return [Fixnum] Total number of viewers across all channels currently watching this game on Twitch.
     attr_reader :viewer_count
   end
 
-  # A game suggestion returned by Twitch when searching for games via `Games.find`.
-  # @see Games.find
+  # A game suggestion returned by Twitch when searching for games via `Twitch.games.find`.
+  # @see Games#find Games#find
   class GameSuggestion
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
     def initialize(hash)
@@ -55,16 +67,24 @@ module Kappa::V2
       @logo_images = Images.new(hash['logo'])
     end
 
+    # @example
+    #   155075940
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
+    # @example
+    #   "Dark Souls"
     # @return [String] Game name.
     attr_reader :name
 
+    # @example
+    #   32697
     # @return [Fixnum] Unique game ID for GiantBomb.com. 
     attr_reader :giantbomb_id
 
-    # @return [Fixnum] Relative popularity metric. Higher number means more popular.
+    # @example
+    #   67
+    # @return [Fixnum] Relative popularity metric. Higher number means more popular. This value only has meaning relative to other popularity values.
     attr_reader :popularity
 
     # @return [Images] Set of images for the game's box art.
@@ -74,36 +94,39 @@ module Kappa::V2
     attr_reader :logo_images
   end
 
-  # Query class used for finding top games or finding games by name.
+  # Query class for finding top games or finding games by name.
   # @see Game
   # @see GameSuggestion
   class Games
-    include Connection
+    # @private
+    def initialize(query)
+      @query = query
+    end
 
     # Get a list of games with the highest number of current viewers on Twitch.
     # @example
-    #   Games.top
+    #   Twitch.games.top
     # @example
-    #   Games.top(:limit => 10)
+    #   Twitch.games.top(:limit => 10)
     # @param options [Hash] Filter criteria.
     # @option options [Boolean] :hls (nil) If `true`, limit the games to those that have any streams using HLS (HTTP Live Streaming). If `false` or `nil`, do not limit.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
-    # @see Game
+    # @see Game Game
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop GET /games/top
     # @return [Array<Game>] List of games sorted by number of current viewers on Twitch, most popular first.
-    def self.top(options = {})
+    def top(options = {})
       params = {}
 
       if options[:hls]
         params[:hls] = true
       end
 
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => 'games/top',
         :params => params,
         :json => 'top',
-        :class => Game,
+        :create => Game,
         :limit => options[:limit],
         :offset => options[:offset]
       )
@@ -111,18 +134,18 @@ module Kappa::V2
     
     # Get a list of games with names similar to the specified name.
     # @example
-    #   Games.find(:name => 'diablo')
+    #   Twitch.games.find(:name => 'diablo')
     # @example
-    #   Games.find(:name => 'starcraft', :live => true)
+    #   Twitch.games.find(:name => 'starcraft', :live => true)
     # @param options [Hash] Search criteria.
     # @option options [String] :name Game name search term. This can be a partial name, e.g. `"league"`.
     # @option options [Boolean] :live (false) If `true`, only returns games that are currently live on at least one channel.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
-    # @see GameSuggestion
+    # @see GameSuggestion GameSuggestion
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames GET /search/games
     # @raise [ArgumentError] If `:name` is not specified.
     # @return [Array<GameSuggestion>] List of games matching the criteria.
-    def self.find(options)
+    def find(options)
       raise ArgumentError, 'options' if options.nil?
       raise ArgumentError, 'name' if options[:name].nil?
 
@@ -135,11 +158,11 @@ module Kappa::V2
         params.merge!(:live => true)
       end
 
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => 'search/games',
         :params => params,
         :json => 'games',
-        :class => GameSuggestion,
+        :create => GameSuggestion,
         :limit => options[:limit]
       )
     end

data/lib/kappa/id_equality.rb

@@ -1,4 +1,4 @@
-module Kappa
+module Twitch
   # @private
   module IdEquality
     def hash

data/lib/kappa/images.rb

@@ -1,4 +1,4 @@
-module Kappa::V2
+module Twitch::V2
   # A group of URLs pointing to variously-sized versions of the same image.
   class Images
     # @private
@@ -10,6 +10,8 @@ module Kappa::V2
     end
 
     # Get a URL pointing to an image with a specific size.
+    # @example
+    #   url = images.url(320, 200)
     # @param width [Fixnum] Desired width of the image.
     # @param height [Fixnum] Desired height of the image.
     # @return [String] URL pointing to the image with the specified size.
@@ -17,16 +19,24 @@ module Kappa::V2
       @template_url.gsub('{width}', width.to_s).gsub('{height}', height.to_s)
     end
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/ttv-logoart/League%20of%20Legends-240x144.jpg"
     # @return [String] URL for the large-sized version of this image.
     attr_reader :large_url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/ttv-logoart/League%20of%20Legends-120x72.jpg"
     # @return [String] URL for the medium-sized version of this image.
     attr_reader :medium_url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/ttv-logoart/League%20of%20Legends-60x36.jpg"
     # @return [String] URL for the small-sized version of this image.
     attr_reader :small_url
 
     # @note You shouldn't need to use this property directly. See #url for getting a formatted URL instead.
+    # @example
+    #   "http://static-cdn.jtvnw.net/ttv-logoart/League%20of%20Legends-{width}x{height}.jpg"
     # @return [String] Template image URL with placeholders for width and height.
     # @see #url
     attr_reader :template_url

data/lib/kappa/query.rb

@@ -0,0 +1,22 @@
+module Twitch::V2
+  # @private
+  class Query
+    def initialize(connection)
+      @connection = connection
+      @channels = Channels.new(self)
+      @streams = Streams.new(self)
+      @users = Users.new(self)
+      @games = Games.new(self)
+      @teams = Teams.new(self)
+      @videos = Videos.new(self)
+    end
+
+    attr_reader :connection
+    attr_reader :channels
+    attr_reader :streams
+    attr_reader :users
+    attr_reader :games
+    attr_reader :teams
+    attr_reader :videos
+  end
+end

data/lib/kappa/stream.rb

@@ -1,75 +1,63 @@
 require 'cgi'
 
-module Kappa::V2
+module Twitch::V2
   # Streams are video broadcasts that are currently live. They belong to a user and are part of a channel.
-  # @see .get Stream.get
+  # @see Streams#get Streams#get
+  # @see Streams#find Streams#find
+  # @see Streams#featured Streams#featured
   # @see Streams
   # @see Channel
   class Stream
-    include Connection
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
-    def initialize(hash)
+    def initialize(hash, query)
+      @query = query
       @id = hash['_id']
       @broadcaster = hash['broadcaster']
       @game_name = hash['game']
       @name = hash['name']
       @viewer_count = hash['viewers']
       @preview_url = hash['preview']
-      @channel = Channel.new(hash['channel'])
+      @channel = Channel.new(hash['channel'], @query)
       @url = @channel.url
     end
 
-    # Get a live stream by name.
-    # @example
-    #   s = Stream.get('lagtvmaximusblack')
-    #   s.nil?          # => false (stream is live)
-    #   s.game_name     # => "StarCraft II: Heart of the Swarm"
-    #   s.viewer_count  # => 2403
-    # @example
-    #   s = Strearm.get('destiny')
-    #   s.nil?          # => true (stream is offline)
-    # @param stream_name [String] The name of the stream to get. This is the same as the channel or user name.
-    # @see Streams.find
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamschannel GET /streams/:channel
-    # @return [Stream] A valid `Stream` object if the stream exists and is currently live, `nil` otherwise.
-    def self.get(stream_name)
-      encoded_name = CGI.escape(stream_name)
-      json = connection.get("streams/#{encoded_name}")
-      stream = json['stream']
-      if json['status'] == 404 || !stream
-        nil
-      else
-        new(stream)
-      end
-    end
-
     # Get the owner of this stream.
     # @note This incurs an additional web request.
     # @return [User] The user that owns this stream.
     def user
-      User.get(@channel.name)
+      @query.users.get(@channel.name)
     end
 
+    # @example
+    #   6226912672
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
     # @example
     #   "fme", "xsplit", "obs", "rebroadcast", "delay", "unknown rtmp"
-    # @deprecated This attribute will not be present in the V3 API.
+    # @deprecated This attribute is not present in the V3 API.
     # @return [String] The broadcasting software used for this stream.
     attr_reader :broadcaster
     
+    # @example
+    #   "Super Meat Boy"
     # @return [String] The name of the game currently being streamed.
     attr_reader :game_name
 
+    # @example
+    #   "live_user_lethalfrag"
     # @return [String] The unique Twitch name for this stream.
     attr_reader :name
 
+    # @example
+    #   2342
     # @return [Fixnum] The number of viewers currently watching the stream.
     attr_reader :viewer_count
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/previews-ttv/live_user_lethalfrag-320x200.jpg"
     # @return [String] URL of a preview screenshot taken from the video stream.
     attr_reader :preview_url
 
@@ -77,36 +65,66 @@ module Kappa::V2
     # @return [Channel] The `Channel` associated with this stream.
     attr_reader :channel
 
+    # @example
+    #   "http://www.twitch.tv/lethalfrag" 
     # @return [String] The URL for this stream.
     attr_reader :url
   end
 
-  # Query class used for finding featured streams or streams meeting certain criteria.
+  # Query class for finding featured streams or streams meeting certain criteria.
   # @see Stream
   class Streams
-    include Connection
+    # @private
+    def initialize(query)
+      @query = query
+    end
+
+    # Get a live stream by name.
+    # @example
+    #   s = Twitch.streams.get('lagtvmaximusblack')
+    #   s.nil?          # => false (stream is live)
+    #   s.game_name     # => "StarCraft II: Heart of the Swarm"
+    #   s.viewer_count  # => 2403
+    # @example
+    #   s = Twitch.streams.get('destiny')
+    #   s.nil?          # => true (stream is offline)
+    # @param stream_name [String] The name of the stream to get. This is the same as the channel or user name.
+    # @see #find
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamschannel GET /streams/:channel
+    # @return [Stream] A valid `Stream` object if the stream exists and is currently live, `nil` otherwise.
+    def get(stream_name)
+      encoded_name = CGI.escape(stream_name)
+      json = @query.connection.get("streams/#{encoded_name}")
+      stream = json['stream']
+      if json['status'] == 404 || !stream
+        nil
+      else
+        Stream.new(stream, @query)
+      end
+    end
 
     # Get a list of streams for a specific game, for a set of channels, or by other criteria.
     # @example
-    #   Streams.find(:game => 'League of Legends', :limit => 50)
+    #   Twitch.streams.find(:game => 'League of Legends', :limit => 50)
     # @example
-    #   Streams.find(:channel => ['fgtvlive', 'incontroltv', 'destiny'])
+    #   Twitch.streams.find(:channel => ['fgtvlive', 'incontroltv', 'destiny'])
     # @example
-    #   Streams.find(:game => 'Diablo III', :channel => ['nl_kripp', 'protech'])
+    #   Twitch.streams.find(:game => 'Diablo III', :channel => ['nl_kripp', 'protech'])
     # @param options [Hash] Search criteria.
     # @option options [String/Game/#name] :game Only return streams currently streaming the specified game.
     # @option options [Array<String/Channel/#name>] :channel Only return streams for these channels.
     #   If a channel is not currently streaming, it is omitted. You must specify an array of channels
-    #   or channel names. If you want to find the stream for a single channel, see {Stream.get}.
+    #   or channel names. If you want to find the stream for a single channel, see {Streams#get}.
     # @option options [Boolean] :embeddable (nil) If `true`, limit the streams to those that can be embedded. If `false` or `nil`, do not limit.
     # @option options [Boolean] :hls (nil) If `true`, limit the streams to those using HLS (HTTP Live Streaming). If `false` or `nil`, do not limit.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
-    # @see Stream.get
+    # @see #get
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
     # @raise [ArgumentError] If `options` does not specify a search criteria (`:game`, `:channel`, `:embeddable`, or `:hls`).
+    # @raise [ArgumentError] If `:channel` is not an array.
     # @return [Array<Stream>] List of streams matching the specified criteria.
-    def self.find(options)
+    def find(options)
       check = options.dup
       check.delete(:limit)
       check.delete(:offset)
@@ -116,6 +134,10 @@ module Kappa::V2
 
       channels = options[:channel]
       if channels
+        if !channels.respond_to?(:map)
+          raise ArgumentError, ':channel'
+        end
+
         params[:channel] = channels.map { |channel|
           if channel.respond_to?(:name)
             channel.name
@@ -142,11 +164,11 @@ module Kappa::V2
         params[:embeddable] = true
       end
 
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => 'streams',
         :params => params,
         :json => 'streams',
-        :class => Stream,
+        :create => -> hash { Stream.new(hash, @query) },
         :limit => options[:limit],
         :offset => options[:offset]
       )
@@ -155,28 +177,28 @@ module Kappa::V2
     # Get the list of currently featured (promoted) streams. This includes the list of streams shown on the Twitch homepage.
     # @note There is no guarantee of how many streams are featured at any given time.
     # @example
-    #   Streams.featured
+    #   Twitch.streams.featured
     # @example
-    #   Streams.featured(:limit => 5)
+    #   Twitch.streams.featured(:limit => 5)
     # @param options [Hash] Filter criteria.
     # @option options [Boolean] :hls (nil) If `true`, limit the streams to those using HLS (HTTP Live Streaming). If `false` or `nil`, do not limit.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamsfeatured GET /streams/featured
     # @return [Array<Stream>] List of currently featured streams.
-    def self.featured(options = {})
+    def featured(options = {})
       params = {}
 
       if options[:hls]
         params[:hls] = true
       end
 
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => 'streams/featured',
         :params => params,
         :json => 'featured',
         :sub_json => 'stream',
-        :class => Stream,
+        :create => -> hash { Stream.new(hash, @query) },
         :limit => options[:limit],
         :offset => options[:offset]
       )