Mail::Header

Provides access to a header object.

Per RFC2822

 2.2. Header Fields

  Header fields are lines composed of a field name, followed by a colon
  (":"), followed by a field body, and terminated by CRLF.  A field
  name MUST be composed of printable US-ASCII characters (i.e.,
  characters that have values between 33 and 126, inclusive), except
  colon.  A field body may be composed of any US-ASCII characters,
  except for CR and LF.  However, a field body may contain CRLF when
  used in header "folding" and  "unfolding" as described in section
  2.2.3.  All field bodies MUST conform to the syntax described in
  sections 3 and 4 of this standard.

Constants

LIMITED_FIELDS

Public Class Methods

new(header_text = nil, charset = nil) click to toggle source

Creates a new header object.

Accepts raw text or nothing. If given raw text will attempt to parse it and split it into the various fields, instantiating each field as it goes.

If it finds a field that should be a structured field (such as content type), but it fails to parse it, it will simply make it an unstructured field and leave it alone. This will mean that the data is preserved but no automatic processing of that field will happen. If you find one of these cases, please make a patch and send it in, or at the least, send me the example so we can fix it.

    # File lib/mail/header.rb, line 36
36:     def initialize(header_text = nil, charset = nil)
37:       @errors = []
38:       @charset = charset
39:       self.raw_source = header_text.to_crlf
40:       split_header if header_text
41:     end

Public Instance Methods

[](name) click to toggle source

 3.6. Field definitions
 
  The following table indicates limits on the number of times each
  field may occur in a message header as well as any special
  limitations on the use of those fields.  An asterisk next to a value
  in the minimum or maximum column indicates that a special restriction
  appears in the Notes column.

  <snip table from 3.6>

As per RFC, many fields can appear more than once, we will return a string of the value if there is only one header, or if there is more than one matching header, will return an array of values in order that they appear in the header ordered from top to bottom.

Example:

 h = Header.new
 h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
 h['To']          #=> 'mikel@me.com'
 h['X-Mail-SPAM'] #=> ['15', '20']

     # File lib/mail/header.rb, line 116
116:     def [](name)
117:       name = dasherize(name).downcase
118:       selected = select_field_for(name)
119:       case
120:       when selected.length > 1
121:         selected.map { |f| f }
122:       when !selected.blank?
123:         selected.first
124:       else
125:         nil
126:       end
127:     end

[]=(name, value) click to toggle source

Sets the FIRST matching field in the header to passed value, or deletes the FIRST field matched from the header if passed nil

Example:

 h = Header.new
 h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
 h['To'] = 'bob@you.com'
 h['To']    #=> 'bob@you.com'
 h['X-Mail-SPAM'] = '10000'
 h['X-Mail-SPAM'] # => ['15', '20', '10000']
 h['X-Mail-SPAM'] = nil
 h['X-Mail-SPAM'] # => nil

     # File lib/mail/header.rb, line 142
142:     def []=(name, value)
143:       name = dasherize(name)
144:       fn = name.downcase
145:       selected = select_field_for(fn)
146:       
147:       case
148:       # User wants to delete the field
149:       when !selected.blank? && value == nil
150:         fields.delete_if { |f| selected.include?(f) }
151:         
152:       # User wants to change the field
153:       when !selected.blank? && limited_field?(fn)
154:         selected.first.update(fn, value)
155:         
156:       # User wants to create the field
157:       else
158:         # Need to insert in correct order for trace fields
159:         self.fields << Field.new(name.to_s, value, charset)
160:       end
161:     end

charset() click to toggle source

     # File lib/mail/header.rb, line 163
163:     def charset
164:       params = self[:content_type].parameters rescue nil
165:       if params
166:         params[:charset]
167:       else
168:         @charset
169:       end
170:     end

charset=(val) click to toggle source

     # File lib/mail/header.rb, line 172
172:     def charset=(val)
173:       params = self[:content_type].parameters rescue nil
174:       if params
175:         params[:charset] = val
176:       end
177:       @charset = val
178:     end

decoded() click to toggle source

     # File lib/mail/header.rb, line 198
198:     def decoded
199:       raise NoMethodError, 'Can not decode an entire header as there could be character set conflicts, try calling #decoded on the various fields.'
200:     end

encoded() click to toggle source

     # File lib/mail/header.rb, line 186
186:     def encoded
187:       buffer = ''
188:       fields.each do |field|
189:         buffer << field.encoded
190:       end
191:       buffer
192:     end

errors() click to toggle source

    # File lib/mail/header.rb, line 91
91:     def errors
92:       @errors
93:     end

field_summary() click to toggle source

     # File lib/mail/header.rb, line 202
202:     def field_summary
203:       fields.map { |f| "<#{f.name}: #{f.value}>" }.join(", ")
204:     end

fields() click to toggle source

Returns an array of all the fields in the header in order that they were read in.

    # File lib/mail/header.rb, line 51
51:     def fields
52:       @fields ||= FieldList.new
53:     end

fields=(unfolded_fields) click to toggle source

 3.6. Field definitions
 
  It is important to note that the header fields are not guaranteed to
  be in a particular order.  They may appear in any order, and they
  have been known to be reordered occasionally when transported over
  the Internet.  However, for the purposes of this standard, header
  fields SHOULD NOT be reordered when a message is transported or
  transformed.  More importantly, the trace header fields and resent
  header fields MUST NOT be reordered, and SHOULD be kept in blocks
  prepended to the message.  See sections 3.6.6 and 3.6.7 for more
  information.

Populates the fields container with Field objects in the order it receives them in.

Acceps an array of field string values, for example:

 h = Header.new
 h.fields = ['From: mikel@me.com', 'To: bob@you.com']

    # File lib/mail/header.rb, line 74
74:     def fields=(unfolded_fields)
75:       @fields = Mail::FieldList.new
76:       unfolded_fields.each do |field|
77: 
78:         field = Field.new(field, nil, charset)
79:         field.errors.each { |error| self.errors << error }
80:         selected = select_field_for(field.name)
81: 
82:         if selected.any? && limited_field?(field.name)
83:           selected.first.update(field.name, field.value)
84:         else
85:           @fields << field
86:         end
87:       end
88: 
89:     end

has_content_id?() click to toggle source

Returns true if the header has a Content-ID defined (empty or not)

     # File lib/mail/header.rb, line 212
212:     def has_content_id?
213:       !fields.select { |f| f.responsible_for?('Content-ID') }.empty?
214:     end

has_date?() click to toggle source

Returns true if the header has a Date defined (empty or not)

     # File lib/mail/header.rb, line 217
217:     def has_date?
218:       !fields.select { |f| f.responsible_for?('Date') }.empty?
219:     end

has_message_id?() click to toggle source

Returns true if the header has a Message-ID defined (empty or not)

     # File lib/mail/header.rb, line 207
207:     def has_message_id?
208:       !fields.select { |f| f.responsible_for?('Message-ID') }.empty?
209:     end

has_mime_version?() click to toggle source

Returns true if the header has a MIME version defined (empty or not)

     # File lib/mail/header.rb, line 222
222:     def has_mime_version?
223:       !fields.select { |f| f.responsible_for?('Mime-Version') }.empty?
224:     end

raw_source() click to toggle source

The preserved raw source of the header as you passed it in, untouched for your Regexing glory.

    # File lib/mail/header.rb, line 45
45:     def raw_source
46:       @raw_source
47:     end

to_s() click to toggle source

     # File lib/mail/header.rb, line 194
194:     def to_s
195:       encoded
196:     end

Private Instance Methods

limited_field?(name) click to toggle source

     # File lib/mail/header.rb, line 259
259:     def limited_field?(name)
260:       LIMITED_FIELDS.include?(name.to_s.downcase)
261:     end

raw_source=(val) click to toggle source

     # File lib/mail/header.rb, line 228
228:     def raw_source=(val)
229:       @raw_source = val
230:     end

select_field_for(name) click to toggle source

     # File lib/mail/header.rb, line 255
255:     def select_field_for(name)
256:       fields.select { |f| f.responsible_for?(name.to_s) }
257:     end

split_header() click to toggle source

Splits an unfolded and line break cleaned header into individual field strings.

     # File lib/mail/header.rb, line 251
251:     def split_header
252:       self.fields = unfolded_header.split(CRLF)
253:     end

unfold(string) click to toggle source

2.2.3. Long Header Fields

 The process of moving from this folded multiple-line representation
 of a header field to its single line representation is called
 "unfolding". Unfolding is accomplished by simply removing any CRLF
 that is immediately followed by WSP.  Each header field should be
 treated in its unfolded form for further syntactic and semantic
 evaluation.

     # File lib/mail/header.rb, line 240
240:     def unfold(string)
241:       string.gsub(/#{CRLF}#{WSP}+/, ' ').gsub(/#{WSP}+/, ' ')
242:     end

unfolded_header() click to toggle source

Returns the header with all the folds removed

     # File lib/mail/header.rb, line 245
245:     def unfolded_header
246:       @unfolded_header ||= unfold(raw_source)
247:     end

Home Classes Methods

In Files

Parent

Methods

Included Modules