class Mail::Field

Provides a single class to call to create a new structured or unstructured field. Works out per RFC what field of field it is being given and returns the correct field of class back on new.

Per RFC 2822

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

FIELDS_MAP
FIELD_ORDER
KNOWN_FIELDS
STRUCTURED_FIELDS

Public Class Methods

new(name, value = nil, charset = 'utf-8') click to toggle source

Accepts a string:

Field.new("field-name: field data")

Or name, value pair:

Field.new("field-name", "value")

Or a name by itself:

Field.new("field-name")

Note, does not want a terminating carriage return. Returns self appropriately parsed. If value is not a string, then it will be passed through as is, for example, content-type field can accept an array with the type and a hash of parameters:

Field.new('content-type', ['text', 'plain', {:charset => 'UTF-8'}])
# File lib/mail/field.rb, line 110
def initialize(name, value = nil, charset = 'utf-8')
  case
  when name =~ /:/                  # Field.new("field-name: field data")
    charset = value unless value.blank?
    name, value = split(name)
    create_field(name, value, charset)
  when name !~ /:/ && value.blank?  # Field.new("field-name")
    create_field(name, nil, charset)
  else                              # Field.new("field-name", "value")
    create_field(name, value, charset)
  end
  return self
end

Public Instance Methods

<=>( other ) click to toggle source
# File lib/mail/field.rb, line 158
def <=>( other )
  self_order = FIELD_ORDER.rindex(self.name.to_s.downcase) || 100
  other_order = FIELD_ORDER.rindex(other.name.to_s.downcase) || 100
  self_order <=> other_order
end
==( other )
Alias for: same
field() click to toggle source
# File lib/mail/field.rb, line 128
def field
  @field
end
field=(value) click to toggle source
# File lib/mail/field.rb, line 124
def field=(value)
  @field = value
end
method_missing(name, *args, &block) click to toggle source
# File lib/mail/field.rb, line 164
def method_missing(name, *args, &block)
  field.send(name, *args, &block)
end
name() click to toggle source
# File lib/mail/field.rb, line 132
def name
  field.name
end
same( other ) click to toggle source
# File lib/mail/field.rb, line 152
def same( other )
  match_to_s(other.name, field.name)
end
Also aliased as: ==
to_s() click to toggle source
# File lib/mail/field.rb, line 144
def to_s
  field.to_s
end
update(name, value) click to toggle source
# File lib/mail/field.rb, line 148
def update(name, value)
  create_field(name, value, charset)
end
value() click to toggle source
# File lib/mail/field.rb, line 136
def value
  field.value
end
value=(val) click to toggle source
# File lib/mail/field.rb, line 140
def value=(val)
  create_field(name, val, charset)
end

Private Instance Methods

create_field(name, value, charset) click to toggle source
# File lib/mail/field.rb, line 186
def create_field(name, value, charset)
  begin
    self.field = new_field(name, value, charset)
  rescue Mail::Field::ParseError => e
    self.field = Mail::UnstructuredField.new(name, value)
    self.field.errors << [name, value, e]
    self.field
  end
end
new_field(name, value, charset) click to toggle source
# File lib/mail/field.rb, line 196
def new_field(name, value, charset)
  lower_case_name = name.to_s.downcase
  header_name = nil
  FIELDS_MAP.each do |field_name, _|
    header_name = field_name if lower_case_name == field_name
  end
  if header_name
    FIELDS_MAP[header_name].new(value, charset)
  else
    OptionalField.new(name, value, charset)
  end

end
split(raw_field) click to toggle source
# File lib/mail/field.rb, line 179
def split(raw_field)
  match_data = raw_field.mb_chars.match(/^(#{FIELD_NAME})\s*:\s*(#{FIELD_BODY})?$/)
  [match_data[1].to_s.mb_chars.strip, match_data[2].to_s.mb_chars.strip]
rescue
  STDERR.puts "WARNING: Could not parse (and so ignoring) '#{raw_field}'"
end