npr 1.1.0 → 1.2.0

data/.travis.yml

@@ -1,8 +1,5 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 1.9.3
   - 1.9.2
-  - ruby-head
-
-notifications:
-  email: false

data/CHANGELOG.md

@@ -1,20 +1,46 @@
+### Version 1.2.0 (2013-08-05)
+##### Additions
+* Added support for the `parent` node.
+* Added the `#link_for` method for any node which has (multiple) nested links.
+* Added `#download?`, `#stream?`, and `#embed?` methods to Permission, to return
+  booleans of whether that permission is allowed.
+* Added support for the `externalAsset` node, as `Story#external_assets (array)`
+
+##### Changes
+* None
+
+##### Deprecations
+* None
+
+
+
 ### Version 1.1.0 (2013-06-05)
+
+##### Additions
 * Allow passing `:url` option to Client, and `:path` option to `Client#query`
 * Allow passing `:apiKey` and `:output` to `Client#query`
+* Add an Image#crop method, to find a specific crop by its type.
+
+##### Changes
 * Handle an HTTP Error from the API better. If the API response is not a
   success (as defined by `Faraday::Response#success?`), then an 
   `NPR::APIError` will be raised. An error was being raised before, but
   it was due to a nil error (when response.body was nil), which could be confusing.
-* Add an Image#crop method, to find a specific crop by its type.
+
+##### Deprecations
+  * None
+
 
 
 ### Version 1.0.0
 * Stable release
 
 
+
 ### Version 0.1.2 (2012-12-30)
 * Critical bug fix having to do with JSON parsing.
 
 
+
 ### Version 0.1.1 (2012-12-16)
 * First stable release.

data/README.md

@@ -3,7 +3,8 @@
 [![Build Status](https://travis-ci.org/bricker/npr.png)](https://travis-ci.org/bricker/npr)
  
 A simple Ruby client for the 
-[NPR API](http://www.npr.org/api/index).
+[NPR API](http://www.npr.org/api/index). Alternative documentation for the NPR
+API can be found at <http://dev.npr.org>.
 
 
 ## Support
@@ -11,7 +12,7 @@ A simple Ruby client for the
 This gem is tested with these versions (but may 
 work with others):
 
-* Ruby 1.9.2, 1.9.3, ruby-head
+* Ruby 1.9.2, 1.9.3, 2.0.0
 * NPR API version 0.94
 
 
@@ -105,17 +106,11 @@ for all of the options.
 * Search functionality
 * Add "select" method to QueryBuilder for the "fields" input
 * Abstract attributes so they're not tied directly to the API response.
-Also to make them more Ruby-conventional (i.e. snake_case)
-    * Example: "apiKey" => :api_key
+* Make all attributes snake_case
 * Support for "correction" node
 * Support for "container" node
-* Support for "parent" node
 * Support for "thumbnail" node
-* Support a way to return raw formats of:
-    * HTML / Javascript (for views)
-    * JSON
-    * ATOM
-    * RSS
+* Support a way to return the raw NPRML if requested.
 
 
 ## Contributing

data/lib/npr/api/client.rb

@@ -9,7 +9,7 @@
 #
 # You can also set params via +client.params+
 #
-# Params should be passed in exactly as they will be sent 
+# Params should be passed in exactly as they will be sent
 # to the API. Example: "apiKey", not "api_key"
 # See the API documentation for what those params are.
 #
@@ -56,7 +56,7 @@ module NPR
       #
       def query(params={})
         path = params.delete(:path) || NPR::Configuration::API_QUERY_PATH
-      
+
         response = connection.get do |request|
           request.url path
           request.headers['Content-Type'] = "application/json"
@@ -65,7 +65,7 @@ module NPR
           request.params['output'] ||= "json"  # Only JSON is supported.
           request.params['apiKey'] ||= @apiKey
         end
-        
+
         if response.success?
           NPR::API::Response.new(response)
         else
@@ -74,11 +74,11 @@ module NPR
       end
 
       #-----------------
-    
+
       private
-    
+
       #-----------------
-    
+
       def connection
         @connection ||= begin
           Faraday.new @url do |conn|

data/lib/npr/api/message.rb

@@ -8,26 +8,26 @@ module NPR
   module API
     class Message
       include NPR::Concern::ShallowAttributes
-      
+
       attr_accessor :id, :level
       shallow_attribute "text", "timestamp"
 
       #------------------
-    
+
       def initialize(json)
         @_json = json
         @id    = @_json["id"]
         @level = @_json["level"]
-      
+
         extract_shallow_attributes(@_json)
       end
 
       #------------------
-    
+
       def error?
         self.level == "error"
       end
-    
+
       #------------------
 
       def warning?

data/lib/npr/api/query_builder.rb

@@ -11,16 +11,16 @@ module NPR
         :offset,
         :set
       ]
-    
+
       attr_reader :_klass, :builder
 
       #-----------------------
-    
+
       def initialize(klass)
         @_klass  = klass
         @builder = {}
       end
-    
+
       #-----------------------
       # Build the params hash.
       # This is automatically called by #to_a, so it probably
@@ -31,13 +31,13 @@ module NPR
         else
           conditions = @builder[:conditions]
         end
-      
+
         params = conditions || {}
         params[:sort]       = @builder[:order]  if @builder[:order]
         params[:numResults] = @builder[:limit]  if @builder[:limit]
         params[:startNum]   = @builder[:offset] if @builder[:offset]
         params.merge!(@builder[:extra])         if @builder[:extra]
-        
+
         params
       end
 
@@ -68,19 +68,19 @@ module NPR
       def to_a
         response = self.query
         stories  = []
-      
+
         if response.list
           stories = Array.wrap(response.list.stories)
         end
-      
+
         stories
       end
-      
+
       #-----------------------
       # Fire the query and return the full Response object
-      # 
+      #
       # Example:
-      # 
+      #
       #   query = NPR::API::QueryBuilder.new(NPR::Story)
       #   query.where(:id => [100, 150]).query
       #   #=> NPR::API::Response
@@ -110,7 +110,7 @@ module NPR
         @builder[:extra] = (@builder[:extra] || {}).merge(params)
         self
       end
-      
+
       #-----------------------
       # Merge in the passed-in conditions to what
       # already exists.
@@ -132,7 +132,7 @@ module NPR
       #     last_week = Time.new(2012, 10, 21)
       #     yesterday = Time.new(2012, 10, 25)
       #     query.where(date: (last_week..yesterday))
-      # 
+      #
       def where(conditions)
         @builder[:conditions] = (@builder[:conditions] || {}).merge(conditions)
         self
@@ -168,9 +168,9 @@ module NPR
         @builder[:limit] = limit
         self
       end
-    
+
       #-----------------------
-      # Offset the number of results 
+      # Offset the number of results
       # Useful for pagination
       #
       # Accepts an Integer.
@@ -183,35 +183,34 @@ module NPR
         @builder[:offset] = offset
         self
       end
-    
+
       #-----------------------
-    
+
       private
-      
+
       def client
         @client ||= NPR::API::Client.new(:apiKey => NPR.config.apiKey)
       end
-      
+
       #-----------------------
-    
+
       def parse_conditions(conditions)
         parse_conditions!(conditions.dup)
       end
 
       #-----------------------
-    
+
       def parse_conditions!(conditions)
-        
         if conditions[:id].is_a? Array
           conditions[:id] = conditions[:id].join(",")
         end
-      
+
         if conditions[:date].is_a? Range
           conditions[:startDate] = conditions[:date].first
           conditions[:endDate]   = conditions[:date].last
           conditions.delete(:date)
         end
-      
+
         conditions
       end
     end # QueryBuilder

data/lib/npr/api/response.rb

@@ -8,24 +8,24 @@ module NPR
   module API
     class Response
       include NPR::Concern::Relation
-      
+
       has_many "messages", :key => "message", :class_name => NPR::API::Message
       attr_reader :raw, :version, :messages, :list
 
       #--------------------------
-      
+
       def initialize(response)
         create_relations(response)
-        
+
         @_response = response
         @raw       = response.body
-        
-        @version  = @raw["version"]
-                
+
+        @version = @raw["version"]
+
         if list = @raw["list"]
           @list = NPR::Entity::List.new(list)
         end
-        
+
         Array.wrap(@raw["message"]).each do |message|
           @messages.push NPR::API::Message.new(message)
         end

data/lib/npr/concern/attr_typecast.rb

@@ -9,7 +9,7 @@ module NPR
   ATTR_TYPES = {
     "id"               => :string_to_i,
     "partnerId"        => :string_to_i,
-    "storyDate"        => :string_time_parse, 
+    "storyDate"        => :string_time_parse,
     "pubDate"          => :string_time_parse,
     "lastModifiedDate" => :string_time_parse,
     "showDate"         => :string_time_parse,
@@ -19,41 +19,39 @@ module NPR
     "timestamp"        => :string_time_at,
     "duration"         => :string_to_i
   }
-  
+
   module Concern
     module AttrTypecast
-      
+
       private
-      
+
       #------------------
       # Typecasting methods
       def string_to_i(value)
         value.to_i
       end
-      
+
       #------------------
-      
+
       def string_time_parse(value)
         !value.empty? ? Time.parse(value) : nil
       end
-      
+
       #------------------
-      
+
       def string_time_at(value)
         Time.at(value.to_f)
       end
-      
-      
-      #------------------
+
       #------------------
-      
+
       def attr_typecast(key, value)
         if method = NPR::ATTR_TYPES[key]
           send method, value
         else
           value
         end
-      end   
+      end
     end # AttrTypecast
   end # Concern
 end # NPR

data/lib/npr/concern/links_association.rb

@@ -0,0 +1,26 @@
+module NPR
+  module Concern
+    module LinksAssociation
+      def self.included(base)
+        base.has_many "links", :key => "link", :class_name => NPR::Entity::Link
+      end
+
+      #-------------------------
+      # Find links of the passed in type.
+      #
+      # Example:
+      #
+      #   story.link_for("html")    #=> http://npr.org/...
+      #   story.link_for("nothing") #=> nil
+      #
+      # Returns an the content of that link if found,
+      # or nil if not found.
+      #
+      def link_for(type)
+        if link = self.links.find { |link| link.type == type }
+          link.to_s
+        end
+      end
+    end # LinkAssociation
+  end # Concern
+end # NPR

data/lib/npr/concern/relation.rb

@@ -9,13 +9,13 @@ module NPR
       end
 
       #-----------------
-      
+
       module ClassMethods
         #-----------------
         # Define a relationship
         # Similar to ActiveRecord's +has_many+
         #
-        # Arguments: 
+        # Arguments:
         #
         # * name (String) - the name of the relation
         # * options (Hash)
@@ -28,7 +28,7 @@ module NPR
         #
         def has_many(name, options)
           relation = build_relation(name, options)
-          
+
           # Define getter and setter for this attribute
           # Forces the relation into an empty array when
           # it's first accessed.
@@ -36,7 +36,7 @@ module NPR
           define_method name do
             instance_variable_get("@#{name}") || instance_variable_set("@#{name}", [])
           end
-          
+
           _has_many_relations.push relation
         end
 
@@ -47,25 +47,25 @@ module NPR
           attr_accessor name
           _has_one_relations.push relation
         end
-        
+
         #-----------------
-      
+
         def _has_many_relations
           @_has_many_relations ||= []
         end
-        
+
         def _has_one_relations
           @_has_one_relations ||= []
         end
 
         #-----------------
-    
+
         private
         attr_writer :_has_many_relations, :_has_one_relations
-        
+
         def build_relation(name, options)
-          relation = { 
-            :name       => name, 
+          relation = {
+            :name       => name,
             :class_name => options[:class_name],
             :key        => options[:key] || name
           }
@@ -76,22 +76,22 @@ module NPR
       #-----------------
 
       private
-      
+
       #-----------------
-      # Populate the relations based on 
+
       def create_relations(json)
         self.class._has_many_relations.each do |relation|
           collection = []
-        
+
           if node = json[relation[:key]]
-            node.each do |obj| 
+            node.each do |obj|
               collection.push relation[:class_name].new(obj)
             end
           end
-        
+
           send "#{relation[:name]}=", collection
         end
-        
+
         self.class._has_one_relations.each do |relation|
           if node = json[relation[:key]]
             send "#{relation[:name]}=", relation[:class_name].new(node)

data/lib/npr/concern/shallow_attributes.rb

@@ -7,15 +7,15 @@
 #
 # Example:
 #
-#   { "link": { "$text": "www.google.com" } }
-#   
-#   shallow_attribute "link"
+#   { "link": { "$text": "http://npr.org" } }
 #
+#   shallow_attribute "link"
+#   @story.link # => "http://npr.org"
 module NPR
   module Concern
     module ShallowAttributes
       include AttrTypecast
-      
+
       def self.included(base)
         base.extend ClassMethods
       end
@@ -27,23 +27,23 @@ module NPR
           _shallow_attributes.push *attrs
           attr_accessor *attrs
         end
-        
+
         #-----------------
-      
+
         def _shallow_attributes
           @shallow_attributes ||= []
         end
-        
+
         #-----------------
-        
+
         private
         attr_writer :_shallow_attributes
       end
-      
+
       #-----------------
-      
+
       private
-      
+
       #-----------------
       # Extract the defined shallow_attributes from the JSON
       # and set the corresponding attribute.
@@ -68,4 +68,4 @@ module NPR
       end
     end # ShallowAttribute
   end # Concern
-end # NPR
+end # NPR

data/lib/npr/configuration.rb

@@ -1,7 +1,7 @@
 ##
 # NPR::Configuration
 #
-module NPR  
+module NPR
   #-------------------
   # Pass a block to configure NPR client globally.
   #
@@ -24,11 +24,11 @@ module NPR
   end
 
   #-------------------
-  
+
   def self.config
     @config ||= NPR::Configuration.new
   end
-  
+
   #-------------------
   # NPR::Configuration
   #
@@ -38,52 +38,52 @@ module NPR
   #
   class Configuration
     API_ROOT = "http://api.npr.org"
-    
+
     API_QUERY_PATH = "/query"
     API_LIST_PATH  = "/list"
-    
+
     # List all the parameters that the NPR API
-    # can accept. Some are left out that don't 
+    # can accept. Some are left out that don't
     # make sense to globally configure (such as
     # +:id+, +:startNum+, and +:callback+)
     API_OPTIONS = [
       # List options
-      :storyCountAll, 
-      :storyCountMonth, 
+      :storyCountAll,
+      :storyCountMonth,
       :storyCountToday,
-      :childrenOf, 
+      :childrenOf,
       :hideChildren,
-      
+
       # Story options
-      :apiKey, 
-      :orgId, 
-      :meta, 
-      :output, 
+      :apiKey,
+      :orgId,
+      :meta,
+      :output,
       :fields,
-      :sort, 
-      :numResults, 
-      :action, 
+      :sort,
+      :numResults,
+      :action,
       :requiredAssets,
-      :date, 
-      :startDate, 
-      :endDate, 
+      :date,
+      :startDate,
+      :endDate,
       :dateType,
-      :searchTerm, 
-      :searchType, 
+      :searchTerm,
+      :searchType,
       :title
     ]
-    
+
     attr_accessor *API_OPTIONS
 
     #-------------------
-    # You can pass in a hash of options to 
+    # You can pass in a hash of options to
     # Configuration.new
     def initialize(options={})
       options.each do |key, value|
         send "#{key}=", value
       end
     end
-    
+
     #-------------------
     # Convenience method
     def merge(hash)
@@ -96,12 +96,12 @@ module NPR
     # Why don't we inherit from OrderedOptions?
     #
     # Since the API options are out of our control
-    # (without having to map every API option to 
+    # (without having to map every API option to
     # internal methods), it is possible that one
     # of the config options will conflict with
     # something in Ruby. For example, the "sort"
     # option that the NPR API allows would mean
-    # we'd have to overwrite Ruby's Hash#sort 
+    # we'd have to overwrite Ruby's Hash#sort
     # method.
     #
     # We *could* just map out config options to