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
FIELD_ORDER_LOOKUP
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.field_order_id <=> other.field_order_id
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

field_order_id() click to toggle source

# File lib/mail/field.rb, line 162
def field_order_id
  @field_order_id ||= (FIELD_ORDER_LOOKUP[self.name.to_s.downcase] || 100)
end

method_missing(name, *args, &block) click to toggle source

# File lib/mail/field.rb, line 166
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 190
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 200
def new_field(name, value, charset)
  lower_case_name = name.to_s.downcase
  if field_klass = FIELDS_MAP[lower_case_name]
    field_klass.new(value, charset)
  else
    OptionalField.new(name, value, charset)
  end
end

split(raw_field) click to toggle source

# File lib/mail/field.rb, line 183
def split(raw_field)
  match_data = raw_field.mb_chars.match(FIELD_SPLIT)
  [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