kappa 0.1.5.pre → 0.2.0

data/lib/kappa/user.rb

@@ -1,27 +1,17 @@
-module Kappa
-  # @private
-  class UserBase
-    include IdEquality
-
-    #
-    # GET /users/:user
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/users.md#get-usersuser
-    #
-    def self.get(user_name)
-      json = connection.get("users/#{user_name}")
-      if json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-  end
-end
+require 'cgi'
 
 module Kappa::V2
-  class User < Kappa::UserBase
+  # These are members of the Twitch community who have a Twitch account. If broadcasting,
+  # they can own a stream that they can broadcast on their channel. If mainly viewing,
+  # they might follow or subscribe to channels.
+  # @see .get User.get
+  # @see Channel
+  # @see Stream
+  class User
     include Connection
+    include Kappa::IdEquality
 
+    # @private
     def initialize(hash)
       @id = hash['_id']
       @created_at = DateTime.parse(hash['created_at'])
@@ -32,10 +22,29 @@ module Kappa::V2
       @updated_at = DateTime.parse(hash['updated_at'])
     end
 
+    # Get a user by name.
+    # @param user_name [String] The name of the user to get. This is the same as the channel or stream name.
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/users.md#get-usersuser GET /users/:user
+    # @return [User] A valid `User` object if the user exists, `nil` otherwise.
+    def self.get(user_name)
+      encoded_name = CGI.escape(user_name)
+      json = connection.get("users/#{encoded_name}")
+      if !json || json['status'] == 404
+        nil
+      else
+        new(json)
+      end
+    end
+
+    # Get the `Channel` associated with this user.
+    # @note This incurs an additional web request.
+    # @return [Channel] The `Channel` associated with this user, or `nil` if this is a Justin.tv account.
+    # @see Channel.get
     def channel
-      # TODO
+      Channel.get(@name)
     end
 
+    # @return [Boolean] `true` if the user is a member of the Twitch.tv staff, `false` otherwise.
     def staff?
       @staff
     end
@@ -44,22 +53,22 @@ module Kappa::V2
     # GET /channels/:channel/subscriptions/:user
     # https://github.com/justintv/Twitch-API/blob/master/v2_resources/subscriptions.md#get-channelschannelsubscriptionsuser
     #
-    # TODO: Requires authentication.
+
+    # TODO: Requires authentication. Private until implemented.
+    # @private
     def subscribed_to?(channel_name)
     end
 
-    #
-    # GET /streams/followed
-    # TODO: Authenticate.
-    # TODO: Only valid for authenticated user, might not belong here.
-    #
-    # GET /users/:user/follows/channels
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannels
-    #
-    def following(params = {})
+    # @param options [Hash] Filter criteria.
+    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @see #following?
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannels GET /users/:user/follows/channels
+    # @return [Array<Channel>] List of channels the user is currently following.
+    def following(options = {})
+      # TODO: If offset supported?
       params = {}
 
-      limit = args[:limit]
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else
@@ -77,22 +86,44 @@ module Kappa::V2
       )
     end
 
-    #
-    # GET /users/:user/follows/:channels/:target
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannelstarget
-    #
-    def following?(channel_name)
+    # @param channel [String, Channel] The name of the channel (or `Channel` object) to check.
+    # @return [Boolean] `true` if the user is following the channel, `false` otherwise.
+    # @see #following
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannelstarget GET /users/:user/follows/:channels/:target
+    def following?(channel)
+      # TODO: Support User for channel parameter? Stream?
+
+      channel_name = case channel
+        when String
+          channel
+        when Channel
+          channel.name
+      end
+
+      channel_name = CGI.escape(channel_name)
+
       json = connection.get("users/#{@name}/follows/channels/#{channel_name}")
       status = json['status']
       return !status || (status != 404)
     end
 
+    # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
+
+    # @return [DateTime] When the user account was created.
     attr_reader :created_at
+
+    # @return [DateTime] When the user account was last updated.
+    attr_reader :updated_at
+
+    # @return [String] User-friendly display name.
     attr_reader :display_name
+
+    # @return [String] URL for the logo image.
     attr_reader :logo_url
+
+    # @return [String] Unique Twitch name.
     attr_reader :name
-    attr_reader :updated_at
 
     # TODO: Authenticated user attributes.
     # attr_reader :email

data/lib/kappa/version.rb

@@ -1 +1 @@
-$version = '0.1.5.pre'
+$version = '0.2.0'

data/lib/kappa/video.rb

@@ -1,21 +1,19 @@
-module Kappa
-  # @private
-  class VideoBase
-    include IdEquality
-
-    def self.get(id)
-      json = connection.get("videos/#{id}")
-      new(json)
-    end
-  end
-end
+require 'cgi'
 
 module Kappa::V2
-  class Video < Kappa::VideoBase
+  # Videos are broadcasts or highlights owned by a channel. Broadcasts are unedited
+  # videos that are saved after a streaming session. Highlights are videos edited from
+  # broadcasts by the channel's owner.
+  # @see .get Video.get
+  # @see Videos
+  # @see Channel
+  class Video
     include Connection
+    include Kappa::IdEquality
 
+    # @private
     def initialize(hash)
-      @id = hash['id']
+      @id = hash['_id']
       @title = hash['title']
       @recorded_at = DateTime.parse(hash['recorded_at'])
       @url = hash['url']
@@ -28,26 +26,75 @@ module Kappa::V2
       # @channel_display_name = json['channel']['display_name']
     end
 
+    # Get a video by ID.
+    # @example
+    #   v = Video.get('a396294648')
+    #   v.title # => "DreamHack Open Stockholm 26-27 April"
+    # @param id [String] The ID of the video to get.
+    # @raise [ArgumentError] If `id` is `nil` or blank.
+    # @return [Video] A valid `Video` object if the video exists, `nil` otherwise.
+    def self.get(id)
+      raise ArgumentError if !id || id.strip.empty?
+
+      encoded_id = CGI.escape(id)
+      json = connection.get("videos/#{encoded_id}")
+      if !json || json['status'] == 404
+        nil
+      else
+        new(json)
+      end
+    end
+
+    # @note This incurs an additional web request.
+    # @return [Channel] The channel on which this video was originally streamed.
     def channel
       Channel.new(connection.get("channels/#{@channel_name}"))
     end
 
+    # @note This is a `String`, not a `Fixnum` like most other object IDs.
+    # @example
+    #   v = Video.get('a396294648')
+    #   v.id # => "a396294648"
+    # @return [String] Unique Twitch ID for this video.
     attr_reader :id
+
+    # @return [String] Title of this video. This is seen on the video's page.
     attr_reader :title
+
+    # @return [DateTime] When this video was recorded.
     attr_reader :recorded_at
+
+    # @return [String] URL of this video on Twitch.
     attr_reader :url
+
+    # @return [Fixnum] The number of views this video has received all-time.
     attr_reader :view_count
+
+    # @return [String] Description of this video.
     attr_reader :description
-    # TODO: Is this actually in seconds? Doesn't seem to match up with video length.
-    attr_reader :length_sec
+
+    # @return [Fixnum] The length of this video in seconds.
+    attr_reader :length_sec # TODO: Is this actually in seconds? Doesn't seem to match up with video length.
+
+    # @return [String] The name of the game played in this video.
     attr_reader :game_name
+
+    # @return [String] URL of a preview screenshot taken from the video stream.
     attr_reader :preview_url
-    # TODO: Move this under "v.channel.name" and force the query if other attributes are requested.
-    attr_reader :channel_name
+
+    # @return [String] The name of the channel on which this video was originally streamed.
+    attr_reader :channel_name # TODO: Move this under "v.channel.name" and force the query if other attributes are requested.
+
+    # TODO: embed (HTML embed code)
   end
 
+  # Query class used for finding top videos.
+  # @see Video
   class Videos
+    # @private
+    # Private until implemented.
     def self.top(params = {})
+      # TODO
     end
   end
 end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: kappa
 version: !ruby/object:Gem::Version
-  version: 0.1.5.pre
-  prerelease: 6
+  version: 0.2.0
+  prerelease: 
 platform: ruby
 authors:
 - Chris Schmich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-12 00:00:00.000000000 Z
+date: 2013-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &26379276 !ruby/object:Gem::Requirement
+  requirement: &24580620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 0.9.0
   type: :runtime
   prerelease: false
-  version_requirements: *26379276
+  version_requirements: *24580620
 - !ruby/object:Gem::Dependency
   name: addressable
-  requirement: &26378880 !ruby/object:Gem::Requirement
+  requirement: &24580296 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 2.3.3
   type: :runtime
   prerelease: false
-  version_requirements: *26378880
+  version_requirements: *24580296
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &26378304 !ruby/object:Gem::Requirement
+  requirement: &24579948 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *26378304
+  version_requirements: *24579948
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &26394384 !ruby/object:Gem::Requirement
+  requirement: &24579624 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 1.11.0
   type: :development
   prerelease: false
-  version_requirements: *26394384
+  version_requirements: *24579624
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &26394048 !ruby/object:Gem::Requirement
+  requirement: &24579288 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,43 @@ dependencies:
         version: 2.13.0
   type: :development
   prerelease: false
-  version_requirements: *26394048
+  version_requirements: *24579288
+- !ruby/object:Gem::Dependency
+  name: launchy
+  requirement: &24578952 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: *24578952
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &24578604 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :development
+  prerelease: false
+  version_requirements: *24578604
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &24578280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: *24578280
 - !ruby/object:Gem::Dependency
   name: coveralls
-  requirement: &26393772 !ruby/object:Gem::Requirement
+  requirement: &24578004 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +109,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *26393772
+  version_requirements: *24578004
 description: ! "    A Ruby library for interfacing with the Twitch.tv API\n    including
   users, channels, streams, and followers.\n"
 email: schmch@gmail.com
@@ -112,9 +145,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.15
@@ -122,3 +155,4 @@ signing_key:
 specification_version: 3
 summary: Ruby library for interfacing with the Twitch.tv API.
 test_files: []
+has_rdoc: