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_NAME_MAP
FIELD_ORDER_LOOKUP
KNOWN_FIELDS
STRUCTURED_FIELDS

Attributes

unparsed_value [R]

Public Class Methods

new (name, value = nil, charset = 'utf-8')

Source

# File lib/mail/field.rb, line 166
def initialize(name, value = nil, charset = 'utf-8')
  case
  when name.index(Constants::COLON)
    raise ArgumentError, 'Passing an unparsed header field to Mail::Field.new is not supported in Mail 2.8.0+. Use Mail::Field.parse instead.'
  when Utilities.blank?(value)
    @name = name
    @unparsed_value = nil
    @charset = charset
  else
    @name = name
    @unparsed_value = value
    @charset = charset
  end
  @name = FIELD_NAME_MAP[@name.to_s.downcase] || @name
end

Create a field by name and optional value:

Mail::Field.new("field-name", "value")
# => #<Mail::Field …>

Values that aren’t strings or arrays are coerced to Strings with ‘#to_s`.

Mail::Field.new("field-name", 1234)
# => #<Mail::Field …>

Mail::Field.new('content-type', ['text', 'plain', {:charset => 'UTF-8'}])
# => #<Mail::Field …>

parse (field, charset = 'utf-8')

Source

# File lib/mail/field.rb, line 122
def parse(field, charset = 'utf-8')
  name, value = split(field)
  if name && value
    new name, value, charset
  end
end

Parse a field from a raw header line:

Mail::Field.parse("field-name: field data")
# => #<Mail::Field …>

Public Instance Methods

<=> (other)

Source

# File lib/mail/field.rb, line 224
def <=>(other)
  field_order_id <=> other.field_order_id
end

== (other)

Source

# File lib/mail/field.rb, line 216
def ==(other)
  same(other) && Utilities.match_to_s(other.value, value)
end

field ()

Source

# File lib/mail/field.rb, line 186
def field
  @field ||= create_field(@name, @unparsed_value, @charset)
end

field= (field)

Source

# File lib/mail/field.rb, line 182
def field=(field)
  @field = field
end

field_order_id ()

Source

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

inspect ()

Source

# File lib/mail/field.rb, line 206
def inspect
  "#<#{self.class.name} 0x#{(object_id * 2).to_s(16)} #{instance_variables.map do |ivar|
    "#{ivar}=#{instance_variable_get(ivar).inspect}"
  end.join(" ")}>"
end

method_missing (name, *args, &block)

Source

# File lib/mail/field.rb, line 232
def method_missing(name, *args, &block)
  field.send(name, *args, &block)
end

name ()

Source

# File lib/mail/field.rb, line 190
def name
  @name
end

respond_to_missing? (method_name, include_private)

Source

# File lib/mail/field.rb, line 236
def respond_to_missing?(method_name, include_private)
  field.respond_to?(method_name, include_private) || super
end

Calls superclass method

responsible_for? (field_name)

Source

# File lib/mail/field.rb, line 220
def responsible_for?(field_name)
  name.to_s.casecmp(field_name.to_s) == 0
end

same (other)

Source

# File lib/mail/field.rb, line 212
def same(other)
  other.kind_of?(self.class) && Utilities.match_to_s(other.name, name)
end

to_s ()

Source

# File lib/mail/field.rb, line 202
def to_s
  field.to_s
end

value ()

Source

# File lib/mail/field.rb, line 194
def value
  field.value
end

value= (val)

Source

# File lib/mail/field.rb, line 198
def value=(val)
  @field = create_field(name, val, @charset)
end

Private Instance Methods

create_field (name, value, charset)

Source

# File lib/mail/field.rb, line 253
def create_field(name, value, charset)
  parse_field(name, value, charset)
rescue Mail::Field::ParseError => e
  field = Mail::UnstructuredField.new(name, value)
  field.errors << [name, value, e]
  field
end

parse_field (name, value, charset)

Source

# File lib/mail/field.rb, line 261
def parse_field(name, value, charset)
  value = unfold(value) if value.is_a?(String)

  if klass = self.class.field_class_for(name)
    klass.parse(value, charset)
  else
    OptionalField.parse(name, value, charset)
  end
end

unfold (string)

Source

# File lib/mail/field.rb, line 279
def unfold(string)
  string.gsub(Constants::UNFOLD_WS, '\1')
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.