>librfc822 1.0

librfc822 1.0

Peter Simons

simons@computer.org


Table of Contents
1. Purpose of librfc822
2. Building librfc822
3. The test program
4. Documentation
5. Getting the latest version
6. Copyright

1. Purpose of librfc822

librfc822 provides application developers with a complete parser for RFC822 addresses. Not only can you use the library to verify that RFC822 addresses are syntactically correct, you can also have an address split up into its semantic parts, what is needed when deciding where to route an address to, etc.

What is quite unique is that librfc822 does indeed parse all address types allowed by the standard. That includes such weird things as "address groups" or addresses with whitespace and comments throw in. Take a look at this beast to get an idea:

testing my parser : peter.simons@gmd.de,
        (peter.)simons@rhein.de ,,,,,
     testing my parser <simons@ieee.org>,
     it rules <@peti.gmd.de,@listserv.gmd.de:simons @ cys .de>
     ;
     ,
     peter.simons@acm.org

That is indeed a legal e-mail address in RFC822 messages. It contains five separate addresses, which are grouped together. Here's the parsed result:

peter.simons@gmd.de
simons@rhein.de
simons@ieee.org
<@peti.gmd.de,@listserv.gmd.de:simons@cys.de>
peter.simons@acm.org
simons@rhein.de
simons@rhein.de
simons@rhein.de

In case you wonder: The strange looking address that's listed fourth is a so called "routing address" -- and yes, that's a legal e-mail address, too. These were popular in the early days of the Internet. Back then, every mail server that relayed an e-mail put its own address into this construct so that bounces could be routed the same way back that they originally went. The address says that the mail should be send to the host peti.gmd.de, then to listserv.gmd.de, and from there it should be delivered (using any route) to the address simons@cys.de. These days, such addresses can hardly be used, because nobody relays for other recipients anymore. Still, these are legal.

librfc822 provides you with several routines that parse the different flavours of e-mail addresses as defined in the standard. The results will be placed in a rfc822address structure and returned. If constructs are parsed that may contain multiple addresses, you can pass a "committer" class to the function, which is called every time a correct address is found and may append it to a container of your choice.


2. Building librfc822

The distribution contains Makefiles suited for compilation with the GNU C++ compiler. Be adviced, though, that you will need a fairly recent version in order to compile librfc822, because the library makes use of many features of the ISO C++ standard that are not supported by older versions of g++.

Nonetheless, it should be possible to translate librfc822 with other ISO C++ compilers, too; the library does not use any system specific functions with the exception of POSIX regular expressions, but these should be widely available -- at least on Unix platforms. So just take a look at the Makefiles: With only a few modifications you should get along.


3. The test program

Included in the distribution is a small test programm, test.cc, which you can compile by executing make test. When started, this program will read an arbitrary RFC822 address from standard input, then it will parse the address and print the separate addresses.

In addition, the program performs a few parsing operations on addresses built into the binary.

The program is not intended to serve any useful purpose, but you might want to look at the source code to get an impression of how this library may be used.


4. Documentation

The directory documentation contains a complete user's manual for librfc822 -- most notably the files user-manual.html and user-manual.pdf. You should really take a look at them if you plan to use this code. :-)


5. Getting the latest version

The latest version of librfc822 is available from http://cryp.to/librfc822/.


6. Copyright

librfc822 is copyrighted by Peter Simons <simons@computer.org>. Permission is granted to use this code under the terms described in the LICENSE file.