Class: RMail::Parser::PushbackReader

Inherits:
Object
  • Object
show all
Defined in:
lib/rmail/parser/pushbackreader.rb

Overview

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. ;-)

Direct Known Subclasses

Mailbox::MBoxReader, MultipartReader

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input) ⇒ PushbackReader

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.



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/rmail/parser/pushbackreader.rb', line 54

def initialize(input)
  unless defined? input.read(1)
    unless input.is_a?(String)
      raise ArgumentError, "input object not IO or String"
    end
    @pushback = input
    @input = nil
  else
    @pushback = nil
    @input = input
  end
  @chunk_size = 16384
end

Instance Attribute Details

#chunk_size ⇒ Object

Retrieve the chunk size of this reader.



131
132
133
 
# File 'lib/rmail/parser/pushbackreader.rb', line 131

def chunk_size
  @chunk_size
end

Class Method Details

.maybe_contains_re(boundary) ⇒ 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.



159
160
161
162
163
164
165
166
167
168
 
# File 'lib/rmail/parser/pushbackreader.rb', line 159

def self.maybe_contains_re(boundary)
  left = Regexp.quote(boundary[0,1])
  right = ''
  boundary[1..-1].each_byte { |ch|
    left << '(?:'
    left << Regexp.quote(ch.chr)
    right << '|\z)'
  }
  left + right
end

Instance Method Details

#eof ⇒ Object

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



148
149
150
 
# File 'lib/rmail/parser/pushbackreader.rb', line 148

def eof
  @pushback.nil? and (@input.nil? or @input.eof)
end

#pushback(string) ⇒ Object

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.

Raises:



124
125
126
127
128
 
# File 'lib/rmail/parser/pushbackreader.rb', line 124

def pushback(string)
  raise RMail::Parser::Error,
    'You have already pushed a string back.' if @pushback
  @pushback = string
end

#read(size = @chunk_size) ⇒ Object

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.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/rmail/parser/pushbackreader.rb', line 72

def read(size = @chunk_size)
  case size
  when nil
    chunk = nil
    while temp = read(@chunk_size)
      if chunk
        chunk << temp
      else
        chunk = temp
      end
    end
    chunk
  when Fixnum
    read_chunk(size)
  else
    raise ArgumentError,
      "Read size (#{size.inspect}) must be a Fixnum or nil."
  end
end

#read_chunk(size) ⇒ Object

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.



97
98
99
 
# File 'lib/rmail/parser/pushbackreader.rb', line 97

def read_chunk(size)
  standard_read_chunk(size)
end

#standard_read_chunk(size) ⇒ Object

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



104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/rmail/parser/pushbackreader.rb', line 104

def standard_read_chunk(size)
  unless size.is_a?(Fixnum) && size > 0
    raise ArgumentError,
      "Read size (#{size.inspect}) must be greater than 0."
  end
  if @pushback
    chunk = @pushback
    @pushback = nil
  elsif ! @input.nil?
    chunk = @input.read(size)
  end
  return chunk
end