espn_rb 0.0.4 → 0.0.5

data/README.md

@@ -1,16 +1,16 @@
 # EspnRb
 
-A ruby wrapper for the ESPN api.  It allows you to interact, in a semantically pleasing way, with the ESPN api.  Currently it only allows access to the publicly available Headline API which can be found [here](http://developer.espn.com/docs/headlines).  I am working to bring more of ESPN's features to espn_rb.  While I do that I'll try to keep this document updated to its current functionality.  That said, I hope you enjoy. 
+A ruby wrapper for the ESPN api.  It allows you to interact, in a semantically pleasing way, with the ESPN api.  Currently it only allows access to the publicly available Headline API which can be found [here](http://developer.espn.com/docs/headlines).  I am working to bring more of ESPN's features to espn_rb.  While I do that I'll try to keep this document updated to its current functionality.  That said, I hope you enjoy.
 
-## Installation
+![ESPN api logo](http://a.espncdn.com/i/apis/attribution/espn-api-black_200.png "See more branding options at developer.espn.com/branding")  in mind.  ^_^
 
-### As of Version 0.0.3
+## Installation
 
 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.  
+
+    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
@@ -18,7 +18,7 @@ In order to use espn_rb you need to first get an API key from ESPN [ESPN api req
 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 
+ $ 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:
@@ -27,7 +27,7 @@ If you want to pass it in to your objects you may do so explicitly like so:
   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. 
+For the sake of simplicity all my examples will assume that you have exported the API key as an environment variable.
 
 ## Espn Headines
 
@@ -40,22 +40,44 @@ require 'espn_rb'
 espn = Espn.headlines
 
 espn.all
+#=> HeadlineResponse
 ```
 
 Which will return an HeadlineResponse object.
 
-#### Get ESPN response as JSON
+#### Get ESPN response as a hash
 
 To get the response straight from the horses' mouth:
 
 ```ruby
 # from above
-  
+
 espn.all.response
-#=> ESPN's response string as JSON
+#=> ESPN's response string as a hash
 ```
 
-The raw response from ESPN will give you the top ten stories meeting your criteria.  
+The raw response from ESPN will give you the top ten stories meeting your criteria.
+
+### HeadlineResponse
+
+Now includes Enumerable which allows you to treat the HeadlineResponse as an iterable object.
+
+```ruby
+espn = EspnRb.headlines
+espn.all.map(&:title)
+
+#=> ["Celtics-Clippers Preview",
+#    "Warriors 97, Clippers 93",
+#    "Hawks 106, Kings 99",
+#    "Warriors-Clippers, Box",
+#    "Warriors 97, Clippers 93",
+#    "Hawks 106, Kings 99",
+#    "Bucks-Nets Preview",
+#    "Hawks-Kings, Box",
+#    "Grizzlies 94, Nuggets 91",
+#    "Grizzlies-Nuggets, Box"]
+
+```
 
 #### Collections
 
@@ -66,9 +88,9 @@ Since the above response is a basic collection and each headline share many comm
 
 # Available methods are [headlines descriptions sources bylines types]
 
-espn.all.response.titles 
+espn.all.response.titles
 #=> ["array", "of", "ESPN", "titles"]
-    
+
 espn.all.response.descriptions
 #=> ["array", "of", "ESPN", "descriptions"]
 
@@ -84,26 +106,49 @@ espn = EspnRb.headlines
 
 espn.nba(:news) #=> HeadlineResponse
 espn.nba(:top)  #=> HeadlineResponse
-espn.nba({:for_date => "2012-03-09"}) #=> HeadlineResponse
+espn.nba(:for_date => "2012-03-09")  #=> HeadlineResponse # Will include all stories for that date
+espn.nba(:for_athlete => "1234")     #=> HeadlineResponse # Will include all stories for that athleteId
 
 ```
 
-#### HeadlineItem
+### 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.
+The HeadlineResponse Object holdes in it the headlines split into HeadlineItems.  Here is where you can get Specific information about each story.  Some of the options are:
 
 ```ruby
 espn = EspnRb.headlines
-headline_response = espn.nba[2] #=> HeadlineItem
+headline_item = 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"
+headline_item.web_url #=> "http://sports.espn.go.com/espn/wire?section=nba&id=7664408&ex_cid=espnapi_public"
+headline_item.id #=> 7664408
+headline_item.title #=> "Mavericks-Kings Preview"
+headline_item.athletes #=> ["Johnny B", "Freddie Flintstone", "Etc"]
+headline_item.leagues #=> ["46"]
+headline_item.athlete_ids #=> ["123", "132", "123"]
 
 # More to come in future versions.
 headline_response.headline #=> JSON hash from original response.
 ```
 
+HeadlineItem will now also respond to #images which will return an HeadlineResponse::HeadlineItem::Images class which contains the images associated with the HeadlineItem in a class that is also enumerable which lets you access the images with nice little methods like:
+
+```ruby
+espn = EspnRb.headlines
+headline_item = espn.nfl[2]
+
+headline_item.images => HeadlineResponse::HeadlineItem::Images
+
+# or to actually use the images
+
+images = headline_item.images
+
+images.first.landscape #=> true
+images.first.url #=> http://path-to-img.com/blah-blah-blah
+
+# or list all the urls
+
+images.map(&:url) #=>  ["list", "of", "image", "urls"]
+```
 #### HELP
 
 ```ruby

data/lib/espn_rb.rb

@@ -2,6 +2,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/headline_image.rb'
 require 'espn_rb/utilities.rb'
 
 require 'json'

data/lib/espn_rb/headline.rb

@@ -33,7 +33,7 @@ module EspnRb
     end
 
     # This will define singleton methods for all resources defined
-    # in EspnRb::Headline.api_resources
+    # in EspnRb::Headline#api_resources
     #
     # @return [HeadlineResponse] which contains the espn response object and assocated methods.
     def create_headline_methods
@@ -86,7 +86,7 @@ module EspnRb
       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
+    # 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)

data/lib/espn_rb/headline_image.rb

@@ -0,0 +1,68 @@
+class HeadlineResponse
+  class HeadlineItem
+    class Images
+      include Enumerable
+      attr_reader :images
+
+      def initialize(images)
+        @images = images.map {|img| Image.new img }
+      end
+
+      def each &block
+        @images.each &block
+      end
+
+      def [](int)
+        @images[int]
+      end
+    end
+
+    class Image
+      attr_reader :image
+
+      def initialize(image)
+        @image = image
+      end
+
+      # returns true if the image is landscape oriented.
+      def landscape?
+        @image["width"] > @image["height"]
+      end
+
+      # returns true if the image is portrait oriented.
+      def portrait?
+        !landscape?
+      end
+
+      # returns caption of image
+      def caption
+        @image["caption"]
+      end
+
+      # returns name of image
+      def name
+        @image["name"]
+      end
+
+      # returns url of image
+      def url
+        @image["url"]
+      end
+
+      # returns credit (attribution) of image
+      def credit
+        @image["credit"]
+      end
+
+      # returns width of image
+      def width
+        @image["width"]
+      end
+
+      # returns height of image
+      def height
+        @image["height"]
+      end
+    end
+  end
+end

data/lib/espn_rb/headline_item.rb

@@ -7,7 +7,7 @@ class HeadlineResponse
     end
 
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.nba.first.web_url => "http://some-valid-nba-article"
     # @return [String] web_url for Item
     def web_url(mobile=false)
@@ -15,24 +15,55 @@ class HeadlineResponse
     end
 
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.ncaa_football.first.title => "Gators Win!!"
     # @return [String] title for Item
     def title
       @headline["headline"]
     end
 
+    # @example
+    #   espn = EspnRb.headlines
+    #   espn.ncaa_football.first.description => "Some string about what happened in the article."
+    # @return [String] description for Item
+    def description
+      @headline["description"]
+    end
+
+    # @example
+    #   espn = EspnRb.headlines
+    #   espn.ncaa_football.first.source => "Page 2"
+    # @return [String] source for Item
+    def source
+      @headline["source"]
+    end
+
+    # @example
+    #   espn = EspnRb.headlines
+    #   espn.ncaa_football.first.last_modified => "2012-03-16T04:07:56Z"
+    # @return [String] title for Item
+    def last_modified
+      @headline["lastModified"]
+    end
+
+    # @example
+    #   espn = EspnRb.headlines
+    #   espn.ncaa_football.first.last_modified => "2012-03-16T04:07:56Z"
+    # @return [Images] Images class containing the collection of images associated with the item.
+    def images
+      Images.new @headline["images"]
+    end
 
     # @example
-    #   espn = EspnRb::Headline
-    #   espn.ncaa_football.first.id => 1234
+    #   espn = EspnRb.headlines
+    #   espn.ncaa_football.first.id => '1234'
     # @return [Integer] id for Item
     def id
       @headline["id"]
     end
 
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.nba.first.api_url => "http://some-valid-nba-article"
     # @return [String] api_url for Item
     def api_url
@@ -47,7 +78,7 @@ class HeadlineResponse
     # Provides access to categories sub-hash.  If available
     #
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.nba.first.athletes
     # #=> ["Johnny B", "Freddie Flintstone", "Etc"]
     def athletes
@@ -57,7 +88,7 @@ class HeadlineResponse
     # Provides access to categories sub-hash.  If available
     #
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.nba.first.leagues
     # #=> ["46"]
     def leagues
@@ -67,7 +98,7 @@ class HeadlineResponse
     # Provides access to categories sub-hash.  If available
     #
     # @example
-    #   espn = EspnRb::Headline
+    #   espn = EspnRb.headlines
     #   espn.nba.first.athlete_ids
     # #=> ["123", "132", "123"]
     def athlete_ids

data/lib/espn_rb/headline_response.rb

@@ -3,7 +3,7 @@ class HeadlineResponse
 
   attr_reader :response,:responses
 
-  # Sets response from EspnRb::Headline.get_results.  Splits response object into composite parts
+  # 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
@@ -12,13 +12,7 @@ class HeadlineResponse
 
   # 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
+    @responses.each &block
   end
 
   # Allows the user to specify which HeadlineItem they'd like to work with via it's index in the @responses array
@@ -28,13 +22,22 @@ class HeadlineResponse
     @responses[int]
   end
 
+  # Returns the all the links associated with this HeadlineResponse
+  # @option options [String] :type Either web, or mobile.
+  # @return [Array] array of links.
+  def links(type=nil)
+    type = type.nil? ? "web" : type
+    @response["headlines"].map{|r| r["links"][type]["href"] }
+  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']
+  #   EspnRb.headlines.nba.titles #=> ['title1', 'title2', 'title3', 'title4', 'etc']
   # @example Invalid method call
-  #   EspnRb::Headline.nba.not_an_available_method #=> nil
+  #   EspnRb.headlines.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

data/lib/espn_rb/version.rb

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

data/spec/espn_rb_spec.rb

@@ -59,6 +59,10 @@ describe EspnRb::Headline do
      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 }
+     it { @espn.all[1].title.should == "Oilers-Sharks Preview" }
+     it { @espn.all[1].description.should  == "The San Jose Sharks are trying to reverse what's becoming a free fall through the Western Conference standings."}
+     it { @espn.all[1].source.should == "Associated Press"}
+     it { @espn.all[1].last_modified.should == "2012-03-06T06:55:01Z"}
     end
 
     context "HeadlineItem should return an array of requested entries from categories sub-hash" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: espn_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-11 00:00:00.000000000 Z
+date: 2012-03-22 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_image.rb
 - lib/espn_rb/headline_item.rb
 - lib/espn_rb/headline_response.rb
 - lib/espn_rb/utilities.rb