curn: Customizable Utilitarian RSS Notifier
User's Guide

Brian M. Clapper
bmc @ clapper . org
$Id$

Table of Contents

• Introduction
• Terminology
• curn Command Line Syntax
  • Command Line Options
  • Command Line Parameters
• The curn Configuration File
  • Configuration File Syntax
    • Section Name Syntax
    • Variable Name Syntax
    • Continuation Lines
    • Expansions of Variable Values
      • Metacharacter Expansion
      • Variable Substitution
      • Suppressing Metacharacter Expansion and Variable Substitution
    • Path Names
    • Includes
    • Comments and Blank Lines
  • Overview of curn's Configuration File
  • The [curn] Section
  • Configuring the RSS Feeds
  • Configuring Output Handlers
    • Output Handler Sections
    • Predefined Output Handlers
      • FreeMarkerOutputHandler
      • HTMLOutputHandler
      • TextOutputHandler
      • SimpleSummaryOutputHandler
      • ScriptOutputHandler
    • Examples
• Having curn Run on a Schedule
  • Running curn from cron(8) on UNIX-like Systems
  • Running curn via the Windows Scheduler
• Being "Bandwidth Friendly"
  • Don't Run curn Too Often
  • Consolidate Common Feeds
• Extending curn
  • Using an Unsupported RSS Parser
  • Plug-ins
    • Overview of Plug-In Support
    • Stock Plug-ins
    • Installing New Plug-ins
    • Writing curn Plug-ins
      • The curn Plug-in API
      • Plug-in Execution Order
      • Registering the Plug-in with curn
      • A Simple Example Plug-in
      • Persisting Data from a Plug-in
  • Customizing curn's Output
    • Writing Your Own FreeMarker Template
    • Writing Your Own Output Handler
      • Writing a Java Output Handler
      • Writing a Script Output Handler
        • Supported Scripting Languages
        • Supporting Additional Scripting Languages
        • Writing the Script
        • Configuring the Script Output Handler
  • Installing Supporting Software
• Troubleshooting
  • Logging
    • java.util.logging
    • Log4J
• Appendix A: Similar Products and Tools
• Appendix B: Copyrights
• End Notes

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 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 (though a Force Feed Download Plug In, such as the Retain Articles, can override that capability). 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. (There are some additional steps you can take to be more bandwidth-friendly.)

curn supports a several output formats; you can configure one or more output handlers in curn's configuration file. In addition, someone conversant with Java programming or comfortable with a scripting language, such as Python or Ruby, can easily extend curn to handle a new output format. See the section entitled Writing Your Own Output Handler for more details. Finally, as of version 2.6, curn has a built-in template-driven output handler, based on the FreeMarker template engine; The FreeMarkerOutputHandler this handler uses a text template to generate output, so anyone conversant with FreeMarker can easily write his own template to generate custom output. See the section describing the FreeMarkerOutputHandler for more details.

curn's predefined output handlers can generate:

• plain text output, suitable for emailing to people who can't handle HTML email
• a plain text summary of the number of new items in each feed
• rich rich HTML output, with hyperlinks to the actual items on the web.

In addition, curn supports emailing its output. If email addresses are specified in the configuration file, then curn creates a MIME multipart/alternative email message [1], using the output of each output handler as one of the alternative attachments. (As of version 3.2, curn can also send individual email messages for each article; see the MailIndividualArticles parameter.)

Terminology

Throughout this document, the following terms are used:

• curn_home is the curn installation directory.
• user_home is the home directory of the user who's running curn.(On Windows, the curn.bat front-end command script uses the value of the %HOME% variable to override the Java VM's notion of the user's home directory, if %HOME% is set.)

curn Command Line Syntax

curn is invoked from the command line as follows:

curn

The curn graphical installer automatically creates a Unix shell script (called curn) or a Windows command file (curn.bat) in the bin directory beneath the curn installation directory. You must put the curn bin directory in your path.

curn's command line uses a UNIX-like syntax. If you invoke curn without any parameters, you get the following usage display.

Many of curn's command-line options simply override settings in the curn configuration file. Each option and argument is discussed in more detail, below.

Command Line Options

Command Line Parameters

A list of curn's positional parameters follows.

The curn Configuration File

curn's configuration file controls all aspects of curn's behavior. The configuration file contains parameters that control curn's behavior, the output handlers, and the individual RSS feed sites. This section first describes the overall configuration file syntax, and then describes each curn configuration item in detail.

You can view a sample curn configuration file by following this link.

Configuration File Syntax

curn's configuration file is a simple text file. It resembles a standard Java properties file, but it is broken into individual sections, each of which has its own variable namespace. At a glance, the configuration file is reminiscent of a Windows .INI file, but there are quite a few differences. [2].

Like a .INI file, each section in the configuration file consists of a name surrounded by brackets. Each section contains variable assignments; the variable assignment syntax is similar to that of a Java properties file. For example:

Section Name Syntax

There can be any amount of whitespace before and after the brackets in a section name; the whitespace is ignored. That is. "[curn]", "[ curn]" and "[ curn ]" all specify a section named "curn".

Variable Name Syntax

Each section contains zero or more variable settings. Similar to a Java properties file, the variables are specified as name/value pairs, separated by an equals sign ("=") or a colon (":"). Variable names are case-sensitive and may contain any printable character (including white space), other than '$' '{', and '}'. Variable values may contain anything at all. The parser ignores whitespace on either side of the "=" or ":"; that is, leading whitespace in the value is skipped. The way to include leading whitespace in a value is escape the whitespace characters with backslashes. (See below).

Variable definitions may span multiple lines; each line to be continued must end with a backslash ("\") character, which escapes the meaning of the newline, causing it to be treated like a space character. The following line is treated as a logical continuation of the first line; however, any leading whitespace is removed from continued lines. For example, the following four variable assignments all have the same value:

Because leading whitespace is skipped, all four variables have the value "one two three".

Only variable definition lines may be continued. Section header lines, comment lines (see below) and include directives (see below) cannot span multiple lines.

Expansions of Variable Values

The configuration parser preprocesses each variable's value, expanding embedded metacharacter sequences and substituting variable references. (See below.) You can use backslashes to escape the special characters that the parser uses to recognize metacharacter and variable sequences; you can also use single quotes. See Suppressing Metacharacter Expansion and Variable Substitution, below, for more details.

Metacharacter Expansion

Within a variable's value, Java-style ASCII escape sequences \t, \n, \r, \\, \", \', \  (a backslash and a space), and \uxxxx are recognized and converted to single characters. Note that metacharacter expansion is performed before variable substitution.

Variable Substitution

A variable's value can interpolate the values of other variables, using a variable substitution syntax reminiscent of the Unix shell (The syntax is also similar to the ant variable substitution syntax). The general form of a variable reference is ${sectionName:varName}. sectionName is the name of the section containing the variable to substitute; if omitted, it defaults to the current section. varName is the name of the variable to substitute. If the variable has an empty value, an empty string is substituted. If the variable (or the referenced section) does not exist, the curn will abort. If a variable reference specifies a section name, the referenced section must precede the current section. It is not possible to substitute the value of a variable in a section that occurs later in the file.

The section names "system", "env", and "program" are reserved for special "pseudosections."

The "system" pseudosection is used to interpolate values from Java's System.properties class. For instance, ${system:user.home} substitutes the value of the user.home system property (typically, the home directory of the user running curn). Similarly, ${system:user.name} substitutes the user's name.

The "env" pseudosection is used to interpolate values from the environment. On UNIX systems, for instance, ${env:HOME} substitutes user's home directory (and is, therefore, a synonym for ${system:user.home}. On some versions of Windows, ${env:USERNAME} will substitute the name of the user running curn. Note: On UNIX systems, environment variable names are typically case-sensitive; for instance, ${env:USER} and ${env:user} refer to different environment variables. On Windows systems, environment variable names are typically case-insensitive; ${env:USERNAME} and ${env:username} are equivalent.

The "program" pseudosection is a placeholder for various special variables provided by the Configuration class at runtime. Those variables are:

For example:

[curn]
myCurnDir = ${system:user.home}/.curn

[Feed_Wired]
URL: http://www.wired.com/news_drop/netcenter/netcenter.rdf
SaveAs: ${curn:myCurnDir}/feeds/wired.rdf

[curn]
myCurnDir = ${system:user.home}/.curn
CacheFile = ${myCurnDir}/cache

The configuration file also supports a simple conditional-substitution logic, which allows you to specify a default value to be substituted if a variable is empty or does not have a value. The general form of a conditional substitution is:

${var?some default value}

Suppressing Metacharacter Expansion and Variable Substitution

To prevent the parser from interpreting metacharacter sequences, variable substitutions and other special characters, enclose part or all of the value in single quotes. (See [3] for additional comments.) For example, suppose you want to set variable "prompt" to the literal value "Enter value. To specify a newline, use \n." The following configuration file line will do the trick:

prompt: 'Enter value. To specify a newline, use \n'

Similarly, to set variable "abc" to the literal string "${foo}" suppressing the parser's attempts to expand "${foo}" as a variable reference, you could use:

abc: '${foo}'

To include a literal single quote, you must escape it with a backslash.

Path Names

Regardless of the underlying operating system, path names in the curn configuration file can always use Unix-style forward slash ("/") characters. At runtime curn will convert the path names to use the appropriate file separator (e.g., "\" on Windows). This capability provides two benefits:

1. It enhances the portability of curn configuration files.
2. It provides a means to avoid using (and, therefore, having to escape) backslash characters in the configuration file.

Includes

A special include directive permits inline inclusion of another configuration file. The include directive takes two forms:

%include "path"
%include "URL"

For example:

%include "/home/bmc/mytools/common.cfg"
%include "file:///home/bmc/mytools/common.cfg"

The included file may contain any content that is valid for this parser. It may contain just variable definitions (i.e., the contents of a section, without the section header), or it may contain a complete configuration file, with individual sections. Since the parser recognizes a variable syntax that is essentially identical to Java's properties file syntax, it's also legal to include a properties file, provided it's included within a valid section.

Attempting to include a file from itself, either directly or indirectly, will cause curn to abort processing.

Comments and Blank Lines

A comment line is a one whose first non-whitespace character is a "#" or a "!". This comment syntax is identical to the one supported by a Java properties file. A blank line is a line containing no content, or one containing only whitespace. Blank lines and comments are ignored. For example:

Overview of curn's Configuration File

curn's configuration file has three kinds of sections:

• The main section, named "curn", contains global parameters. Some of these parameters can be overridden on the command-line. Others can be overridden on a per-feed basis.
• Output handler sections, each specifying an output handler that will process parsed feed data and (presumably) produce output. There can be any number of these sections.
• Feed sections, each specifying a single RSS feed to be downloaded, parsed and processed.

All other sections in the configuration file are parsed (and subject to syntactic constraints), but otherwise ignored. Thus, it's perfectly legal to have a separate section, e.g., "[var]", where you define variables that exist solely to be substituted into other sections.

Any boolean parameter (i.e., one documented as taking a true or false value) can also take a value of "0" (false), "1" (true), "no" (false) or "yes" (true).

The [curn] Section

This section contains variable global parameters. Each is described in detail, below. (Parameters marked with plug-in are handled by one of curn's stock plug-ins, rather than by the core code.)

Configuring the RSS Feeds

The curn configuration file also contains a list of RSS feeds to be polled. Each feed must be specified in its own section in the configuration file. The name of the section must start with the string "Feed". If more than one feed is present, then each section name must also have additional characters, to make the section name unique. The following section names are all valid for RSS feed sections.

• Feed (if there's only one configured feed)
• Feed1
• Feed_0
• Feed_Wired
• Feed.NYTimes.Top

Each feed section supports the following parameters. (Parameters marked with plug-in are handled by one of curn's stock plug-ins, rather than by the core code.)

Configuring Output Handlers

Output Handler Sections

As curn processes each RSS feed, it parses the XML and loads the new items into internal data structures. When it has finished processing the XML, it hands the parsed data structures to one or more output handlers. Output handlers are so called because they generally produce output that's to be displayed or emailed to the user—generally, but not always. An output handler may choose to save its output to a file, but not send the output back to curn; each of the built-in output handlers does exactly that if its SaveAs configuration parameter is set and its SaveOnly configuration parameters is true. Alternatively, the output handler may choose to convert the internal data structures to output that it publishes somewhere (e.g., via a network connection to an HTTP server).

Each output handler is specified in its own section in the configuration file. The name of the section must start with the string "OutputHandler". If more than one output handler is present, then each section name must also have additional characters, to make the section name unique. The following section names are all valid for output handler sections.

• OutputHandler (if there's only one output handler)
• OutputHandlerHTML
• OutputHandlerText
• OutputHandler1
• OutputHandler_asdf

If no OutputHandler sections are present in the configuration file, curn skips the RSS XML parsing phase. (There's not reason to parse the XML if there are no output handlers to process the parsed feed data.) If there are no output handlers, curn may or may not download individual feeds. If a given feed has no SaveAs setting, and there are no output handlers, then curn skips the feed entirely. After all, there's no sense wasting time downloading the feed, if the feed isn't being parsed or saved. However, if the feed does have a SaveAs setting, curn will download and save the XML (assuming it has changed) even if XML parsing is disabled.

All output handler sections take two variables. In addition, individual output handlers can require configuration items of their own. The two variables common to all output handlers are described below.

There are some output handler examples following the next section.

Predefined Output Handlers

curn comes bundled with the following built-in output handlers.

FreeMarkerOutputHandler

Class

org.clapper.curn.output.freemarker.FreeMarkerOutputHandler

Purpose

Uses the FreeMarker template engine and a configured template to generate output.

Using the FreeMarker output handler

The FreeMarkerOutputHandler, introduced in curn version 2.6, is both simple and flexible. It uses the FreeMarker template engine to convert a template to an output file. FreeMarker templates can be used to generate nearly any kind of textual output file, from HTML and XML to simple text. In fact, the HTMLOutputHandler, TextOutputHandler, and SimpleSummaryOutputHandler have been reimplemented to use the FreeMarkerOutputHandler in conjunction with built-in templates that produce the appropriate kind of output.

You can also write your own FreeMarker template, to change the output format. See the subsection entitled Writing Your Own FreeMarker template, in the Extending curn section, below.

HTMLOutputHandler

Class

org.clapper.curn.output.html.HTMLOutputHandler

Purpose

Produces an HTML description of the new RSS items. You can find a sample of its output here.

Note

Prior to version 2.6, this output handler used custom code and the XMLC library to generate its HTML output. However, that approach made it difficult to customize the HTML output for individual sites. As of curn, version 2.6, the HTMLOutputHandler is implemented in terms of the FreeMarkerOutputHandler. The HTMLOutputHandler class uses the FreeMarkerOutputHandler's built-in HTML template, so the output from the HTMLOutputHandler class is identical to the output from the FreeMarkerOutputHandler class when the "builtin html" template is used. You can continue to use the HTMLOutputHandler class, but it is no longer maintained. Plus, the FreeMarkerOutputHandler class is more flexible.

TextOutputHandler

Class

org.clapper.curn.output.TextOutputHandler

Purpose

Produces a plain text description of the new RSS items. You can find a sample of its output here.

Note

As of curn, version 2.6, this output handler is implemented in terms of the FreeMarkerOutputHandler. It forces use of the FreeMarkerOutputHandler's built-in "text" template. You can continue to use the TextOutputHandler class, but it is no longer maintained. Plus, the FreeMarkerOutputHandler class is more flexible.

SimpleSummaryOutputHandler

Class

org.clapper.curn.output.SimpleSummaryOutputHandler

Purpose

Produces a plain text summary of the new RSS items. For each RSS feed that has new items, this output handler shows the feed's name, its URL, and the number of new items. It does not show the items themselves. You can find a sample of its output here.

Note

As of curn, version 2.6, this output handler is implemented in terms of the FreeMarkerOutputHandler. It forces use of the FreeMarkerOutputHandler's built-in "summary" template. You can continue to use the SimpleSummaryOutputHandler class, but it is no longer maintained. Plus, the FreeMarkerOutputHandler class is more flexible.

ScriptOutputHandler

Class

org.clapper.curn.script.ScriptOutputHandler

Purpose

Provides an output handler calls a script via the Apache Jakarta Bean Scripting Framework (BSF) or the Java 6 (JSR 223) javax.script scripting framework. (The Java 6 scripting framework is only available if you're running curn via Java 6.) By default, the ScriptOutputHandler first tries to use the javax.script infrastructure; if that doesn't work, it tries to the BSF infrastructure. This handler supports any scripting language supported by the underlying scripting infrastructure. For complete details on writing a script output handler, See Writing a Script Output Handler, below.

Examples

Example 1: The output handler sections from a curn configuration file that produces HTML output. If curn is called with email addresses, the HTML output will be mailed to the specified email addresses. The HTML output is not saved anywhere.

Example 2: The output handler sections from a curn configuration file that produces HTML output and plain text output. If curn is called with email addresses, the text output and the HTML output will be mailed to the specified email addresses as "multipart/alternative" attachments. The output is not saved anywhere.

Example 3: The output handler sections from a curn configuration file that produces HTML output to a file (but not to the user), and displays (or emails) the user a text summary that contains a link to the HTML file.

Example 4: The feed and output handler sections from a curn configuration file that retrieves and downloads XML feeds, caching them in a known location, without displaying them. (See Being Bandwidth Friendly for reasons why you might want to do this.)

Having curn Run on a Schedule

You can run curn manually, at the command line, whenever you feel like checking your news feeds. However, this is less than useful. The best way to run curn to have your computer's background scheduler process (e.g., cron(8) on UNIX-like systems, or the Windows Scheduler on Windows) run curn for you automatically, every so often.

Running curn from cron(8) on UNIX-like Systems

I typically run curn three times a day, via cron, on weekdays and once on weekends, and I have it mail me the output. I use my personal crontab, rather than the system-wide /etc/crontab file. Here's a sample crontab entry that does this:

Running curn via the Windows Scheduler

Currently, this task is left as an exercise to the reader. (I don't use Windows often enough to play with the scheduler, so I haven't gotten around to running curn that way. When I do find the time and inclination to experiment with running curn from the Windows Scheduler, I'll update this section. Unless, of course, someone else wants to supply the relevant details...)

Being "Bandwidth Friendly"

When pulling down RSS documents from remote HTTP servers, curn does its best to minimize the amount of bandwidth it consumes. By default, it uses the following strategies to do so (though most can be overridden by configuration parameters and command-line parameters).

• Uses the cache to determine how to set the HTTP If-Modified-Since header, instructing the remote HTTP server to send the RSS document only if it has changed since the last time curn retrieved it. (The HTTP server isn't required to honor that header.)
• Requests that the remote HTTP server compress the RSS data in transit, by setting the HTTP Accept-Encoding header to gzip. Again, the HTTP server isn't required to honor that header; some do, some don't.

But there are other things you can do to be polite to remote HTTP servers.

Don't Run curn Too Often

I run curn three times a day. In practice, that's more than sufficient to keep up with the daily news feeds I want to read. Your needs may vary, but if you're using curn to poll remote RSS feeds every five minutes, you probably fall into the "impolite RSS feed user" category.

Consolidate Common Feeds

Suppose you have a number of users, all of whom run curn several times a day. Further suppose that there's significant commonality in the RSS feeds that they want to read. Rather than have each user poll the common remote HTTP servers individually, you could run a single instance of curn that downloads and saves those feeds several times a day. You could then instruct the individual users to point their curn configuration files at the local copies of the RSS feeds, instead of the remote ones.

For instance, suppose the following URLs (for a fictitious RSS aggregator service) are commonly downloaded by people on your local network:

http://www.example.org/rss/nytimes_front_page.xml
http://www.example.org/rss/bbc_world_news.rdf
http://www.example.org/rss/big_jimmys_blog.xml

You could run curn periodically with the following configuration file, to download each of those feeds without producing any output.

Note that you could use curn in this manner even if your users are not using curn to read their RSS feeds. You could still run your periodic instance of curn to download the common feeds to a directory that's part of an internal web site, and instruct your users to point whatever RSS readers they're using to those internal web pages, instead of the external ones.

Extending curn

This section is intended for Java programmers who want to extend curn's capabilities by writing additional output handlers, integrating a different RSS parser, or even writing a new command-line or GUI front-end to curn's main logic.

Roughly speaking, curn's processing is divided into the following phases:

1. startup: Initialization
2. configuration: Read the configuration file (which includes the set of RSS feeds, the output handlers to use, the RSS parser to use, various cache-control values, and other things), load the on-disk cache into memory, and initialize various data structures.
3. feed download: Download the configured RSS feeds, assuming they have changed.
4. feed parsing: Parse the downloaded RSS feeds, assuming (a) a parser class and at least one output handler have been configured. (If there's no parser, or no output handlers, then curn is running in download-only mode, and there's no need to waste time parsing the XML.)
5. output: Pass the parsed feed data to the configured output handlers
6. shutdown: Cleanup.

Since curn permits you to specify the parsing and output handler classes in its configuration file, you can easily extend curn's capabilities by writing your output handler or integrating a different RSS parser. In addition, as of version 3.0, curn supports general-purpose plug-ins that can intercept various phases of curn processing.

Using an Unsupported RSS Parser

Suppose you've found (or written) an RSS parser that you prefer to use instead of ROME. (Perhaps it's faster than one of those, or perhaps it supports some new RSS syntax that ROME does not support. Or, perhaps you're just playing around.) Integrating that parser with curn requires writing some adapter classes that implement some interfaces and extend some classes provided with the curn software. Those classes are:

Typically, integrating a new parser means writing a set of adapter classes that implement the above interfaces or extend the above classes, and map the necessary calls onto methods in the real underlying parser. For a sample integration, see the classes in the curn source code package org.clapper.curn.parser.rome. Those classes implement a simple adapter for the third-party ROME RSS parser.

Note: If you've written an adapter for an unsupported RSS parser engine, you'll have to make your adapter classes and the RSS parser classes available to curn. It's not sufficient to add the appropriate jar files to your CLASSPATH environment variable. Please refer to the section entitled Installing Supporting Software for details.

Plug-ins

As of version 3.0, curn supports plug-ins. curn plug-ins can intercept various phases of curn processing and can enhance or modify curn's behavior. This section discusses curn's plug-in support.

Overview of Plug-In Support

If invoked properly (e.g., via the curn shell script or the curn.bat DOS script created by the curn installer), curn will search for and load plug-ins before it begins doing its real work. curn looks for plug-ins in the following directories:

• curn_home/plugins
• user_home/curn/plugins
• user_home/.curn/plugins

curn searches all jar files, zip files, and subdirectories in each of those directories, looking for any non-abstract, public class that implements one or more of the curn Java plug-in interfaces. curn then attempts to load and instantiate each plug-in. Once a plug-in has been instantiated, its capabilities are available. Most plug-ins are dormant; that is, they don't do anything unless activated by a plug-in-specific configuration entry.

After curn loads all the plug-ins it can find, it sorts them by "sort key" (a special field that each plug-in is required to provide), case-blind comparison. All plug-ins within a given execution phase are, therefore, invoked in alphabetical order by sort key. This bit of processing trivia is useful if you need to ensure that one plug-in fires before another plug-in.

Stock Plug-ins

curn ships with a set of stock plug-ins. Some of those plug-ins implement capabilities that were formerly in the curn core code; others provide new functionality. These plug-ins are automatically available (provided you don't delete the curn-plugins.jar file that's shipped with curn). The following table summarizes the stock plug-ins. All stock plug-ins are in the org.clapper.curn.plugins package.

Installing Plug-ins

Installing a custom plug-in (i.e., not one of curn's stock plug-ins) is simple: Copy the plug-in's jar or zip file to one of the directories listed in the Overview of Plug-In Support section.

Writing curn Plug-ins

curn Plug-in API

curn automatically invokes plug-ins at various phases of its execution. A plug-in that is registered for a particular phase will be called during that phase of processing. A given plug-in class can be associated with multiple phases of execution. In fact, most are, if only to permit them to intercept their plug-in-specific configuration parameters.

Each plug-in phase is represented by its own Java interface, and each interface has exactly one method. Each plug-in interface, in turn, extends the curn parent PlugIn interface, which defines some additional methods that all plug-ins must provide.

A plug-in that intercepts multiple curn processing phases must implement the interfaces for each of the phases. Here are the plug-in phases, with their associated interfaces and methods, in execution order.

Plug-in Execution Order

All plug-ins within a given phase are run in a particular order. The internal curn plug-in manager sorts the plug-ins for each phase according to the value of each plug-in's sort key. Each plug-in must implement a getPlugInSortKey() method returning a string to be used when sorting that plug-in. For all curn stock plug-ins, that sort key is the plug-in's short class name (i.e., the class name without its package name). This is important only if one plug-in within a phase depends on another plug-in within the phase having run first. For instance, the Save As RSS plug-in runs during the post feed-parse phase, operating on the internal parsed feed data. It runs after the Ignore Duplicate Articles plug-in, because the Ignore Duplicate Articles plug-in's short class name (IgnoreDuplicateArticlesPlugIn) sorts before the Save As RSS plug-in's short class name (SaveAsRSSPlugIn). (This example assumes that both plug-ins are enabled, via their respective configuration parameters.) If the Save As RSS plug-in's short class name were something like CurnSaveAsRSSPlugIn, it would run before the Ignore Duplicate Articles plug-in, and the saved RSS file might have duplicate articles in it. Again, if you're writing your own plug-in, you care about this operational detail only if your plug-in depends on the other plug-ins within the same phase.

Registering the Plug-in with curn

A plug-in class doesn't have to do anything special to register itself with curn. Merely implementing the appropriate interfaces is sufficient, as long as curn can find the plug-in class at run-time.

A Simple Example Plug-in

Of course, there's nothing quite like an example to clarify things. So, here's a simple plug-in that:

• defines a ZipOutputTo configuration parameter, in the [curn] section, that specifies the path to a zip file
• takes all output files written by the output handlers and zips them up into the specified zip file

It uses a convenience class, org.clapper.util.io.Zipper, to simplify the chore of writing the zip file. Here's the source (with comments stripped out). Note that this is a stripped-down version of the actual ZipOutputPlugIn.

To activate this plug-in, simply ensure that it is available to curn at startup, and add this configuration directive to the [curn] section of the configuration file:

For more examples, please see the source code for the stock plug-ins delivered with curn.

Persisting Data from a Plug-in

Beginning with curn 3.1, plug-ins (and output handlers, for that matter) can save runtime metadata to the curn metadata store (formerly called the "cache") and restore that data in a subsequent curn run. To be able to save and restore metadata, a plug-in must:

• extend the org.clapper.curn.PersistentDataClient interface or extend the org.clapper.curn.AbstractPersistentDataClient class
• register itself as a persistent data handler by calling org.clapper.curn.DataPersister class's addPersistentDataClient() method, typically from the plug-in's initPlugIn() method

Once the plug-in is registered as a persistent data client, curn will:

• Ask the plug-in for its name/value pairs to be saved, just before curn exits
• Present the plug-in with name/value pairs to be parsed, just after curn starts up and reads the metadata (cache) file.

The following code fragment shows how a plug-in might register itself.

import org.clapper.curn.DataPersister;
import org.clapper.curn.DataPersisterFactory;
import org.clapper.curn.AbstractPersistentDataClient;

...

public class MyPlugIn extends AbstractPersistentDataClient, ...
{
    ...
    public void initPlugIn() throws CurnException
    {
        DataPersister dataPersister = DataPersisterFactory.getInstance();
        dataPersister.addPersistentDataClient(this);
    }
    ...
}

Customizing curn's Output

Writing Your Own FreeMarker Template

Because FreeMarker relies on external templates to create the final document, and because curn makes it easy to use custom-crafted templates, you easily create your own custom documents, or your own branded HTML output, without having to write your own output handler. To create your own curn FreeMarker template, you must understand two things:

• How to create a FreeMarker template
• curn's specific FreeMarker data model

A tutorial on FreeMarker is beyond the scope of this document. The remainder of this section assumes you have some familiarity with FreeMarker. If you don't know how FreeMarker works, please consult the on-line FreeMarker documentation before reading this section.

A FreeMarker template relies on the presence of a tree of data, supplied by the program. FreeMarker calls this data tree a "data model". The FreeMarkerOutputHandler creates a curn-specific FreeMarker data model for use within a template. The FreeMarkerOutputHandler is as much as data-mapper as an output handler: It maps curn's internal RSS data structures into a FreeMarker data model, then invokes the FreeMarker template engine to transform the template and data-model into a document.

The curn FreeMarker data model is described below. The data model notation used here is similar to the notation used within the FreeMarker documentation.

Tree                                         Description

(root)
 |
 +-- curn
 |    |
 |    +-- showToolInfo ....................... [boolean] whether or not
 |    |                                        to display curn information
 |    |                                        in the output
 |    |
 |    +-- version ............................ [String] version of curn
 |    |
 |    +-- buildID ............................ [String] curn's build ID
 |
 +-- totalItems .............................. [int] total items for all channels
 |
 +-- dateGenerated ........................... [Date] date generated
 |
 +-- extraText ............................... [String] extra text, from the config
 |
 +-- encoding ................................ [String] encoding, from the config
 |
 +-- tableOfContents ......................... hash of table-of-contents data
 |    |
 |    +-- needed ............................. [boolean] whether a table of contents is needed
 |    |
 |    +-- (channels) ......................... sequence of channel table of contents items
 |          |
 |          +-- channel ...................... table of contents entry for one channel
 |          |     |
 |          |     +-- title .................. [String] channel title
 |          |     |
 |          |     +-- totalItems ............. [int] total items in channel
 |          |     |
 |          |     +-- channelAnchor .......... [String] HTML anchor name for channel
 |          |
 |          +-- channel
 ...        ...
 |
 +-- (channels) .............................. sequence of channel (feed) data
 |      |
 |      +-- channel .......................... hash for a single channel (feed)
 |      |       |
 |      |       +-- index .................... [int] channel's index in list
 |      |       |
 |      |       +-- totalItems ............... [int] total items in channel
 |      |       |
 |      |       +-- title .................... [String] channel title
 |      |       |
 |      |       +-- description .............. [String] channel description, or "" if not available
 |      |       |
 |      |       +-- anchorName ............... [String] HTML anchor name for channel
 |      |       |
 |      |       +-- url ...................... [String] channel's URL (as published in the feed's XML)
 |      |       |
 |      |       +-- configuredURL ............ [String] channel/feed URL (as listed in the curn configuration file)
 |      |       |
 |      |       +-- id ....................... [String] channel's unique ID (which might just be the URL)
 |      |       |
 |      |       +-- date ..................... [Date] channel's last-modified date (might be missing)
 |      |       |
 |      |       +-- rssFormat ................ [String] RSS format of channel (Atom, RSS 0.92, etc.).
 |      |       |                              Empty if not to be shown.
 |      |       |
 |      |       +-- author .......             [String] the author or authors of the item, combined in a single string, or ""
 |      |       |
 |      |       +-- (authors) ................ sequence of (String) names of authors of the feed
 |      |       |
 |      |       +-- (items) .................. sequence of channel items
 |      |             |
 |      |             +-- item ............... entry for one item
 |      |             |     |
 |      |             |     +-- index ........ [int] item's index in channel
 |      |             |     |
 |      |             |     +-- title ........ [String] item's title
 |      |             |     |
 |      |             |     +-- url .......... [String] item's URL (as published in the feed's XML)
 |      |             |     |
 |      |             |     +-- date ......... [Date] the date (might be missing)
 |      |             |     |
 |      |             |     +-- author ....... [String] the author or authors of the item, combined in a single string, or ""
 |      |             |     |
 |      |             |     +-- authors ...... a sequence of individual (String) author names. Might be empty.
 |      |             |     |
 |      |             |     +-- description .. [String] description/summary
 |      |             |
 |      |             +-- item
 |      |             |
...    ...           ...
 |      |
 |      +-- channel
 |      |
...    ...

The FreeMarkerOutputHandler also places three FreeMarker methods in the data model, as well:

Below is a sample template, which is largely identical to the built-in text template. This template illustrates the use of the data model. You can a version of the text template, as well as the HTML template and the simple summary template, by following these links:

• HTML
• Text
• Simple Summary

${title}
<#if extraText != "">
${wrapText (extraText)}
</#if>

<#list channels as channel>
---------------------------------------------------------------------------
${wrapText (channel.title, 0)}
${channel.url}
<#if channel.date?exists>
${channel.date?string("E, dd MMM, yyyy 'at' HH:mm:ss")}
</#if>

<#list channel.items as item>
${wrapText (item.title, 4)}
${indentText (item.url, 4)}
<#assign desc = stripHTML(item.description)>
<#if desc != "">

${wrapText (desc, 8)}
</#if>

</#list>
</#list>

---------------------------------------------------------------------------
<#if (curn.showToolInfo)>
curn, ${curn.version}
Generated ${dateGenerated?string("EEEEEE, dd MMMM, yyyy 'at' HH:mm:ss zzz")}
</#if>

Writing Your Own Output Handler

There are two ways to write your own output handler: You can write a Java class that implements the output handler, or you can write a script using a scripting language supported by the Apache Jakarta Bean Scripting Framework (BSF). Both approaches are discussed below.

But—before you write your own output handler, consider whether you can accomplish the same ends by writing a FreeMarker template and using the FreeMarkerOutputHandler. If you're planning to create a different output file format (as opposed to writing an output handler to send data over a network connection or to a database), then there's a good chance that writing a FreeMarker template will be simpler and faster.

Writing a Java Output Handler

Writing a new output handler is reasonably straightforward:

• First, write a Java class the implements the org.clapper.curn.OutputHandler interface.
• Compile the class, place it in a jar file, and put the jar file someplace where curn can find it. (See the section entitled Installing Supporting Software for details on where to place the jar file.)
• Specify your new output handler in your curn configuration file.

To illustrate the concept, let's look at an output handler that simply writes each channel and its items as plain text. (As it turns out, this example is a stripped down version of the existing org.clapper.curn.output.TextOutputHandler class. The real source code has more comments and documentation and also implements a common base class.)

First, let's look at the top of the class and the required init() method:

curn calls the init() method right after instantiating the output handler class. One of the init() method's primary responsibilities is to handle any special handler-specific configuration variables. It does so by:

1. asking the ConfiguredOutputHandler object for the section name that's associated with the output handler class
2. requesting the specific configuration variable values from that section
3. processing the results, if any

The init() method also performs any other initialization required by the output handler class.

Note: The sample init() method, above, does a little more work than it needs to do. As it turns out, the curn API provides a useful abstract base class called org.clapper.curn.output.FileOutputHandler that implements the OutputHandler interface. FileOutputHandler provides an init() method that:

• automatically handles the "SaveAs" and "SaveOnly" configuration parameters
• handles creation of the output file, much the same way the sample init() method, above, does
• provides some useful protected methods for the subclass, such as getOutputFile() (which returns the file to which the subclass should write its output).

FileOutputHandler requires that the subclass provide:

• an initOutputHandler() method, to handle subclass initialization. This method takes the same parameters as the init() method.
• the output methods (e.g., displayChannel()), discussed below

With that in mind, let's simplify our original init() method and class definition. Changes from the original, above, are marked in bold.

Next, let's look at the output-related methods. There are several output-related methods that are required by the OutputHandler interface:

• displayChannel(): Displays the output for a parsed channel. This method takes the parsed RSSChannel object and a special org.clapper.curn.FeedInfo object that contains the configuration information about the feed (i.e., its URL, its title, etc.).
• flush(): Flushes the output and closes the output files
• getContentType() returns the MIME type associated with the generated output.
• hasGeneratedOutput(): returns true if the handler generated output that the user should see, false otherwise. In this handler's case, hasGeneratedOutput() is provided by the parent FileOutputHandler class; it returns true if the output file has a non-zero length and the SaveOnly configuration parameter has not been set. (Recall that "SaveOnly" says that the generated output should only be saved, not displayed.)
• getGeneratedOutput(): Returns an InputStream for reading the generated output (if hasGeneratedOutput() returns true) or null otherwise. Again, we don't have to implement that method in our sample output handler, because the parent FileOutputHandler provides it for us.

Here's the code for the methods our sample class must implement:

This particular output handler's displayChannel() method summarizes the channel and item data, writing it to the output file that the init() method opened. The flush() method simply finishes the display.

With this model, it's possible to create output handlers that produce all kinds of output, including (for instance):

• HTML
• XML (e.g., for converting all incoming RSS feeds to one type of RSS feed)
• data sent over a network connection
• etc.

Writing a Script Output Handler

Writing a script output handler is even simpler, in a way, than writing a Java output handler. You simply write a script in a supported language, then configure an instance of the ScriptOutputHandler class to point to your script.

Supported Scripting Languages

The ScriptOutputHandler uses the Apache Jakarta Bean Scripting Framework (BSF) or the JSR 223 scripting engine to call scripts. It currently supports any scripting language that has a binding to either scripting infrastructure. See the configuration section for the ScriptOutputHandler class for the list of sample languages.

Note: curn comes bundled with a compatible version of the BSF bsf.jar file. If you're running Java 6, and you want JSR 223 support for languages other than Javascript, please see https://scripting.dev.java.net/.

Writing the Script

The ScriptOutputHandler class's displayChannel() method doesn't actually generated any output. Instead, it buffers the channels so that the flush() method can invoke the script. That way, the overhead of invoking the script occurs only once.

The ScriptOutputHandler object exposes a special curn object to the invoked script; that object contains the following fields and methods, all of which are available to the script. The curn object is exposed via BSFManager.declareBean(), which means it is a global variable that is automatically accessible to the script, without the need for the script to call any methods to find it.

Here's a sample Jython script that shows how to put it all together. This script reimplements most of the functionality of the org.clapper.curn.output.TextOutputHandler Java class that comes with curn. (Note that the script uses a org.clapper.util.io.WordWrapWriter object for its output. While the word-wrapping functionality could have been implemented directly in Jython, this strategy both saves time and demonstrates how easily you can use existing Java classes from a Jython script.)

Class documentation, copyrights, etc., have been stripped from the script for brevity. You can find the complete script, along with a JRuby implementation of the same functionality, in the curn source bundle, in directory src/org/clapper/curn/output/script.

Configuring the Script Output Handler

The configuration section for the ScriptOutputHandler class provides a detailed description of the configuration parameters. Here is a sample configuration entry for our TextOutputHandler.py Jython script.

Installing Supporting Software

As noted in the Overview of Plug-In Support section, curn searches for plug-ins in the following directories:

• curn_home/plugins
• user_home/curn/plugins
• user_home/.curn/plugins

curn implicitly adds those directories to the internal class path used by the curn custom class loader. curn also loads the following directories into its class loader:

• curn_home/lib
• user_home/curn/lib
• user_home/.curn/lib

If you've written or installed a plug-in, output handler or RSS parser adapter that requires some third-party support software (e.g., a third-party RSS parser engine), or if you want to enable logging using a non-bundled logging framework such as Log4J), you'll have to install the appropriate support jars somewhere where curn can find them. If you install the jars in the lib directory underneath the curn installation directory, then they'll be available to any user who runs that curn installation. However, if you don't have permission to update that directory, or you only want to make your extensions available to you, then you can install your software in the appropriate lib directory under your home directory.

Troubleshooting

In the event of problems, your first step should be to enable logging. The next section discusses curn's logging infrastructure.

Logging

curn issues log messages via the Jakarta Commons Logging API (JCL), so it'll log to any JCL-compatible logging framework. The two most popular frameworks are Log4J and the java.util.logging framework that comes with the Java JDK or J2SE runtime.

curn's graphical installer automatically installs the JCL jars, but it does not install Log4J (or any other third-party logging framework); so, by default, curn will log via the java.util.logging API.

When initialized at runtime, some underlying logging frameworks will automatically begin logging if they find an appropriate configuration file in some default location. To prevent this behavior, curn does not initialize the JCL layer unless the --logging command-line parameter is specified. If --logging is not specified, curn will not issue log messages even if default logging configuration files are present.

All curn Java classes are in packages within the org.clapper.curn namespace.

Each logging framework has its own initialization files; the following two sections show how you might enable logging for the two more popular logging frameworks, java.util.logging and Log4J.

java.util.logging

This section assumes that you're using a properties file to configure the logging framework; if you're using a custom logging configuration class, you'll have to work out the configuration details yourself.

When you use the java.util.logging framework with curn, you must specify the location of the logging configuration file with system property java.util.logging.config.file. file. According to the Javadoc for the LogManager class, the property may be set via the Preferences API or as a command-line property definition passed to the java command.

To invoke curn on a Unix-like system, so that it logs through the java.util.logging framework, you might use a command line like this:

java -Djava.util.logging.config.file=/home/bmc/curn/logging.properties org.clapper.curn.Tool --logging /home/bmc/curn/curn.cfg

The curn shell script installed by the graphical installer understands -D parameters; if you use the shell script, you can shorten the above command to:

curn -Djava.util.logging.config.file=/home/bmc/curn/logging.properties --logging /home/bmc/curn/curn.cfg

Alternatively, you can set those values in the CURN_JAVA_VM_ARGS environment variable, and curn will automatically supply them to the Java virtual machine. For example:

export CURN_JAVA_VM_ARGS="-Djava.util.logging.config.file=/home/bmc/curn/logging.properties"
curn --logging /home/bmc/.curn/curn.cfg

The Windows curn.bat command file currently does not understand -D parameters, so you must use the CURN_JAVA_VM_ARGS environment variable method. For instance:

set CURN_JAVA_VM_ARGS=-Djava.util.logging.config.file=/home/bmc/curn/logging.properties
curn --logging %HOME%\.curn\curn.cfg

Here's a configuration file that writes logs all messages at the "info" level or lower, to a file. (Change "INFO" to "FINEST" to get messages at the debug level.)

handlers=java.util.logging.FileHandler
.level=FINEST

# %h is replaced with the user's home directory
java.util.logging.FileHandler.pattern = %h/curn/log.out
java.util.logging.FileHandler.level=FINEST
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

org.clapper.curn.level=INFO

If you want to have exceptions mailed to you (which can be useful when running curn from a scheduler, such as cron(8)), then download and install the SMTPHandler class from smtphandler.sourceforge.net, and use this configuration file, instead:

handlers=java.util.logging.FileHandler
.level=FINEST

# %h is replaced with the user's home directory
java.util.logging.FileHandler.pattern = %h/curn/log.out
java.util.logging.FileHandler.level=FINEST
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

smtphandler.SMTPHandler.level=WARNING
smtphandler.SMTPHandler.smtpHost=your_smtp_host_here
smtphandler.SMTPHandler.to=your_email_address_here
smtphandler.SMTPHandler.from=your_email_address_here
smtphandler.SMTPHandler.subject=[SMTPHandler] curn error
smtphandler.SMTPHandler.bufferSize=4096
smtphandler.SMTPHandler.formatter=smtphandler.SMTPHandler

org.clapper.curn.level=INFO

Note that both files use the org.clapper.util.misc.JDK14TextLogFormatter formatter class, instead of the JDK-supplied java.util.logging.SimpleFormatter. I don't care for the text format that SimpleFormatter produces, so I use a formatter in from utility library that produces output that's similar to the default Log4J text formatter.

Obviously, you can use any formatter you wish, including the java.util.logging.XMLFormatter class.

Log4J

Before you can use the Log4J framework with curn, you must install the log4j.jar file so that curn can find it. (You can download that file from http://logging.apache.org/log4j/.) See the section entitled Installing Support Software for details on where to install log4j.jar.

When you use the Log4J framework with curn, you must specify the location of the logging configuration file using system property log4j.configuration Unlike the java.util.logging framework, the argument to log4j.configuration is not a pathname; it's URL.

To invoke curn on a Unix-like system, so that it logs through the Log4J framework, you might use a command line like this:

java -Dlog4j.configuration=file:///home/bmc/curn/logging.properties org.clapper.curn.Tool --logging /home/bmc/curn/curn.cfg

The curn shell script installed by the graphical installer understands -D parameters; if you use the shell script, you can shorten the above command to:

curn -Djava.util.logging.config.file=/home/bmc/curn/logging.properties --logging /home/bmc/curn/curn.cfg

Alternatively, you can set those values in the CURN_JAVA_VM_ARGS environment variable, and curn will automatically supply them to the Java virtual machine. For example:

export CURN_JAVA_VM_ARGS="-Djava.util.logging.config.file=/home/bmc/curn/logging.properties"
curn --logging /home/bmc/.curn/curn.cfg

The Windows curn.bat command file currently does not understand -D parameters, so you must use the CURN_JAVA_VM_ARGS environment variable method. For instance:

set CURN_JAVA_VM_ARGS=-Djava.util.logging.config.file=/home/bmc/curn/logging.properties
curn --logging %HOME%\.curn\curn.cfg

Here's a configuration file that writes logs all messages at the "info" level or lower, to a file. (Change "info" to "debug" to get messages at the debug level.)

log4j.rootLogger=info, File
log4j.appender.File=org.apache.log4j.FileAppender
log4j.appender.File.layout=org.apache.log4j.PatternLayout

log4j.appender.File.file=${user.home}/curn/log.out

# Overwrite the file each time
log4j.appender.File.append=false

# Print the date in ISO 8601 format
log4j.appender.File.layout.ConversionPattern=%d %-5p (%c{1}): %m%n

log4j.logger.org.clapper.curn=info

If you want to have exceptions mailed to you (which can be useful when running curn from a scheduler, such as cron(8)), then you have to use the Log4J LevelRangeFilter class to filter the messages going to individual Log4J appenders. You can't use a properties-based configuration file in this case, because Log4J's properties file configurator doesn't support filters. Instead, you must use an XML configuration file, such as the one shown below.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

  <appender name="logfile" class="org.apache.log4j.FileAppender">
    <param name="File" value="${user.home}/.curn/log.out"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="=%d %-5p (%c{1}): %m%n"/>
    </layout>
  </appender>

  <appender name="mail" class="org.apache.log4j.net.SMTPAppender">
    <param name="BufferSize" value="4096"/>
    <param name="From" value="bmc@clapper.org"/>
    <param name="To" value="bmc@clapper.org"/>
    <param name="Subject" value="curn log message"/>
    <param name="SMTPHost" value="mail.inside.clapper.org"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="=%d %-5p (%c{1}): %m%n"/>
    </layout>

    <filter class="org.apache.log4j.varia.LevelRangeFilter">
      <param name="LevelMin" value="error"/>
      <param name="AcceptOnMatch" value="true"/>
    </filter>
  </appender>

  <logger name="org.clapper.curn">
    <level value="debug"/>
    <appender-ref ref="mail"/>
    <appender-ref ref="logfile"/>
  </logger>

  <root>
    <level value="fatal"/>
    <appender-ref ref="logfile"/>
    <appender-ref ref="mail"/>
  </root>
</log4j:configuration>

Note that both files use the org.clapper.util.misc.JDK14TextLogFormatter formatter class, instead of the JDK-supplied java.util.logging.SimpleFormatter. I don't care for the text format that SimpleFormatter produces, so I use a formatter in from utility library that produces output that's similar to the default Log4J text formatter.

Obviously, you can use any formatter you wish, including the java.util.logging.XMLFormatter class.

Appendix A: Similar Products and Tools

Adam Sampson's rawdog (RSS Aggregator Without Delusions Of Grandeur) is similar in spirit, features, and invocation. It's written in Python. Like curn, rawdog is intended to be run from a scheduler such as cron.

Appendix B: Copyrights

curn is copyright © 2004-2010 Brian M. Clapper. All rights reserved. This software is licensed under a BSD-style license.

curn uses software (Freemarker) developed by the Visigoth Software Society (http://www.visigoths.org/).It is licensed under a BSD-style license.

curn uses the ASM Bytecode Manipulation Library, which is copyright © 2000-2005 INRIA, France Telecome. All rights reserved.

curn uses the Java Mail API and the Java Beans Activation Framework, which are copyright © Sun Microsystems, Inc.

curn uses the Apache Jakarta Bean Scripting Framework (BSF), the Jakarta Commons Logging API, and the Apache Xerces XML parser API. All are copyright © The Apache Software Foundation.

curn is integrated with the ROME RSS parser (though it does not use that parser by default). ROME is copyright © 2004 Sun Microsystems, Inc and is licensed under the Apache License, Version 2.0.

End Notes

[1] Normally, adding attachments to an email message results in a "multipart/mixed" message. According to RFC 1341, the differences between "multipart/mixed" and "multipart/alternative" messages are:

[2] curn's configuration file is parsed by a subclass of the org.clapper.util.config.Configuration class, so it implicitly supports all the features provided by that class.

[3] It's also possible, though hairy, to escape the special meaning of special characters via the backslash character. For instance, you can escape the variable substitution lead-in character, '$', with a backslash. e.g., "\$". This technique is not recommended, however, because you have to double-escape any backslash characters that you want to be preserved literally. For instance, to get "\t", you must specify "\\\\t". To get a literal backslash, specify "\\\\". (Yes, that's four backslashes, just to get a single unescaped one.) This double-escaping is a regrettable side effect of how the configuration file parses variable values: It makes two separate passes over the value, one for metacharacter expansion and another for variable expansion. Each of those passes honors and processes backslash escapes. This problem would go away if the configuration file parser parsed both metacharacter sequences and variable substitutions itself, in one pass. It doesn't currently do that, because I wanted to make use of the existing org.clapper.util.text.XStringBuffer class's decodeMetacharacters() method and the org.clapper.util.text.UnixShellVariableSubstituter class. In general, you're better off just sticking with single quotes. I may eventually fix this problem, but single quotes work now and will continue to work regardless.

$Id$