Provides access to a header object.
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.
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
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 117 117: def [](name) 118: name = dasherize(name).downcase 119: selected = select_field_for(name) 120: case 121: when selected.length > 1 122: selected.map { |f| f } 123: when !selected.blank? 124: selected.first 125: else 126: nil 127: end 128: end
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 143 143: def []=(name, value) 144: name = dasherize(name) 145: fn = name.downcase 146: selected = select_field_for(fn) 147: 148: case 149: # User wants to delete the field 150: when !selected.blank? && value == nil 151: fields.delete_if { |f| selected.include?(f) } 152: 153: # User wants to change the field 154: when !selected.blank? && limited_field?(fn) 155: selected.first.update(fn, value) 156: 157: # User wants to create the field 158: else 159: # Need to insert in correct order for trace fields 160: self.fields << Field.new(name.to_s, value, charset) 161: end 162: end
# File lib/mail/header.rb, line 164 164: def charset 165: params = self[:content_type].parameters rescue nil 166: if params 167: params[:charset] 168: else 169: @charset 170: end 171: end
# File lib/mail/header.rb, line 173 173: def charset=(val) 174: params = self[:content_type].parameters rescue nil 175: if params 176: params[:charset] = val 177: end 178: @charset = val 179: end
# File lib/mail/header.rb, line 199 199: def decoded 200: raise NoMethodError, 'Can not decode an entire header as there could be character set conflicts, try calling #decoded on the various fields.' 201: end
# File lib/mail/header.rb, line 187 187: def encoded 188: buffer = '' 189: fields.each do |field| 190: buffer << field.encoded 191: end 192: buffer 193: end
# File lib/mail/header.rb, line 92 92: def errors 93: @errors 94: end
# File lib/mail/header.rb, line 203 203: def field_summary 204: fields.map { |f| "<#{f.name}: #{f.value}>" }.join(", ") 205: end
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
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: warn "Warning: more than 1000 header fields only using the first 1000" if unfolded_fields.length > 1000 77: unfolded_fields[0..1000].each do |field| 78: 79: field = Field.new(field, nil, charset) 80: field.errors.each { |error| self.errors << error } 81: selected = select_field_for(field.name) 82: 83: if selected.any? && limited_field?(field.name) 84: selected.first.update(field.name, field.value) 85: else 86: @fields << field 87: end 88: end 89: 90: end
Returns true if the header has a Content-ID defined (empty or not)
# File lib/mail/header.rb, line 213 213: def has_content_id? 214: !fields.select { |f| f.responsible_for?('Content-ID') }.empty? 215: end
Returns true if the header has a Date defined (empty or not)
# File lib/mail/header.rb, line 218 218: def has_date? 219: !fields.select { |f| f.responsible_for?('Date') }.empty? 220: end
Returns true if the header has a Message-ID defined (empty or not)
# File lib/mail/header.rb, line 208 208: def has_message_id? 209: !fields.select { |f| f.responsible_for?('Message-ID') }.empty? 210: end
Returns true if the header has a MIME version defined (empty or not)
# File lib/mail/header.rb, line 223 223: def has_mime_version? 224: !fields.select { |f| f.responsible_for?('Mime-Version') }.empty? 225: end
# File lib/mail/header.rb, line 260 260: def limited_field?(name) 261: LIMITED_FIELDS.include?(name.to_s.downcase) 262: end
# File lib/mail/header.rb, line 229 229: def raw_source=(val) 230: @raw_source = val 231: end
# File lib/mail/header.rb, line 256 256: def select_field_for(name) 257: fields.select { |f| f.responsible_for?(name.to_s) } 258: end
Splits an unfolded and line break cleaned header into individual field strings.
# File lib/mail/header.rb, line 252 252: def split_header 253: self.fields = unfolded_header.split(CRLF) 254: end
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 241 241: def unfold(string) 242: string.gsub(/#{CRLF}#{WSP}+/, ' ').gsub(/#{WSP}+/, ' ') 243: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.