2.1. The rfc822address Structure

When dealing with librfc822, the results of the parsing process will be placed into the rfc822address structure, which is defined as follows:

 class rfc822address {
  std::string address;
  std::string localpart;
  std::string hostpart;
}

The address field will contain the complete address without any comments, whitespace, or whatever madness the standard allows. If you want to compare to addresses for equity, this is the place to go. The localpart field is set to the localpart of the address. "localpart" in that context does not necessarily mean "username". For addresses of the type "user@example.org", "user" will be the localpart, granted, but when parsing the routing address "<@example.com:user@example.org>", the localpart will be "user@example.org". Imagine the "localpart" as being that part of the address that remains when the "hostpart" is stripped off!

In case of a routing address, the hostpart will be the first hostname in the list of routed hosts and the remainder will be the localpart. So, when having an address parsed by the library, you can check whether the address is really a local address by checking whether the localpart field does still contain an "@". If it does, parse it again (and again, and again …) to get the username.

The hostpart field will contain the name of the host that would interpret this address as "local". This should be relatively clear from the discussion of the localpart field.

rfc822.hh defines an operator<< for rfc822address, so you can print instances of the structure to any std::ostream, but the format printed by the operator is meant more or less for debugging purposes, not for anything useful. An operator>> is not defined by the library.

2.2. The check_rfc822_xxx functions

This set of free functions is defined in rfc822.hh. Each of these routines parses a certain type of address, as defined in the standard, but no results are returned. Rather, these functions will be used to verify the addresses syntax. If an address contains an error, an rfc822_syntax_error exception will be thrown.

The available routines are:

Obviously, the syntax specification here is a bit short. Please refer to section 6 of [RFC822] for further details!

2.3. The parse_rfc822_xxx functions

This set of free functions is defined in rfc822.hh. Each of these routines parses a certain type of address, as defined in the standard, and returns the result in one or more rfc822address structure. The routines that parse a single address will return the structure directly as the return value, the routines that may possibly return multiple addresses require an additional parameter of type std::insert_iterator<T>* -- a pointer to a class instance that will be used to append the results to a container of your choice.

If an address contains an syntax error, an rfc822_syntax_error exception will be thrown. Please note that when the exception is thrown, an arbitrary number of addresses might already have been added to the container!

The available routines are:

Obviously, the syntax specification here is a bit short. Please refer to section 6 of [RFC822] for further details!

One more note: It is legal to pass "0" for the ii parameter; in that case, the routines will throw all parsers results away and effectively act like the corresponding check_rfc822_xxx function.

3.1. The Lexer

The lexer used in librfc822 is a free function called lex, which is defined in rfc822.hh. Its synopsis is:

lex will walk throught the text buffer input and produce a stream of actual tokens. Everything that's not a token according to the standard is omitted, such as whitespace, comments, etc. tokstream_t is defined to be std::deque<token> in rfc822.hh, but don't depend on the choice of the container, because it might change in future versions of the library. Use the abstract name instead.

The token structure contains an enumerator, which defines the type of the token and the actual string value of the token. Please refer to rfc822.hh and lexer.cc if you want to know those details. They are usually not important for users of the library.

3.2. The Parser

The parser of librfc822 consists of the class rfc822parser, which is defined in rfc822.hh. It's public interface is:

 class rfc822parser {

  rfc822parser(tokstream_t ts, address_comitter* c);

  void addresses();
  void mailboxes();
  void address();
  rfc822address mailbox();
  rfc822address route_addr();
  rfc822address addr_spec();
  bool empty();
}

Obviously, the parser class must be created with a token stream as returned by lex and a pointer to a committer class, which is used to return the parsed results by the member functions that may return multiple addresses. This data is stored internally in the class and may be erased once rfc822parser is instantiated. Consequently, you may parse only one token stream per parser instance, but creating an instance is not very expensive.

Once the rfc822parser instance has been created, you may call the various member functions repeatedly to parse the corresponding expression. The parsed tokens are thereby consumed from the internal token stream. If no tokens are left, the rfc822parser::empty() function will return true.

3.3. The Address Committer

The class rfc822parser::address_committer defines an interface from which you can derive your own committer classes. rfc822.hh defines this interface as follows:

 class rfc822parser::address_committer {

  virtual void operator()(const rfc822address& address);
}

It effectively implements a simple callback. Whenever any of the member functions rfc822parser::address, rfc822parser::addresses, or rfc822parser::mailboxes finds a complete RFC822 address, it will invoke the instance of the committer class that rfc822parser has been instantiated with. If the class has been instantiated with "0" for a pointer to the committer class, the results of the parser will be thrown away.

3.4. An Example Program

#include <rfc822.hh>
using namespace std;

class my_committer : public rfc822parser::address_committer
    {
  public:
    void operator() (const rfc822address & addr)
        {
        cout << addr << endl;
        }
    };

int main()
try
    {
    string input = \
        "testing my parser : peter.simons@gmd.de,\n"    \
        "\t (peter.)simons@rhein.de ,,,,,\n"            \
        "\t testing my parser <simons@ieee.org>,\n"     \
        "\t it rules <@peti.gmd.de:simons @ cys .de>\n" \
        "\t ;\n"                                        \
        "\t ,\n"                                        \
        "\t peter.simons@acm.org\n";

    my_committer   committer;
    rfc822parser parser(lex(input), &committer);
    parser.addresses();

    return 0;
    }
catch(rfc822_syntax_error & e)
    {
    cout << "Address contains an syntax error: " << e.what() << endl;
    }
catch(...)
    {
    cout << "Caught unknown exception." << endl;
    }