Class: Mail::Header
- Defined in:
- lib/mail/header.rb
Overview
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.
Constant Summary collapse
- LIMITED_FIELDS =
%w[ date from sender reply-to to cc bcc message-id in-reply-to references subject return-path content-type mime-version content-transfer-encoding content-description content-id content-disposition content-location]
Constants included from Patterns
Patterns::ATOM_UNSAFE, Patterns::CONTROL_CHAR, Patterns::CRLF, Patterns::FIELD_BODY, Patterns::FIELD_LINE, Patterns::FIELD_NAME, Patterns::FWS, Patterns::HEADER_LINE, Patterns::PHRASE_UNSAFE, Patterns::QP_SAFE, Patterns::QP_UNSAFE, Patterns::TEXT, Patterns::TOKEN_UNSAFE, Patterns::WSP
Instance Method Summary collapse
-
#[](name) ⇒ Object
3.6.
-
#[]=(name, value) ⇒ Object
Sets the FIRST matching field in the header to passed value, or deletes the FIRST field matched from the header if passed nil.
- #charset ⇒ Object
- #charset=(val) ⇒ Object
- #decoded ⇒ Object
- #encoded ⇒ Object
- #errors ⇒ Object
- #field_summary ⇒ Object
-
#fields ⇒ Object
Returns an array of all the fields in the header in order that they were read in.
-
#fields=(unfolded_fields) ⇒ Object
3.6.
-
#has_content_id? ⇒ Boolean
Returns true if the header has a Content-ID defined (empty or not).
-
#has_date? ⇒ Boolean
Returns true if the header has a Date defined (empty or not).
-
#has_message_id? ⇒ Boolean
Returns true if the header has a Message-ID defined (empty or not).
-
#has_mime_version? ⇒ Boolean
Returns true if the header has a MIME version defined (empty or not).
-
#initialize(header_text = nil, charset = nil) ⇒ Header
constructor
Creates a new header object.
-
#raw_source ⇒ Object
The preserved raw source of the header as you passed it in, untouched for your Regexing glory.
- #to_s ⇒ Object
Methods included from Utilities
#atom_safe?, #bracket, #capitalize_field, #constantize, #dasherize, #dquote, #escape_paren, #map_lines, #map_with_index, #match_to_s, #paren, #quote_atom, #quote_phrase, #quote_token, #token_safe?, #unbracket, #underscoreize, #unparen, #unquote, #uri_escape, #uri_parser, #uri_unescape
Constructor Details
#initialize(header_text = nil, charset = nil) ⇒ Header
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.
36 37 38 39 40 41 |
# File 'lib/mail/header.rb', line 36 def initialize(header_text = nil, charset = nil) @errors = [] @charset = charset self.raw_source = header_text.to_crlf split_header if header_text end |
Instance Method Details
#[](name) ⇒ Object
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: [email protected]', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
h['To'] #=> '[email protected]'
h['X-Mail-SPAM'] #=> ['15', '20']
117 118 119 120 121 122 123 124 125 126 127 128 |
# File 'lib/mail/header.rb', line 117 def [](name) name = dasherize(name).downcase selected = select_field_for(name) case when selected.length > 1 selected.map { |f| f } when !selected.blank? selected.first else nil end end |
#[]=(name, value) ⇒ Object
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: [email protected]', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
h['To'] = '[email protected]'
h['To'] #=> '[email protected]'
h['X-Mail-SPAM'] = '10000'
h['X-Mail-SPAM'] # => ['15', '20', '10000']
h['X-Mail-SPAM'] = nil
h['X-Mail-SPAM'] # => nil
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 |
# File 'lib/mail/header.rb', line 143 def []=(name, value) name = dasherize(name) fn = name.downcase selected = select_field_for(fn) case # User wants to delete the field when !selected.blank? && value == nil fields.delete_if { |f| selected.include?(f) } # User wants to change the field when !selected.blank? && limited_field?(fn) selected.first.update(fn, value) # User wants to create the field else # Need to insert in correct order for trace fields self.fields << Field.new(name.to_s, value, charset) end end |
#charset ⇒ Object
164 165 166 167 168 169 170 171 |
# File 'lib/mail/header.rb', line 164 def charset params = self[:content_type].parameters rescue nil if params params[:charset] else @charset end end |
#charset=(val) ⇒ Object
173 174 175 176 177 178 179 |
# File 'lib/mail/header.rb', line 173 def charset=(val) params = self[:content_type].parameters rescue nil if params params[:charset] = val end @charset = val end |
#decoded ⇒ Object
199 200 201 |
# File 'lib/mail/header.rb', line 199 def decoded raise NoMethodError, 'Can not decode an entire header as there could be character set conflicts, try calling #decoded on the various fields.' end |
#encoded ⇒ Object
187 188 189 190 191 192 193 |
# File 'lib/mail/header.rb', line 187 def encoded buffer = '' fields.each do |field| buffer << field.encoded end buffer end |
#errors ⇒ Object
92 93 94 |
# File 'lib/mail/header.rb', line 92 def errors @errors end |
#field_summary ⇒ Object
203 204 205 |
# File 'lib/mail/header.rb', line 203 def field_summary fields.map { |f| "<#{f.name}: #{f.value}>" }.join(", ") end |
#fields ⇒ Object
Returns an array of all the fields in the header in order that they were read in.
51 52 53 |
# File 'lib/mail/header.rb', line 51 def fields @fields ||= FieldList.new end |
#fields=(unfolded_fields) ⇒ Object
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: [email protected]', 'To: [email protected]']
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 |
# File 'lib/mail/header.rb', line 74 def fields=(unfolded_fields) @fields = Mail::FieldList.new warn "Warning: more than 1000 header fields only using the first 1000" if unfolded_fields.length > 1000 unfolded_fields[0..1000].each do |field| field = Field.new(field, nil, charset) field.errors.each { |error| self.errors << error } selected = select_field_for(field.name) if selected.any? && limited_field?(field.name) selected.first.update(field.name, field.value) else @fields << field end end end |
#has_content_id? ⇒ Boolean
Returns true if the header has a Content-ID defined (empty or not)
213 214 215 |
# File 'lib/mail/header.rb', line 213 def has_content_id? !fields.select { |f| f.responsible_for?('Content-ID') }.empty? end |
#has_date? ⇒ Boolean
Returns true if the header has a Date defined (empty or not)
218 219 220 |
# File 'lib/mail/header.rb', line 218 def has_date? !fields.select { |f| f.responsible_for?('Date') }.empty? end |
#has_message_id? ⇒ Boolean
Returns true if the header has a Message-ID defined (empty or not)
208 209 210 |
# File 'lib/mail/header.rb', line 208 def !fields.select { |f| f.responsible_for?('Message-ID') }.empty? end |
#has_mime_version? ⇒ Boolean
Returns true if the header has a MIME version defined (empty or not)
223 224 225 |
# File 'lib/mail/header.rb', line 223 def has_mime_version? !fields.select { |f| f.responsible_for?('Mime-Version') }.empty? end |
#raw_source ⇒ Object
The preserved raw source of the header as you passed it in, untouched for your Regexing glory.
45 46 47 |
# File 'lib/mail/header.rb', line 45 def raw_source @raw_source end |
#to_s ⇒ Object
195 196 197 |
# File 'lib/mail/header.rb', line 195 def to_s encoded end |