From: Stoyan Zhekov <stoyan@...>
Date: 2008-01-21T19:05:07+09:00
Subject: [ANN] rss-client-2.0.9

ABOUT
  Fetching and parsing RSS feeds with easy. Ruby library (mixin) for
adding RSS feeds download
  and parsing functionality. The RSS fetch command line utility, using
the library is also included.

DEPENDS
  feed-normalizer for the RSS feeds parsing.

URIs
  Homepage:  http://rubyforge.org/projects/rss-client
  Download:  http://rubyforge.org/frs/?group_id=5309
  SVN:       svn checkout http://rss-client.rubyforge.org/svn/
  Mercurial: hg clone http://hg.assembla.com/rss-client rss-client

  I'm using mostly mercurial, so you can follow the development on:

  http://trac-hg.assembla.com/rss-client/

  Only releases/gems will be posted to rubyforge. Some main milestones/
bug fixes will be commited
  to the rubyforge SVN.

INSTALLATION

Normal Installation
  You can install rss-client with the following command:

  $ ruby install.rb

  from its distribution directory.

GEM Installation
  Download and install rss-client with the following:

  $ gem install --remote rss-client


COMMAND LINE UTILITY USAGE
  $ rssclient [options] feed_url

Options
  -h, --help          Displays help message
  -V, --version       Display the version, then exit
  -q, --quiet         Output as little as possible, overrides verbose
  -v, --verbose       Verbose output
  -p, --proxy         Use proxy (format http://user:pass@address:port
)
  -r, --raw           Use raw RSS fetch (no error code processing)
  -g, --giveup        Giveup on fetching after timeout (seconds)
  -f, --force         Force fresh feed fetch (no 304 code processing)
  -s, --since         Only changes from {since} seconds ago

Examples
  $ rssclient -q http://example.com/atom.xml
  $ rssclient -r -f http://test:test@example.com/atom.xml
  $ rssclient --verbose http://example.com/atom.xml
  $ rssclient --giveup 20 -f http://example.com/atom.xml
  $ rssclient --since 600 http://example.com/atom.xml
  $ rssclient -f -p http://aa:bb@localhost:8088 http://example.com/atom.xml


LIBRARY USAGE IN YOUR OWN RUBY CLASSES
  The main method the library exports is:

  get_feed(url, opts)

  where,

  url - string with the feed url
  opts - OpenStruct with options (see the example below)

  The method returns the output from the FeedNormalizer.parse() on
sucess and nil on failure/not modified.
  The raw feed is saved in @rssc_raw for future processing
  The method handles:
  - successful download (200) - @rssc_raw have the original feed and
the output from the method is the
                                parsed one.
  - not modidied (304) - returns nil and 304 in the @rssc_raw.status
  - redirects (301, 302) - automaticaly redirect to the new url and
trying to fetch the feed again

Example
  require 'rss-client

  class Feed
    include RSSClient

    def fetch
      opts = OpenStruct.new
      opts.forceUpdate = false # set true to force the download (no
304 code handling)
      opts.giveup = 10         # on error giveup after 10 sec timeout

      rss = get_feed('http://rubyforge.org/export/
rss_sfnews.php',opts)
      return nil unless @rssc_raw             # download error
      return 304 if @rssc_raw.status == 304   # feed not modified
      return nil unless rss                   # error in parsing

      # some title, items etc. processing
      self.title = rss.channel.title.to_s
      self.description = rss.channel.description.to_s
      rss.entries.each do |i|
        ...
      end
    end

  end

  get_feed() using get_url(url, opts) method, which in turn is powered
by HTTPAccess2::Client.
  get_url() can be used for low-level connection debugging (the -r
option in the command line
  utility). get_url() example output for http://rubyforge.org/export/rss_sfnews.php:

  $ rssclient -r http://rubyforge.org/export/rss_sfnews.php
  Status code: 200
  Headers:
  - Status: 200 OK
  - Date: Mon, 21 Jan 2008 09:37:00 GMT
  - Server: Apache
  - X-Powered-By: PHP/4.4.8
  - Vary: Accept-Encoding
  - Connection: close
  - Transfer-Encoding: chunked
  - Content-Type: text/plain
  - Content-Length: 0
  - Content-Type: text/html; charset=us-ascii


CREDITS
  Hiroshi Nakamura - For the http-access2 library.
  Todd Werth - For the ruby command-line application skeleton

LICENSE
  rss-client is available under an MIT-style license.


And one question/problem: when installed with 'ruby install.rb' the '-
h' option properly displaying
the help/usage. When installed via gems, '-h' returns:

  rssclient version 2.0.9
  This file was generated by RubyGems.

  The application 'rss-client' is installed as part of a gem, and this
  file is here to facilitate running it.