Home Code Other Software

Table of Contents

Introduction

curn is an RSS reader. It scans a configured set of URLs, each one representing an RSS feed, and summarizes the results. By default, curn keeps track of individual items within each RSS feed, using an on-disk cache; when using the cache, it will suppress displaying information for items it has already processed (though that behavior can be disabled).

Unlike many RSS readers, curn does not use a graphical user interface. It is a command-line utility, intended to be run periodically in the background by a command scheduler such as cron(8) (on Unix-like systems) or the Windows Scheduler Service (on Windows).

curn is written entirely in Java and can read RSS feeds from any URL that’s supported by Java’s runtime. When querying HTTP sites, curn uses the HTTP If-Modified-Since and Last-Modified headers to suppress retrieving and processing feeds that haven’t changed. By default, it also requests that the remote HTTP server gzip the XML before sending it. (Some HTTP servers honor the request; some don’t.) These measures both minimize network bandwidth and ensure that curn is as kind as possible to the remote RSS servers.

Extensibility

curn can be extended in a number of ways.

Choice of Output Formats

curn supports several output formats; you can configure one or more output handlers in curn’s configuration file. A sample of curn’s HTML output is here. A sample of curn’s plain text output is here.

curn supports, and uses internally, the FreeMarker template engine; you can easily generate another output format by writing your own FreeMarker template. In addition, you can write your own output handlers, in Java or in any scripting language supported by the javax.script API. See Writing Your Own Output Handler in the curn User’s Guide for more details.

Plug-ins

curn supports custom Java plug-ins that can intercept various phases of curn processing and can enhance or modify curn’s behavior. See Plug-ins in the curn User’s Guide for more details.

Use an RSS Parser of your Choice

curn can be adapted to use any Java RSS parser. By default, it uses the ROME parser, which can handle RSS feeds in Atom format and RSS formats 0.91, 0.92, 1.0 and 2.0. curn can easily be adapted to work with other Java-based RSS parser. Adding an adapter for a new underlying RSS parser technology requires implementing several interfaces and providing concrete implementations for a small number of abstract classes.

Installation

Previous versions of curn could be installed manually or via an IzPack-generated installer. With the 3.0 release of curn, only the graphical installer is supported. That’s because the installer creates a custom front-end shell script (for Unix and Mac OS X) or command script (for Windows) that sets up the proper runtime environment before running curn. Replicating that work manually is enough of a pain that it is no longer officially supported.

IzPack installers support both a graphical installation mode (the default) and a command-line installation mode (by specifying a -console parameter to the invocation).

To install curn:

Once you’ve installed the curn via the graphical installer, you should run it via the curn shell script (for Unix systems) or the curn.bat DOS script (for Windows systems), located in the bin directory where you installed curn.

Using curn

For complete instructions on configuring and using curn, please see the curn User’s Guide.

Building curn from source

Git

The source for the Java Utility Library is in a GitHub repository. The easiest way to obtain it is via Git, which runs on Unix-like operating systems (such as Linux and FreeBSD), Windows, and Mac OS X.

Buildr

The library builds with Apache Buildr, because Buildr’s Ruby-based build files are more powerful and flexible, and much easier to read and maintain, than Maven’s POM files. If you’re building this library from source, you must first download and install Buildr.

Building

First, clone a copy of the Git repository:

git clone git://github.com/bmc/curn.git

Then, change your working directory to the newly-created curn directory, and type:

buildr compile

to compile the code.

To build the IzPack installer, first ensure that you’ve installed IzPack. Then, set environment variable IZPACK_HOME to the directory where you installed IzPack. Then, within the curn source directory, simply type

buildr installer

to generate the IzPack installer jar.

Keeping Up to Date

To be notified automatically of new releases of curn, please join the (low-volume) curn-users mailing list, at http://groups.google.com/group/curn-users/.

To track the curn source code, please see the curn GitHub repository.

Author

Brian M. Clapper, bmc@clapper.org

Acknowledgements

My friend, former co-worker, and (to our mutual surprise) fourth cousin, Steve Sapovits, suggested the name curn.

Portions of curn were developed by, and funded by, ArdenTex, Inc. and donated back to Brian M. Clapper and the curn project.

Portions of curn were developed by ArdenTex, Inc., under contract with Dow Jones & Co.. Dow Jones has graciously donated the source code back to the curn project.

Frequently Asked Questions

Please see the FAQ.

Related Links

Miscellaneous

I use curn myself, every day, to poll a variety of RSS feeds. I develop, test and run curn on Mac OS X, FreeBSD and Ubuntu Linux. have successfully built it on:

Copyright and License

curn is copyright © 2004-2011 Brian M. Clapper and is released under a BSD License.

Patches

I gladly accept patches from their original authors. Feel free to email patches to me or to fork the GitHub repository and send me a pull request. Along with any patch you send: