Class RMail::StreamHandler

In: | lib/rmail/parser.rb
Parent: | Object

# Overview

An RMail::StreamHandler documents the set of methods a RMail::StreamParser handler must implement. See RMail::StreamParser.parse. This is a low level interface to the RMail message parser.

# Order of Method Calls (Grammar)

Calls to the methods of this class follow a specific grammar, described informally below. The words in all caps are productions in the grammar, while the lower case words are method calls to this object.

MESSAGE: | [ #mbox_from ] *( #header_field ) ( BODY / MULTIPART_BODY )
BODY: | *body_begin *( #body_chunk ) #body_end
MULTIPART_BODY: | #multipart_body_begin *( #preamble_chunk ) *( #part_begin MESSAGE #part_end) *( #epilogue_chunk ) #multipart_body_end

# Order of Method Calls (English)

If the grammar above is not clear, here is a description in English.

The parser begins calling #header_field, possibly calling #mbox_from for the first line. Then it determines if the message was a MIME multipart message.

If the message is a not a MIME multipart, the parser calls #body_begin once, then #body_chunk any number of times, then #body_end.

If the message header is a MIME multipart message, then #multipart_body_begin is called, followed by any number of calls to #preamble_chunk. Then for each part parsed, #part_begin is called, followed by a recursive set of calls described by the "MESSAGE" production above, and then #part_end. After all parts are parsed, any number of calls to #epilogue_chunk are followed by a single call to #multipart_body_end.

The recursive nature of MIME multipart messages is represented by the recursive invocation of the "MESSAGE" production in the grammar above.

Methods

body_begin body_chunk body_end epilogue_chunk header_field mbox_from multipart_body_begin multipart_body_end part_begin part_end preamble_chunk

Public Instance methods

mbox_from(line)

This method is called for Unix MBOX "From " lines in the message header, it calls this method with the text.

header_field(field, name, value)

This method is called when a header field is parsed. The `field` is the full text of the field, the `name` is the name of the field and the `value` is the field’s value with leading and trailing whitespace removed. Note that both `field` and `value` may be multi-line strings.

body_begin()

This method is called before a non-multipart message body is about to be parsed.

body_chunk(chunk)

This method is called with a string chunk of data from a non-multipart message body. The string does not necessarily begin or end on any particular boundary.

body_end()

This method is called after all of the non-multipart message body has been parsed.

multipart_body_begin()

This method is called before a multipart message body is about to be parsed.

preamble_chunk(chunk)

This method is called with a chunk of data from a multipart message body’s preamble. The preamble is any text that appears before the first part of the multipart message body.

part_begin()

This method is called when a part of a multipart body begins.

part_end()

This method is called when a part of a multipart body ends.

epilogue_chunk(chunk)

This method is called with a chunk of data from a multipart message body’s epilogue. The epilogue is any text that appears after the last part of the multipart message body.

multipart_body_end(delimiters, boundary)

This method is called after a multipart message body has been completely parsed.

The `delimiters` is an Array of strings, one for each boundary string found in the multipart body. The `boundary` is the boundary string used to delimit each part in the multipart body. You can normally ignore both `delimiters` and `boundary` if you are concerned only about message content.