greader 0.0.1

data/README.md

@@ -0,0 +1,14 @@
+# Google Reader API client
+#### This is a Google Reader API client in Ruby.
+
+`gem install greader`
+
+Please read the {GReader} module documentation.
+
+### External links
+
+* [Documentation][doc]
+* [Google Reader API reference][api]
+  
+[doc]: http://rubydoc.info/github/rstacruz/greader
+[api]: http://code.google.com/p/pyrfeed/wiki/GoogleReaderAPI

data/Rakefile

@@ -0,0 +1,5 @@
+$:.push File.expand_path('../test', __FILE__)
+
+task :test do
+  Dir['test/**/*_test.rb'].each { |f| load f }
+end

data/lib/greader.rb

@@ -0,0 +1,103 @@
+require 'json'
+require 'rest_client'  unless defined?(RestClient)
+require 'nokogiri'     unless defined?(Nokogiri)
+
+# Google Reader API client.
+#
+# == Common usage
+#
+# First, log in (returns a {Client} or `nil`):
+#
+#   @client = GReader.auth email: 'test@sinefunc.com', password: 'password'
+#
+# == Common {Client} usage
+#
+# A {Client} has many {Feed Feeds} and {Tag Tags}:
+#
+#   @client.feeds                #=> [#<Feed>, #<Feed>, ...]
+#   @client.tags                 #=> [#<Tag>, #<Tag>, ...]
+#
+#   @client.feed('FEED_ID')
+#   @client.tag('TAG_ID')
+#
+# == Common {Feed} usage
+#
+#   @client.feeds.each do |feed|
+#     p feed.id
+#     p feed.title
+#     p feed.url
+#
+#     # A Feed has many entries
+#     feed.entries.each do |entry|
+#       p entry.title
+#       p entry.content
+#     end
+#   end
+#
+# == Common {Tag} usage
+#
+# A {Tag} also has many feeds:
+#
+#   # Tag
+#   @client.tag('TAG_ID').feeds.each { |feed| }
+#
+# == Other
+#
+#   GReader.version            #=> "0.0.0"
+#
+# == See also
+#
+# {Feed}::   A website's feed.
+# {Entry}::  An entry in a feed.
+# {Tag}::    A feed's tag.
+#
+module GReader
+  PREFIX  = File.expand_path('../greader/', __FILE__)
+  VERSION = "0.0.1"
+
+  autoload :Client,    "#{PREFIX}/client"
+  autoload :Entry,     "#{PREFIX}/entry"
+  autoload :Entries,   "#{PREFIX}/entries"
+  autoload :Feed,      "#{PREFIX}/feed"
+  autoload :Tag,       "#{PREFIX}/tag"
+  autoload :Utilities, "#{PREFIX}/utilities"
+
+  def self.auth(options={})
+    client = GReader::Client.new options
+    client  if client.logged_in?
+  end
+
+  # Returns a list of HTML pre-processors.
+  # HTML snippets will be passed through this.
+  #
+  # @example
+  #   GReader.html_processors << lambda { |s| s.strip }
+  #   GReader.process_html('<p>  ')   #=> '<p>'
+  #
+  def self.html_processors
+    @html_processors ||= Array.new
+  end
+
+  # Processes an HTML snippet through the given HTML
+  # processors.
+  def self.process_html(str)
+    html = str.dup
+    html_processors.each { |proc| html = proc.call(html) }
+    html
+  end
+
+  def self.version
+    VERSION
+  end
+
+  Error      = Class.new(StandardError)
+
+  class ParseError < Error
+    attr_reader :node
+
+    def initialize(message, node)
+      super(message)
+      @node = node
+    end
+  end
+end

data/lib/greader/client.rb

@@ -0,0 +1,162 @@
+module GReader
+  # A client.
+  #
+  # == Common usage
+  #
+  # Greader.auth is the preferred way.
+  #
+  #   @client = GReader.auth email: 'test@sinefunc.com', password: 'password'
+  #   @client = GReader.auth email: 'test@sinefunc.com', access_token: <from oauth>
+  #   @client.nil?  # nil if logging in fails
+  #
+  # You can also use it like so:
+  #
+  #   client = Client.new email: 'test@sinefunc.com', password: 'password'
+  #   client.logged_in?
+  #
+  # See GReader for more common usage of the Client class.
+  #
+  # == Caching and expiration
+  #
+  #   # Caching
+  #   @client.tags
+  #   @client.tags      # Will be retrieved from cache
+  #   @client.expire!
+  #   @client.tags      # Will be re-retrieved online
+  #
+  # == Internal low-level usage
+  #
+  #   # Making calls
+  #   @client.api_get 'subscription/list'   # to /reader/api/0/...
+  #   @client.get 'http://foo'              # to arbitrary URL
+  #
+  class Client
+    include Utilities
+    
+    AUTH_URL   = "https://www.google.com/accounts/ClientLogin"
+    API_URL    = "http://www.google.com/reader/api/0/"
+
+    attr_reader :auth
+    attr_reader :email
+
+    # Constructor.
+    #
+    # The constructor can be called without args, but you won't be able to
+    # do anything that requires authentication (which is pretty much 
+    # everything).
+    #
+    def initialize(options={})
+      authenticate options  if options[:password]
+      @oauth_token = options[:access_token]  if options[:access_token]
+    end
+
+    # Authenticates to the Google Reader service.
+    # @return [true] on success
+    def authenticate(options={})
+      @email = options[:email]
+
+      response = RestClient.post AUTH_URL,
+        'service'  => 'reader',
+        'continue' => 'http://www.google.com/',
+        'Email'    => options[:email],
+        'Passwd'   => options[:password],
+        'source'   => client_name
+
+      m = /Auth=(.*)/i.match(response.to_s)
+      @auth = m ? m[1] : nil
+
+      true
+    rescue RestClient::Forbidden
+      false
+    end
+
+    def logged_in?
+      !@auth.nil? or !@oauth_token.nil?
+    end
+
+    def token
+      @token ||= api_get 'token'
+    end
+
+    # Expires the cache
+    def expire!
+      @feeds = nil
+      @tags  = nil
+    end
+
+    def feeds
+      @feeds ||= begin
+        list = json_get('subscription/list')['subscriptions']
+        list.inject({}) { |h, item| feed = Feed.new self, item; h[feed.to_param] = feed; h }
+      end
+      @feeds.values.sort
+    end
+
+    def feed(what=nil)
+      feeds && @feeds[what.to_s.gsub('/', '_')]
+    end
+
+    def tags
+      @tags ||= begin
+        list = json_get('tag/list')['tags']
+        list.inject({}) { |h, item| tag = Tag.new self, item; h[tag.to_param] = tag; h }
+      end
+      @tags.values.sort
+    end
+
+    def tag(what=nil)
+      tags && @tags[what.gsub('/', '_')]
+    end
+
+    def unread_count
+      json_get 'unread-count', 'all' => 'all'
+    end
+
+    def client_name() "greader.rb/#{GReader.version}"; end
+
+    def get(url, options={})
+      request :get, url, params: options.merge('client' => client_name)
+    end
+
+    def post(url, options={})
+      request :post, url, options.merge('client' => client_name)
+    end
+
+    def json_get(url, options={})
+      JSON.parse get(url, options.merge('output' => 'json'))
+    end
+
+    def request(meth, url, options={})
+      url = API_URL + url
+
+      if @auth
+        auth_request meth, url, options
+      elsif @oauth_token
+        oauth_request meth, url, options
+      else
+        raise Error, "Not logged in"
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}#{email ? ' '+email.inspect : '' }>"
+    end
+
+  protected
+
+    # For those using #auth(email: x, password: x)
+    def auth_request(meth, url, options={})
+      options['Authorization'] = "GoogleLogin auth=#{self.auth}"  if logged_in?
+      RestClient.send meth, url, options
+    end
+
+    # For those using #auth(access_token: x)
+    def oauth_request(meth, url, options={})
+      if meth == :get
+        @oauth_token.get url + '?' + kv_map(options[:params])
+      elsif meth == :post
+        @oauth_token.post url, options
+      end.body
+    end
+  end
+end

data/lib/greader/entries.rb

@@ -0,0 +1,87 @@
+module GReader
+  # Entries list
+  #
+  # == Common usage
+  #
+  # This is what's returned by methods like {Feed#entries} and
+  # {Tag#entries}.
+  #
+  #   entries = tag.entries
+  #
+  # It's a simple array so just use it like so:
+  #
+  #   entries.each { |entry| puts entry }
+  #
+  #   entries.size  #=> 20
+  #
+  # You can also lookup by id:
+  #
+  #   feeds.entries['ENTRY_ID']
+  #
+  # But you can have it load more entries:
+  #
+  #   entries.more
+  #   entries.each { |entry| puts entry }
+  #
+  #   entries.size  #=> 40
+  #
+  # == Internal usage
+  #
+  # Pass it an Atom URL.
+  #
+  #   Entries.fetch @client, @client.atom_url(xxx)
+  #
+  class Entries < Array
+    include Utilities
+
+    attr_reader :continuation  # Continuation token (don't use)
+    attr_reader :client
+
+    # Fetch from atom
+    def self.fetch(client, url, options={})
+      doc      = client.json_get(url, to_params(options))
+      contents = doc['items'].map do |node|
+        Entry.new client, Entry.parse_json(node)
+      end
+
+      new contents, client, options.merge(:url => url)
+    end
+
+    def initialize(contents, client, options={})
+      super contents
+      @continuation = options[:continuation]
+      @url          = options[:url]
+      @client       = client
+    end
+
+    def more
+      # self + fetch(@client, @url, :from => @continuation)
+    end
+
+    def +(other)
+      #
+    end
+
+    # Lookup
+    def [](id)
+      indices[slug(id)]
+    end
+
+  protected
+    def indices
+      @indices ||= entries.inject({}) { |h, entry| h[slug(entry.id)] = entry; h }
+    end
+
+    # Converts normal options to Google's equivalents.
+    # See {Feed#entries}.
+    def self.to_params(options={})
+      params = Hash.new
+      params[:n]  = options[:limit]  if options[:limit]
+      params[:c]  = options[:from]   if options[:from]  # Continuation
+      params[:r]  = 'o'              if options[:order] == :asc
+      params[:ot] = options[:start_time].to_i  if options[:start_time]
+      params
+    end
+  end
+end
+

data/lib/greader/entry.rb

@@ -0,0 +1,158 @@
+module GReader
+  # A feed entry.
+  #
+  # == Common usage
+  #
+  # Getting entries:
+  #
+  #   feed.entries.each { |entry| }
+  #   tag.entries.each { |entry| }
+  #   feed.entries['ENTRY_ID']  # See Entry#id below
+  #
+  # Common metadata:
+  #
+  #   entry.title           #=> "On pride and prejudice" (or #to_s)
+  #   entry.content         #=> "<p>There was a time where..."
+  #   entry.summary         #=> "There was a time where..." (no HTML)
+  #   entry.image_url       # URL of the first image
+  #
+  # More metadata:
+  #
+  #   entry.author          #=> "Rico Sta. Cruz"
+  #   entry.updated         #=> #<Date>
+  #   entry.published       #=> #<Date>
+  #   entry.url             #=> "http://ricostacruz.com/on-pride-and-prejudice.html"
+  #   entry.id              #=> "reader_item_128cb290d31352d9"
+  #
+  # Relationships:
+  #
+  #   entry.feed            #=> #<Feed ...>
+  #
+  # States and actions:
+  #
+  #   # Not implemented yet!
+  #   entry.read?           # Read or not?
+  #   entry.starred?
+  #
+  #   entry.read!           # Mark as read
+  #   entry.unread!         # Mark as unread
+  #
+  class Entry
+    include Utilities
+
+    attr_reader :content
+    attr_reader :author
+    attr_reader :title
+    attr_reader :published
+    attr_reader :updated
+    attr_reader :url
+    attr_reader :id
+
+    attr_reader :feed
+    attr_reader :client
+
+    alias to_s title
+
+    # Constructor.
+    # Can be called with an options hash or a Nokogiri XML node.
+    def initialize(client=Client.new, options)
+      @client  = client
+
+      @feed      = client.feed(options[:feed])
+      @author    = options[:author]
+      @content   = GReader.process_html(options[:content])
+      @title     = options[:title]
+      @published = options[:published]
+      @updated   = options[:updated]
+      @url       = options[:url]
+      @id        = options[:id]
+      @read      = options[:read]
+      @starred   = options[:starred]
+      @options = options
+    end
+
+    def inspect
+      "#<#{self.class.name} \"#{title}\" (#{url})>"
+    end
+
+    def to_param
+      slug @id
+    end
+
+    # Returns a Nokogiri document.
+    def doc
+      @doc ||= Nokogiri.HTML(content)
+    end
+
+    # Returns a short summary
+    # @return [string]
+    # @return [nil]
+    def summary
+      doc = self.doc.dup
+
+      # Remove images and empty paragraphs
+      doc.xpath('*//img').each { |tag| tag.remove }
+      doc.xpath('*//*[normalize-space(.)=""]').each { |tag| tag.remove }
+
+      # The first block
+      el = doc.xpath('//body/p | //body/div').first || doc.xpath('//body').first
+      el and el.text
+    end
+
+    # Returns the {#content} without HTML tags
+    def bare_content
+      strip_tags(content)
+    end
+
+    # Returns the URL of the first image
+    # @return [string]
+    # @return [nil]
+    def image_url
+      url = raw_image_url and begin
+        return nil  if url.include?('feedburner.com') # "Share on Facebook"
+        url
+      end
+    end
+
+    def raw_image_url
+      img = doc.xpath('*//img').first and img['src']
+    end
+
+    def image?
+      ! image_url.nil?
+    end
+
+    def read?
+      @read
+    end
+
+    def starred?
+      @starred
+    end
+
+    # Converts a Noko XML node into a simpler Hash.
+    def self.parse_json(doc)
+      summary = (doc['content'] || doc['summary'])
+      summary = summary['content']  if summary.is_a?(Hash)
+
+      { :url       => doc['alternate'].first['href'],
+        :author    => doc['author'],
+        :content   => summary,
+        :title     => doc['title'],
+        :published => Time.new(doc['published']),
+        :updated   => Time.new(doc['updated']),
+        :feed      => doc['origin']['streamId'],
+        :id        => doc['id'],
+        :read      => doc['categories'].any? { |s| s =~ /com\.google\/fresh$/ },
+        :starred   => doc['categories'].any? { |s| s =~ /com\.google\/starred$/ }
+        # Also available: comments [], annotations [], enclosure 
+        # [{href,type,length}]
+      }
+    rescue NoMethodError
+      raise ParseError.new("Malformed entries", doc)
+    end
+
+    # def read!
+    # def unread!
+  end
+end