# class RMail::StreamHandler

# 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.

### Public Instance Methods

body_begin() click to toggle source

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

    # File lib/rmail/parser.rb, line 100
    def body_begin
    end

body_chunk(chunk) click to toggle source

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.

    # File lib/rmail/parser.rb, line 106
    def body_chunk(chunk)
    end

body_end() click to toggle source

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

    # File lib/rmail/parser.rb, line 111
    def body_end
    end

epilogue_chunk(chunk) click to toggle source

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.

    # File lib/rmail/parser.rb, line 136
    def epilogue_chunk(chunk)
    end

header_field(field, name, value) click to toggle source

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.

    # File lib/rmail/parser.rb, line 95
    def header_field(field, name, value)
    end

mbox_from(line) click to toggle source

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

    # File lib/rmail/parser.rb, line 87
    def mbox_from(line)
    end

multipart_body_begin() click to toggle source

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

    # File lib/rmail/parser.rb, line 116
    def multipart_body_begin
    end

multipart_body_end(delimiters, boundary) click to toggle source

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.

    # File lib/rmail/parser.rb, line 147
    def multipart_body_end(delimiters, boundary)
    end

part_begin() click to toggle source

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

    # File lib/rmail/parser.rb, line 126
    def part_begin
    end

part_end() click to toggle source

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

    # File lib/rmail/parser.rb, line 130
    def part_end
    end

preamble_chunk(chunk) click to toggle source

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.

    # File lib/rmail/parser.rb, line 122
    def preamble_chunk(chunk)
    end