Class RMail::Parser::PushbackReader
In: lib/rmail/parser/pushbackreader.rb
Parent: Object

A utility class for reading from an input source in an efficient chunked manner.

The idea is to read data in descent sized chunks (the default is 16k), but provide a way to "push back" some of the chunk if we read too much.

This class is useful only as a base class for other readers -- e.g. a reader that parses MIME multipart documents, or a reader that understands one or more mailbox formats.

The typical RubyMail user will have no interest in this class. ;-)

:chunk_size  [R] 

Retrieve the chunk size of this reader.

Public Class methods

Create a PushbackReader and have it read from a given input source.

The input source must either be a String or respond to the "read" method in the same way as an IO object.


Creates a regexp that'll match the given boundary string in its entirely anywhere in a string, or any partial prefix of the boundary string so long as the match is anchored at the end of the string. This is useful for various subclasses of PushbackReader that need to know if a given input chunk might contain (or contain just the beginning of) an interesting string.

Public Instance methods
read(size = @chunk_size)

Read a chunk of input. The "size" argument is just a suggestion, and more or fewer bytes may be returned. If "size" is nil, then return the entire rest of the input stream.


Read a chunk of a given size. Unlike #read, #read_chunk must be passed a chunk size, and cannot be passed nil.

This is the function that should be re-defined in subclasses for specialized behavior.


The standard implementation of read_chunk. This can be convenient to call from derived classes when super() isn't easy to use.


Push a string back. This will be the next chunk of data returned by #read.

Because it has not been needed and would compromise efficiency, only one chunk of data can be pushed back between successive calls to #read.


Set the chunk size of this reader in bytes. This is useful mainly for testing, though perhaps some operations could be optimized by tweaking this value. The chunk size must be a Fixnum greater than 0.


Returns true if the next call to read_chunk will return nil.