espn_rb 0.0.3 → 0.0.4

data/README.md

@@ -4,9 +4,30 @@ A ruby wrapper for the ESPN api.  It allows you to interact, in a semantically p
 
 ## Installation
 
+### As of Version 0.0.3
+
 Add this line to your application's Gemfile:
     
     gem 'espn_rb'
+    
+In order to use espn_rb you need to first get an API key from ESPN [ESPN api request](http://developer.espn.com/member/register).  Once you've gotten that squared away you can use the public requests straight away.  
+
+
+## Set your API key
+
+The easiest way to set your api key for use with espn_rb is to export it as an environment variable. Do that like so:
+
+```sh
+ $ export espn_api_key=YOUR_SUPER_SECRET_API_KEY 
+```
+
+If you want to pass it in to your objects you may do so explicitly like so:
+
+```ruby
+  espn = EspnRb.headlines(:api_key => YOUR_SUPER_SECRET_API_KEY)
+```
+
+For the sake of simplicity all my examples will assume that you have exported the API key as an environment variable. 
 
 ## Espn Headines
 
@@ -21,10 +42,12 @@ espn = Espn.headlines
 espn.all
 ```
 
-Which will return an HeadlineResponse object.  To get the response straight from the horses' mouth:
+Which will return an HeadlineResponse object.
 
 #### Get ESPN response as JSON
 
+To get the response straight from the horses' mouth:
+
 ```ruby
 # from above
   
@@ -32,10 +55,12 @@ espn.all.response
 #=> ESPN's response string as JSON
 ```
 
-The raw response from ESPN will give you the top ten stories meeting your criteria.  Since this is a basic collection and each headline share many common attributes there are collection methods defined on the HeadlineResponse object.  Use them like so.
+The raw response from ESPN will give you the top ten stories meeting your criteria.  
 
 #### Collections
 
+Since the above response is a basic collection and each headline share many common attributes there are collection methods defined on the HeadlineResponse object.  Use them like so.
+
 ```ruby
 # from above
 
@@ -59,6 +84,24 @@ espn = EspnRb.headlines
 
 espn.nba(:news) #=> HeadlineResponse
 espn.nba(:top)  #=> HeadlineResponse
+espn.nba({:for_date => "2012-03-09"}) #=> HeadlineResponse
+
+```
+
+#### HeadlineItem
+
+The HeadlineResponse Object holdes in it the headlines split into HeadlineItems.  Here is where you can get Specific information about each story.  Here are some of the options.
+
+```ruby
+espn = EspnRb.headlines
+headline_response = espn.nba[2] #=> HeadlineItem
+
+headline_response.web_url #=> "http://sports.espn.go.com/espn/wire?section=nba&id=7664408&ex_cid=espnapi_public"
+headline_response.id #=> 7664408
+headline_response.title #=> "Mavericks-Kings Preview"
+
+# More to come in future versions.
+headline_response.headline #=> JSON hash from original response.
 ```
 
 #### HELP

data/lib/espn_rb/api_definitions/headline_methods.yaml

@@ -11,3 +11,6 @@
 :for_date:
   :url: /news/dates/:yyyymmdd
   :description: Retrieves news for a specific date.
+:for_athlete:
+  :url: /athletes/:athleteId/news
+  :description: Retrieves stories about a particular player/athlete.

data/lib/espn_rb/headline.rb

@@ -2,20 +2,40 @@ module EspnRb
   class Headline
     attr_reader :api_key
 
+    # @raise [StandardError] Will raise StandardError if api_key isn't specified by either options passed into initialize or set from ENV
     def initialize(opts)
-      @api_key = opts && opts[:api_key].nil? ? opts[:api_key] : ENV['espn_api_key']
+      @api_key = opts && !opts[:api_key].nil? ? opts[:api_key] : ENV['espn_api_key']
       raise StandardError, "You must specify an API key." if @api_key.nil?
+
       create_headline_methods
     end
 
+    # Returns the ESPN resources as defined [here](http://developer.espn.com/docs/headlines#parameters).
+    #
+    # @return [Hash] of sports, urls and their descriptions.
     def api_resources
-      @api_resources ||= YAML::load(File.read('lib/espn_rb/api_definitions/headline_resources.yaml'))
+      @api_resources ||= YAML::load(File.read(File.expand_path(File.join(File.dirname(__FILE__), "..", 'espn_rb/api_definitions/headline_resources.yaml'))))
     end
 
+    # Returns the ESPN methods as defined [here](http://developer.espn.com/docs/headlines#parameters).
+    #
+    # @return [Hash] methods, and their associated urls and brief description.
     def api_methods
-      @api_methods ||= YAML::load(File.read('lib/espn_rb/api_definitions/headline_methods.yaml'))
+      @api_methods ||= YAML::load(File.read(File.expand_path(File.join(File.dirname(__FILE__), "..", 'espn_rb/api_definitions/headline_methods.yaml'))))
     end
 
+    # The final request to ESPN api after all option parsing has been completed.
+    # @return [HeadlineResponse] a headline response object.
+    def get_results(resource, method)
+      http = Net::HTTP.new("api.espn.com")
+      request = Net::HTTP::Get.new("/#{EspnRb::API_VERSION}#{resource}#{method}?apikey=#{@api_key}")
+      HeadlineResponse.new JSON.parse(http.request(request).body)
+    end
+
+    # This will define singleton methods for all resources defined
+    # in EspnRb::Headline.api_resources
+    #
+    # @return [HeadlineResponse] which contains the espn response object and assocated methods.
     def create_headline_methods
       api_resources.each do |k,v|
         define_singleton_method(k) do |opt=nil|
@@ -24,26 +44,57 @@ module EspnRb
       end
     end
 
+    # Attempts to parse which EspnRb::Headline.api_methods the user has passed to
+    # method defined by EspnRb::Headline.create_headline_methods.
+    #
+    # @param [Hash] options the options passed in by user.
+    # @note This will accept either a string or a hash.
+    #
+    # @example Call with string
+    #   get_api_method("news") #=> '/news'
+    #
+    # @example Call with Hash (for_date)
+    #   get_api_method({:for_date => "2012-01-01"}) #=> '/news/dates/20120101'
+    # @option options [String] :arg When string is passed and :arg
+    #   is available it will return the url associated with that :arg from EspnRb::Headline.api_methods
+    # @option options [Hash] :arg When Hash will pass :arg to opt_from_hash
+    #
+    # @return [String] a url entry from EspnRb::Headline.api_methods defaults to :news
     def get_api_method(opt)
       case opt.class.to_s
       when "Symbol"
-         api_method = api_methods.keys.include?(opt) ? api_methods[opt][:url] : (raise StandardError, "The parameter you sent is not available.")
+        api_method = api_methods.keys.include?(opt) ? api_methods[opt][:url] : (raise StandardError, "The parameter you sent is not available.")
       when "Hash"
-        unless opt[:for_date].nil?
-          api_method = api_methods[:for_date][:url].gsub(":yyyymmdd", Date.parse(opt[:for_date]).strftime("%Y%m%d"))
-        else
-        end
+        api_method = opt_from_hash(opt)
       else
-       api_method = api_methods[:news][:url]
+        api_method = api_methods[:news][:url]
       end
     end
 
-    def get_results(resource, method)
-      http = Net::HTTP.new("api.espn.com")
-      request = Net::HTTP::Get.new("/#{EspnRb::API_VERSION}#{resource}#{method}?apikey=#{@api_key}")
-      HeadlineResponse.new JSON.parse(http.request(request).body)
+    def opt_from_hash(opt)
+      if !opt[:for_date].nil?
+        for_date opt
+      elsif !opt[:for_athlete].nil?
+        for_athlete opt
+      end
+    end
+
+    # Takes EspnRb::Headline.api_methods[:for_athlete][:url] and subs out the options passed by user
+    # @example internal call
+    #   for_athlete({:for_athlete => "123"}) => '/athletes/123/news'
+    def for_athlete(opt)
+      api_methods[:for_athlete][:url].gsub(":athleteId", opt[:for_athlete])
+    end
+
+    # Takes EspnRb::Headline.api_methods[:for_date][:url] and subs out the options passed by user
+    # @example internal call
+    #   for_date({:for_date => "2012-01-01"}) => '/news/dates/20120101'
+    def for_date(opt)
+      api_methods[:for_date][:url].gsub(":yyyymmdd", Date.parse(opt[:for_date]).strftime("%Y%m%d"))
     end
 
+    # Provides help text.  Passes the methods available from create_headline_methods all prettified into a set of
+    # strings and passes them to EspnRb::Utilities.help which then inserts it below some nice ascii art.
     def help
        EspnRb::Utilities.help api_resources.map {|k,v| "\t#{(':' + k.to_s).ljust(25)} #{v[:description]}"}.join("\n")
     end

data/lib/espn_rb/headline_item.rb

@@ -0,0 +1,81 @@
+class HeadlineResponse
+  class HeadlineItem
+    attr_reader :headline
+
+    def initialize(opts)
+      @headline = opts
+    end
+
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.nba.first.web_url => "http://some-valid-nba-article"
+    # @return [String] web_url for Item
+    def web_url(mobile=false)
+      (mobile == true) ? @headline["links"]["mobile"]["href"] : @headline["links"]["web"]["href"]
+    end
+
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.ncaa_football.first.title => "Gators Win!!"
+    # @return [String] title for Item
+    def title
+      @headline["headline"]
+    end
+
+
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.ncaa_football.first.id => 1234
+    # @return [Integer] id for Item
+    def id
+      @headline["id"]
+    end
+
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.nba.first.api_url => "http://some-valid-nba-article"
+    # @return [String] api_url for Item
+    def api_url
+      @headline["links"]["api"]["news"]["href"]
+    end
+
+
+    def collect_category(sym)
+      @headline["categories"].inject([]) {|m, i| m <<  i[sym.to_s] unless i[sym.to_s].nil?; m}
+    end
+
+    # Provides access to categories sub-hash.  If available
+    #
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.nba.first.athletes
+    # #=> ["Johnny B", "Freddie Flintstone", "Etc"]
+    def athletes
+      return collect_category(:description)
+    end
+
+    # Provides access to categories sub-hash.  If available
+    #
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.nba.first.leagues
+    # #=> ["46"]
+    def leagues
+      return collect_category(:leagueId)
+    end
+
+    # Provides access to categories sub-hash.  If available
+    #
+    # @example
+    #   espn = EspnRb::Headline
+    #   espn.nba.first.athlete_ids
+    # #=> ["123", "132", "123"]
+    def athlete_ids
+      return collect_category(:athleteId)
+    end
+
+    def categories
+      @headline["categories"]
+    end
+  end
+end

data/lib/espn_rb/headline_response.rb

@@ -1,45 +1,46 @@
 class HeadlineResponse
+  include Enumerable
+
   attr_reader :response,:responses
 
+  # Sets response from EspnRb::Headline.get_results.  Splits response object into composite parts
+  # so that we can include enumerable
   def initialize(response)
-    @response = @response || response
+    @response  = @response || response
     @responses = @response['headlines'].map {|h| HeadlineItem.new(h)}
-    @reports = create_reports(reponse)
   end
 
+  # define each so that Enumerable methods work properly.
+  def each &block
+    @responses.each do |response|
+      if block_given?
+        block.call response
+      else
+        yield response
+      end
+    end
+  end
+
+  # Allows the user to specify which HeadlineItem they'd like to work with via it's index in the @responses array
+  #
+  # @return [HeadlineItem] HeadlineItem specified by responses index
   def [](int)
     @responses[int]
   end
 
+  # Defines a few collection methods to allow the user to view all of the @response like attributes
+  # @note available methods are headlines, descriptions, sources, bylines, types
+  #
+  # @example Valid method call
+  #   EspnRb::Headline.nba.titles #=> ['title1', 'title2', 'title3', 'title4', 'etc']
+  # @example Invalid method call
+  #   EspnRb::Headline.nba.not_an_available_method #=> nil
+  # @return [Array] array of like items or nil
   def method_missing(sym, *args)
-    sym.to_s == "titles"? sym = :headlines : sym
+    sym.to_s == "titles" ? sym = :headlines : sym
 
     if %w{headlines descriptions sources bylines types}.include?(sym.to_s)
       @response["headlines"].map {|h| h[sym.to_s[0..-2]]  }
     end
   end
-
-  class HeadlineItem
-    attr_reader :headline
-
-    def initialize(opts)
-      @headline = opts
-    end
-
-    def web_url(mobile=false)
-      (mobile == true) ? @headline["links"]["mobile"]["href"] : @headline["links"]["web"]["href"]
-    end
-
-    def title
-      @headline["headline"]
-    end
-
-    def id
-      @headline["id"]
-    end
-
-    def api_url
-      @headline["links"]["api"]["news"]["href"]
-    end
-  end
 end

data/lib/espn_rb/utilities.rb

@@ -3,11 +3,11 @@ module EspnRb
     def self.help(str)
       puts "-----------------------------Welcome to EspnRb.---------------------------------\n\n"
       puts s = <<EOF
-                                        _.-=""=-._
-                                      .'\\\\-++++-//'.
-                                     (  ||      ||  )
-                                      './/      \\\\.'
-                                        `'-=..=-'`
+                               _.-=""=-._
+                             .'\\\\-++++-//'.
+                            (  ||      ||  )
+                             './/      \\\\.'
+                               `'-=..=-'`
 EOF
       puts "--------------------------------------------------------------------------------"
       puts "You are currently using the headlines api from here you can do the follow:\n\n"

data/lib/espn_rb/version.rb

@@ -1,4 +1,4 @@
 module EspnRb
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
   API_VERSION = "v1"
 end

data/lib/espn_rb.rb

@@ -1,6 +1,7 @@
 require "espn_rb/version"
 require "espn_rb/headline.rb"
 require 'espn_rb/headline_response.rb'
+require 'espn_rb/headline_item.rb'
 require 'espn_rb/utilities.rb'
 
 require 'json'
@@ -9,6 +10,11 @@ require "net/http"
 module EspnRb
   include EspnRb::Utilities
 
+  # Returns an EspnRb::Headline object.
+  #
+  # @param [Hash] options the options to create the Headline object.
+  # @option options [String] :api_key Your ESPN developer api key.
+  # @return [EspnRb::Headline] entry point to Espn Headline API.
   def self.headlines(options=nil)
     EspnRb::Headline.new(options)
   end

data/spec/espn_rb_spec.rb

@@ -11,14 +11,19 @@ describe EspnRb::Headline do
                     :headers => {})
   end
 
-  it "should return valid HeadlineResponse when #all is called." do
+  it "#all should return valid HeadlineResponse" do
     @espn.all.class.should eq(HeadlineResponse)
   end
 
-  it "get_results from api.espn.com" do
+  it "#get_results from api.espn.com" do
     @espn.get_results(@espn.api_resources[:all][:url], @espn.api_methods[:news][:url]).class.should eq(HeadlineResponse)
   end
 
+  it "@api_key should be set" do
+    espn = EspnRb.headlines(:api_key => "abc123")
+    espn.api_key.should eq "abc123"
+  end
+
   context "api_resources and api_methods should be defined properly (Ensure no typos)" do
     it {@espn.api_resources[:nba][:url].should eq("/sports/basketball/nba") }
     it {@espn.api_resources[:all][:url].should eq("/sports") }
@@ -40,9 +45,29 @@ describe EspnRb::Headline do
 
 
   describe HeadlineResponse do
-    context "returns the correct title information when #title is called" do
+    context "Method missing provides correct collection methods." do
      it {@espn.all.titles.first.should eq("Trail Blazers 86, Hornets 74")}
-     it {@espn.all.titles.last.should eq("Saint Mary's (Cal) 78, No. 24 Gonzaga 74") }
+     it {@espn.all.descriptions.last.should eq("With the score deadlocked in overtime and the ball bouncing free, opposing guards Matthew Dellavedova and Kevin Pangos collided near the scorer's table.") }
+     it {@espn.all.sources.last.should eq("Associated Press") }
+     it {@espn.all.types.last.should eq("Wire") }
+    end
+  end
+
+  describe HeadlineResponse::HeadlineItem do
+    context "HeadlineItem returns proper item info when requested" do
+     it { @espn.all[1].web_url.should  == 'http://sports.espn.go.com/espn/wire?section=nhl&id=7651009&ex_cid=espnapi_public' }
+     it { @espn.all[1].title.should  == 'Oilers-Sharks Preview' }
+     it { @espn.all[1].api_url.should  == 'http://api.espn.com/v1/sports/news/7651009' }
+     it { @espn.all[1].id.should  == 7651009 }
+    end
+
+    context "HeadlineItem should return an array of requested entries from categories sub-hash" do
+      it {@espn.all[1].athletes.should == ["NHL", "San Jose Sharks", "Edmonton Oilers", "Douglas Murray",
+                                           "Logan Couture", "Patrick Marleau", "Joe Thornton", "Anaheim Ducks",
+                                           "Jordan Eberle", "Shawn Horcoff", "Taylor Hall"] }
+
+      it {@espn.all[1].leagues.should == [90] }
+      it {@espn.all[1].athlete_ids.should  == [2100, 3773, 576, 939, 5032, 1080, 5428] }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: espn_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-09 00:00:00.000000000 Z
+date: 2012-03-11 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby wrapper for ESPN's api.
 email:
@@ -29,6 +29,7 @@ files:
 - lib/espn_rb/api_definitions/headline_methods.yaml
 - lib/espn_rb/api_definitions/headline_resources.yaml
 - lib/espn_rb/headline.rb
+- lib/espn_rb/headline_item.rb
 - lib/espn_rb/headline_response.rb
 - lib/espn_rb/utilities.rb
 - lib/espn_rb/version.rb
@@ -63,3 +64,4 @@ test_files:
 - spec/espn_rb_spec.rb
 - spec/mock_requests/all_headlines_request.txt
 - spec/spec_helper.rb
+has_rdoc: