Class: Mail::Field

Inherits:
Object
  • Object
show all
Includes:
Comparable
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 collapse

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::NAME)
end
FIELD_ORDER_LOOKUP = 
Hash[%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
].each_with_index.to_a]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/mail/field.rb', line 162

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

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


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

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


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

def unparsed_value
  @unparsed_value
end

Class Method Details

.parse(field, charset = 'utf-8') ⇒ Object

Parse a field from a raw header line:

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


122
123
124
125
126
127
 
# 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

.split(raw_field) ⇒ Object

:nodoc:


129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/mail/field.rb', line 129

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 


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

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

#==(other) ⇒ Object 


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

def ==(other)
  same(other) && Utilities.match_to_s(other.value, value)
end

#field ⇒ Object 


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

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

#field=(field) ⇒ Object 


178
179
180
 
# File 'lib/mail/field.rb', line 178

def field=(field)
  @field = field
end

#field_order_id ⇒ Object 


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

def field_order_id
  @field_order_id ||= FIELD_ORDER_LOOKUP.fetch(self.name.to_s.downcase, 100)
end

#inspect ⇒ Object 


202
203
204
205
206
 
# File 'lib/mail/field.rb', line 202

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 


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

def name
  @name
end

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

Returns:

  • (Boolean) 

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

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) 

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

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

#responsible_for?(field_name) ⇒ Boolean

Returns:

  • (Boolean) 

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

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

#same(other) ⇒ Object 


208
209
210
 
# File 'lib/mail/field.rb', line 208

def same(other)
  other.kind_of?(self.class) && Utilities.match_to_s(other.name, name)
end

#to_s ⇒ Object 


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

def to_s
  field.to_s
end

#value ⇒ Object 


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

def value
  field.value
end

#value=(val) ⇒ Object 


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

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