npr 0.0.0 → 0.1.0

data/lib/npr/concern/relation.rb

@@ -0,0 +1,103 @@
+##
+# NPR::Concern::Relation
+#
+module NPR
+  module Concern
+    module Relation
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      #-----------------
+      
+      module ClassMethods
+        #-----------------
+        # Define a relationship
+        # Similar to ActiveRecord's +has_many+
+        #
+        # Arguments: 
+        #
+        # * name (String) - the name of the relation
+        # * options (Hash)
+        #     * class_name (Class) - the class for the related objects
+        #     * key (String) - the JSON key that holds this relation
+        #
+        # Example:
+        #
+        #   has_many "links", key: "link", class_name: NPR::Entity::Link
+        #
+        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.
+          attr_writer name
+          define_method name do
+            instance_variable_get("@#{name}") || instance_variable_set("@#{name}", [])
+          end
+          
+          _has_many_relations.push relation
+        end
+
+        #-----------------
+
+        def has_one(name, options)
+          relation = build_relation(name, options)
+          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, 
+            :class_name => options[:class_name],
+            :key        => options[:key] || name
+          }
+        end
+      end
+
+
+      #-----------------
+
+      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| 
+              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)
+          end
+        end
+      end
+    end # Relation
+  end # Concern
+end # NPR

data/lib/npr/concern/shallow_attributes.rb

@@ -0,0 +1,71 @@
+##
+# NPR::Concern::ShallowAttributes
+#
+# A "shallow attribute" is one that only contains the "$text"
+# node. Use this class method to define which attributes those
+# are.
+#
+# Example:
+#
+#   { "link": { "$text": "www.google.com" } }
+#   
+#   shallow_attribute "link"
+#
+module NPR
+  module Concern
+    module ShallowAttributes
+      include AttrTypecast
+      
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      #-----------------
+
+      module ClassMethods
+        def shallow_attribute(*attrs)
+          _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.
+      #
+      # If the JSON doesn't contain a key for an attribute,
+      # then attribute will remain at its default state (nil).
+      #
+      # Arguments: Hash of the JSON for this object
+      #
+      # Example:
+      #
+      #   def initialize(json)
+      #     extract_shallow_attributes(json)
+      #   end
+      #
+      def extract_shallow_attributes(json)
+        self.class._shallow_attributes.each do |key|
+          if node = json[key]
+            send "#{key}=", attr_typecast(key, node["$text"].to_s)
+          end
+        end
+      end
+    end # ShallowAttribute
+  end # Concern
+end # NPR

data/lib/npr/concern.rb

@@ -0,0 +1,9 @@
+##
+# NPR::Concern
+#
+# A set of modules to mix in to other classes
+#
+module NPR
+  module Concern
+  end # Concern
+end # NPR

data/lib/npr/configuration.rb

@@ -0,0 +1,120 @@
+##
+# NPR::Configuration
+#
+module NPR  
+  #-------------------
+  # Pass a block to configure NPR client globally.
+  #
+  # Options configured globally will be
+  # passed in to every API request. They can
+  # still be overridden on a per-query or per-client
+  # basis.
+  #
+  # Example:
+  #
+  #   NPR.configure do |config|
+  #     config.apiKey         = "YOUR_API_KEY"
+  #     config.sort           = "date descending"
+  #     config.output         = "NPRML"
+  #     config.requiredAssets = "text"
+  #   end
+  #
+  def self.configure
+    yield config
+  end
+
+  #-------------------
+  
+  def self.config
+    @config ||= NPR::Configuration.new
+  end
+  
+  #-------------------
+  # NPR::Configuration
+  #
+  # Probably doesn't need to be accessed directly.
+  # You can get the global configuration for the NPR
+  # gem by accessing +NPR.config+
+  #
+  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 
+    # make sense to globally configure (such as
+    # +:id+, +:startNum+, and +:callback+)
+    API_OPTIONS = [
+      # List options
+      :storyCountAll, 
+      :storyCountMonth, 
+      :storyCountToday,
+      :childrenOf, 
+      :hideChildren,
+      
+      # Story options
+      :apiKey, 
+      :orgId, 
+      :meta, 
+      :output, 
+      :fields,
+      :sort, 
+      :numResults, 
+      :action, 
+      :requiredAssets,
+      :date, 
+      :startDate, 
+      :endDate, 
+      :dateType,
+      :searchTerm, 
+      :searchType, 
+      :title
+    ]
+    
+    attr_accessor *API_OPTIONS
+
+    #-------------------
+    # 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)
+      to_hash.merge hash
+    end
+
+    #-------------------
+    # Convert this Configuration object into a Hash
+    #
+    # Why don't we inherit from OrderedOptions?
+    #
+    # Since the API options are out of our control
+    # (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 
+    # method.
+    #
+    # We *could* just map out config options to
+    # the API options, but I think it's more
+    # important to keep the gem config options
+    # in perfect sync with the API options.
+    #
+    def to_hash
+      hash = {}
+      instance_variables.each do |var|
+        hash[var[1..-1].to_sym] = instance_variable_get(var)
+      end
+      hash
+    end
+  end # Configuration
+end # NPR

data/lib/npr/core_ext/array/wrap.rb

@@ -0,0 +1,15 @@
+##
+# Copied directly from ActiveSupport
+# <https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/array/wrap.rb>
+#
+class Array
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary || [object]
+    else
+      [object]
+    end
+  end
+end

data/lib/npr/entity/audio.rb

@@ -0,0 +1,28 @@
+##
+# NPR::Entity::Audio
+#
+module NPR
+  module Entity
+    class Audio < Base
+      attr_accessor :id, :type, :stream
+      shallow_attribute "title", "duration", "description", "rightsHolder"
+      has_one "permissions", :class_name => NPR::Entity::Permissions
+      has_one "formats", :key => "format", :class_name => NPR::Entity::Formats
+      
+      #-------------------
+      # +stream+ returns true if "active" is set to "true"
+      # 
+      def initialize(json)
+        @id   = json["id"].to_i
+        @type = json["type"]
+                
+        if json["stream"]
+          @stream = json["stream"]["active"] == "true"
+        end
+        
+        create_relations(json)
+        extract_shallow_attributes(json)
+      end
+    end # Audio
+  end # Entity
+end # NPR

data/lib/npr/entity/author.rb

@@ -0,0 +1,22 @@
+##
+# NPR::Entity::Author
+#
+module NPR
+  module Entity
+    class Author < Base
+      attr_accessor :id, :num
+      shallow_attribute "title"
+      has_one "link", :class_name => NPR::Entity::Link
+      
+      #-----------------
+      
+      def initialize(json)
+        @id  = json["id"].to_i
+        @num = json["num"].to_i
+        
+        create_relations(json)
+        extract_shallow_attributes(json)
+      end
+    end # Author
+  end # Entity
+end # NPR

data/lib/npr/entity/base.rb

@@ -0,0 +1,19 @@
+##
+# NPR::Entity::Base
+#
+# Class for all NPR Objects to inherit from
+#
+module NPR
+  module Entity
+    class Base
+      include NPR::Concern::Relation
+      include NPR::Concern::ShallowAttributes
+      
+      #-----------------
+      # Override this
+      def initialize(json={})
+        @_json = json
+      end
+    end # Base
+  end # Entity
+end # NPR

data/lib/npr/entity/book.rb

@@ -0,0 +1,21 @@
+##
+# NPR::Entity::Book
+#
+module NPR
+  module Entity
+    class Book < Base
+      attr_accessor :id
+      shallow_attribute "title"
+      has_one "link", :class_name => NPR::Entity::Link
+      
+      #---------------------
+      
+      def initialize(json)
+        @id = json["id"].to_i
+
+        extract_shallow_attributes(json)
+        create_relations(json)
+      end
+    end # Book
+  end # Entity
+end # NPR

data/lib/npr/entity/book_edition.rb

@@ -0,0 +1,26 @@
+##
+# NPR::Entity::BookEdition
+#
+module NPR
+  module Entity
+    class BookEdition < Base
+      attr_accessor :id, :format_num
+      shallow_attribute "isbn", "publisher", "pubDate", "pagination", "listPrice"
+      has_one "book", :class_name => NPR::Entity::Book
+      
+      #---------------------
+      # Note that the "format" property is represented on this 
+      # object as "format_num", because of Kernel's "format"
+      def initialize(json)
+        @id         = json["id"].to_i
+        
+        if json["format"]
+          @format_num = json["format"]["$text"].to_i
+        end
+        
+        extract_shallow_attributes(json)
+        create_relations(json)
+      end
+    end # BookEdition
+  end # Entity
+end # NPR

data/lib/npr/entity/byline.rb

@@ -0,0 +1,18 @@
+##
+# NPR::Entity::Byline
+#
+module NPR
+  module Entity
+    class Byline < Base
+      attr_accessor :id
+      shallow_attribute "name"
+      
+      #-----------------
+      
+      def initialize(json)
+        @id = json["id"].to_i
+        extract_shallow_attributes(json)
+      end
+    end # Byline
+  end # Entity
+end # NPR

data/lib/npr/entity/collection.rb

@@ -0,0 +1,11 @@
+##
+# NPR::Entity::Collection
+#
+module NPR
+  module Entity
+    class Collection < Base
+      def initialize(json)
+      end
+    end # Collection
+  end # Entity
+end # NPR

data/lib/npr/entity/crop.rb

@@ -0,0 +1,20 @@
+##
+# NPR::Entity::Crop
+#
+module NPR
+  module Entity
+    class Crop < Base
+      attr_accessor :type, :src, :width, :height
+      
+      #---------------
+      
+      def initialize(json)
+        @type   = json["type"]
+        @src    = json["src"]
+        @width  = json["width"].to_i
+        @height = json["height"].to_i
+      end
+    end # Crop
+  end # Entity
+end # NPR
+

data/lib/npr/entity/enlargement.rb

@@ -0,0 +1,20 @@
+##
+# NPR::Entity::Enlargement
+#
+module NPR
+  module Entity
+    class Enlargement < Base
+      attr_accessor :src
+      shallow_attribute "caption"
+      
+      #---------------
+      
+      def initialize(json)
+        @src = json["src"]
+        extract_shallow_attributes(json)
+      end
+    end # Enlargement
+  end # Entity
+end # NPR
+
+      

data/lib/npr/entity/formats.rb

@@ -0,0 +1,19 @@
+##
+# NPR::Entity::Formats
+#
+# Audio Formats
+module NPR
+  module Entity
+    class Formats < Base
+      has_many "mp3s", :key => "mp3", :class_name => NPR::Entity::MP3
+      shallow_attribute "wm", "rm", "mediastream"
+      
+      #--------------------
+      
+      def initialize(json)
+        extract_shallow_attributes(json)
+        create_relations(json)
+      end
+    end # Formats
+  end # Entity
+end # NPR

data/lib/npr/entity/image.rb

@@ -0,0 +1,33 @@
+##
+# NPR::Entity::Image
+#
+module NPR
+  module Entity
+    class Image < Base
+      attr_accessor :id, :type, :width, :src, :hasBorder, :link
+      shallow_attribute "title", "caption", "producer", "copyright"
+      has_many "crops", :key => "crop", :class_name => NPR::Entity::Crop
+      has_one "enlargement", :class_name => NPR::Entity::Enlargement
+      has_one "provider", :class_name => NPR::Entity::Provider
+      
+      #-------------
+      # NOTE that the "link" attribute here is not cast into a Link
+      # object, and the "url" parameter is ignored. Instead, just 
+      # calling +image.link+ will return the URL parameter.
+      def initialize(json)
+        @id        = json["id"].to_i
+        @type      = json["type"]
+        @width     = json["width"].to_i
+        @src       = json["src"]
+        @hasBorder = json["hasBorder"] == "true"
+        
+        if json["link"]
+          @link = json["link"]["url"]
+        end
+        
+        extract_shallow_attributes(json)
+        create_relations(json)
+      end
+    end # Image
+  end # Entity
+end # NPR

data/lib/npr/entity/intro_text.rb

@@ -0,0 +1,21 @@
+##
+# NPR::Entity::IntroText
+#
+module NPR
+  module Entity
+    class IntroText < Base
+      attr_accessor :num, :content
+      
+      def initialize(json)
+        @num     = json["num"].to_i
+        @content = json["$text"] 
+      end
+      
+      #--------------------
+      
+      def to_s
+        @content
+      end
+    end # IntroText
+  end # Entity
+end # NPR

data/lib/npr/entity/link.rb

@@ -0,0 +1,23 @@
+##
+# NPR::Entity::Link
+#
+module NPR
+  module Entity
+    class Link < Base
+      attr_accessor :type, :content
+      
+      #---------------------
+    
+      def initialize(json)
+        @content = json["$text"]
+        @type    = json["type"]
+      end
+
+      #---------------------
+    
+      def to_s
+        @content
+      end
+    end # Link
+  end # Entity
+end # NPR

data/lib/npr/entity/list.rb

@@ -0,0 +1,28 @@
+##
+# NPR::Entity::List
+#
+module NPR
+  module Entity
+    class List < Base
+      #------------------
+
+      has_many "links",   :key => "link",  :class_name => NPR::Entity::Link
+      has_many "stories", :key => "story", :class_name => NPR::Entity::Story
+
+      #------------------
+
+      shallow_attribute(
+        "title",
+        "teaser",
+        "miniTeaser"
+      )
+
+      #------------------
+    
+      def initialize(json)
+        extract_shallow_attributes(json)
+        create_relations(json)
+      end
+    end # List
+  end # Entity
+end # NPR

data/lib/npr/entity/list_text.rb

@@ -0,0 +1,19 @@
+##
+# NPR::Entity::ListText
+#
+module NPR
+  module Entity
+    class ListText < Base
+      attr_accessor :id, :tag
+      has_many "paragraphs", :key => "paragraph", :class_name => NPR::Entity::Paragraph
+      
+      #-------------------
+      
+      def initialize(json)
+        @id = json["id"].to_i
+        @tag = json["tag"]
+        create_relations(json)
+      end
+    end # ListText
+  end # Entity
+end # NPR

data/lib/npr/entity/member.rb

@@ -0,0 +1,23 @@
+##
+# NPR::Entity::Member
+#
+module NPR
+  module Entity
+    class Member < Base
+      attr_accessor :id
+      has_one "promoArt",    :class_name => NPR::Entity::MemberPromoArt
+      has_one "title",       :class_name => NPR::Entity::Title
+      has_one "author",      :class_name => NPR::Entity::Author
+      has_one "bookEdition", :class_name => NPR::Entity::PromoArtBookEdition
+      has_one "introText",   :class_name => NPR::Entity::IntroText
+      has_one "byline",      :class_name => NPR::Entity::MemberByline
+
+      #------------------
+      
+      def initialize(json)
+        @id = json["id"].to_i
+        create_relations(json)
+      end
+    end # Member
+  end # Entity
+end # NPR