Class: Mail::Field

Inherits:

Object

• Object
• Mail::Field

Includes:

Comparable, Utilities

Defined in:

lib/mail/field.rb

Overview

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.

Defined Under Namespace

Classes: FieldError, IncompleteParseError, NilParseError, ParseError, SyntaxError

Constant Summary

STRUCTURED_FIELDS =

%w[ bcc cc content-description content-disposition
content-id content-location content-transfer-encoding
content-type date from in-reply-to keywords message-id
mime-version received references reply-to
resent-bcc resent-cc resent-date resent-from
resent-message-id resent-sender resent-to
return-path sender to ]

KNOWN_FIELDS =

STRUCTURED_FIELDS + ['comments', 'subject']

FIELDS_MAP =

{
  "to" => ToField,
  "cc" => CcField,
  "bcc" => BccField,
  "message-id" => MessageIdField,
  "in-reply-to" => InReplyToField,
  "references" => ReferencesField,
  "subject" => SubjectField,
  "comments" => CommentsField,
  "keywords" => KeywordsField,
  "date" => DateField,
  "from" => FromField,
  "sender" => SenderField,
  "reply-to" => ReplyToField,
  "resent-date" => ResentDateField,
  "resent-from" => ResentFromField,
  "resent-sender" =>  ResentSenderField,
  "resent-to" => ResentToField,
  "resent-cc" => ResentCcField,
  "resent-bcc" => ResentBccField,
  "resent-message-id" => ResentMessageIdField,
  "return-path" => ReturnPathField,
  "received" => ReceivedField,
  "mime-version" => MimeVersionField,
  "content-transfer-encoding" => ContentTransferEncodingField,
  "content-description" => ContentDescriptionField,
  "content-disposition" => ContentDispositionField,
  "content-type" => ContentTypeField,
  "content-id" => ContentIdField,
  "content-location" => ContentLocationField,
}

FIELD_NAME_MAP =

FIELDS_MAP.inject({}) do |map, (field, field_klass)|
  map.update(field => field_klass::CAPITALIZED_FIELD)
end

FIELD_ORDER =

%w[ return-path received
resent-date resent-from resent-sender resent-to
resent-cc resent-bcc resent-message-id
date from sender reply-to to cc bcc
message-id in-reply-to references
subject comments keywords
mime-version content-type content-transfer-encoding
content-location content-disposition content-description ]

FIELD_ORDER_LOOKUP =

Constants included from Utilities

Utilities::CRLF, Utilities::LF, Utilities::TO_CRLF_REGEX

Constants included from Constants

Constants::ASTERISK, Constants::ATOM_UNSAFE, Constants::B_VALUES, Constants::CAPITAL_M, Constants::COLON, Constants::CONTROL_CHAR, Constants::CR, Constants::CRLF, Constants::CR_ENCODED, Constants::EMPTY, Constants::ENCODED_VALUE, Constants::EQUAL_LF, Constants::FIELD_BODY, Constants::FIELD_LINE, Constants::FIELD_NAME, Constants::FIELD_PREFIX, Constants::FIELD_SPLIT, Constants::FULL_ENCODED_VALUE, Constants::FWS, Constants::HEADER_LINE, Constants::HEADER_SPLIT, Constants::HYPHEN, Constants::LF, Constants::LF_ENCODED, Constants::NULL_SENDER, Constants::PHRASE_UNSAFE, Constants::QP_SAFE, Constants::QP_UNSAFE, Constants::Q_VALUES, Constants::SPACE, Constants::TEXT, Constants::TOKEN_UNSAFE, Constants::UNDERSCORE, Constants::WSP

Instance Attribute Summary

• #unparsed_value ⇒ Object readonly

  Returns the value of attribute unparsed_value.

Class Method Summary

• .parse(field, charset = nil) ⇒ Object

  Parse a field from a raw header line:.

• .split(raw_field) ⇒ Object

  :nodoc:.

Instance Method Summary

• #<=>(other) ⇒ Object
• #==(other) ⇒ Object
• #field ⇒ Object
• #field=(value) ⇒ Object
• #field_order_id ⇒ Object
• #initialize(name, value = nil, charset = 'utf-8') ⇒ Field constructor

  Create a field by name and optional value:.

• #inspect ⇒ Object
• #method_missing(name, *args, &block) ⇒ Object
• #name ⇒ Object
• #respond_to?(method_name, include_private = false) ⇒ Boolean
• #respond_to_missing?(method_name, include_private) ⇒ Boolean
• #responsible_for?(val) ⇒ Boolean
• #same(other) ⇒ Object
• #to_s ⇒ Object
• #update(name, value) ⇒ Object
• #value ⇒ Object
• #value=(val) ⇒ Object

Methods included from Utilities

#atom_safe?, binary_unsafe_to_crlf, binary_unsafe_to_lf, blank?, #bracket, #capitalize_field, #constantize, #dasherize, #dquote, #escape_paren, #map_lines, #map_with_index, #match_to_s, #paren, #quote_atom, #quote_phrase, #quote_token, safe_for_line_ending_conversion?, to_crlf, to_lf, #token_safe?, #unbracket, #underscoreize, unescape, #unparen, unquote, #uri_escape, #uri_parser, #uri_unescape

Constructor Details

#initialize(name, value = nil, charset = 'utf-8') ⇒ Field

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 …>

# File 'lib/mail/field.rb', line 164

def initialize(name, value = nil, charset = 'utf-8')
  case
  when name.index(COLON)
    Kernel.warn 'Passing an unparsed header field to Mail::Field.new is deprecated and will be removed in Mail 2.8.0. Use Mail::Field.parse instead.'
    @name, @unparsed_value = self.class.split(name)
    @charset = Utilities.blank?(value) ? charset : value
  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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &block) ⇒ Object

# File 'lib/mail/field.rb', line 238

def method_missing(name, *args, &block)
  field.send(name, *args, &block)
end

Instance Attribute Details

#unparsed_value ⇒ Object (readonly)

Returns the value of attribute unparsed_value.

# File 'lib/mail/field.rb', line 150

def unparsed_value
  @unparsed_value
end

Class Method Details

.parse(field, charset = nil) ⇒ Object

Parse a field from a raw header line:

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

# File 'lib/mail/field.rb', line 124

def parse(field, charset = nil)
  name, value = split(field)
  if name && value
    new name, value, charset
  end
end

.split(raw_field) ⇒ Object

:nodoc:

# File 'lib/mail/field.rb', line 131

def split(raw_field) #:nodoc:
  if raw_field.index(Constants::COLON)
    name, value = raw_field.split(Constants::COLON, 2)
    name.rstrip!
    if name =~ /\A#{Constants::FIELD_NAME}\z/
      [ name.rstrip, value.strip ]
    else
      Kernel.warn "WARNING: Ignoring unparsable header #{raw_field.inspect}: invalid header name syntax: #{name.inspect}"
      nil
    end
  else
    raw_field.strip
  end
rescue => error
  warn "WARNING: Ignoring unparsable header #{raw_field.inspect}: #{error.class}: #{error.message}"
  nil
end

Instance Method Details

#<=>(other) ⇒ Object

# File 'lib/mail/field.rb', line 230

def <=>( other )
  self.field_order_id <=> other.field_order_id
end

#==(other) ⇒ Object

# File 'lib/mail/field.rb', line 221

def ==( other )
  return false unless other.kind_of?(self.class)
  match_to_s(other.name, self.name) && match_to_s(other.value, self.value)
end

#field ⇒ Object

# File 'lib/mail/field.rb', line 186

def field
  @field ||= create_field(@name, @unparsed_value, @charset)
end

#field=(value) ⇒ Object

# File 'lib/mail/field.rb', line 182

def field=(value)
  @field = value
end

#field_order_id ⇒ Object

# File 'lib/mail/field.rb', line 234

def field_order_id
  @field_order_id ||= (FIELD_ORDER_LOOKUP[self.name.to_s.downcase] || 100)
end

#inspect ⇒ Object

# 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

#name ⇒ Object

# File 'lib/mail/field.rb', line 190

def name
  @name
end

#respond_to?(method_name, include_private = false) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/mail/field.rb', line 247

def respond_to?(method_name, include_private = false)
  field.respond_to?(method_name, include_private) || super
end

#respond_to_missing?(method_name, include_private) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/mail/field.rb', line 243

def respond_to_missing?(method_name, include_private)
  field.respond_to?(method_name, include_private) || super
end

#responsible_for?(val) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/mail/field.rb', line 226

def responsible_for?( val )
  name.to_s.casecmp(val.to_s) == 0
end

#same(other) ⇒ Object

# File 'lib/mail/field.rb', line 216

def same( other )
  return false unless other.kind_of?(self.class)
  match_to_s(other.name, self.name)
end

#to_s ⇒ Object

# File 'lib/mail/field.rb', line 202

def to_s
  field.to_s
end

#update(name, value) ⇒ Object

# File 'lib/mail/field.rb', line 212

def update(name, value)
  @field = create_field(name, value, @charset)
end

#value ⇒ Object

# File 'lib/mail/field.rb', line 194

def value
  field.value
end

#value=(val) ⇒ Object

# File 'lib/mail/field.rb', line 198

def value=(val)
  @field = create_field(name, val, @charset)
end