Class: Mail::Field

Inherits:
Object
  • Object
show all
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, 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 =
Hash[FIELD_ORDER.each_with_index.to_a]

Constants included from Utilities

Utilities::CRLF, Utilities::CRLF_REGEX, Utilities::LF

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 Method Summary collapse

Methods included from Utilities

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

Constructor Details

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

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'}])


115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# File 'lib/mail/field.rb', line 115

def initialize(name, value = nil, charset = 'utf-8')
  case
  when name.index(COLON)            # Field.new("field-name: field data")
    @charset = Utilities.blank?(value) ? charset : value
    @name = name[FIELD_PREFIX]
    @raw_value = name
    @value = nil
  when Utilities.blank?(value)   # Field.new("field-name")
    @name = name
    @value = nil
    @raw_value = nil
    @charset = charset
  else                              # Field.new("field-name", "value")
    @name = name
    @value = value
    @raw_value = nil
    @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



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

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

Instance Method Details

#<=>(other) ⇒ Object



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

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

#==(other) ⇒ Object



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

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

#fieldObject



140
141
142
143
# File 'lib/mail/field.rb', line 140

def field
  _, @value = split(@raw_value) if @raw_value && !@value
  @field ||= create_field(@name, @value, @charset)
end

#field=(value) ⇒ Object



136
137
138
# File 'lib/mail/field.rb', line 136

def field=(value)
  @field = value
end

#field_order_idObject



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

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

#inspectObject



161
162
163
164
165
# File 'lib/mail/field.rb', line 161

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

#nameObject



145
146
147
# File 'lib/mail/field.rb', line 145

def name
  @name
end

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

Returns:

  • (Boolean)


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

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)


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

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

#responsible_for?(val) ⇒ Boolean

Returns:

  • (Boolean)


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

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

#same(other) ⇒ Object



171
172
173
174
# File 'lib/mail/field.rb', line 171

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

#to_sObject



157
158
159
# File 'lib/mail/field.rb', line 157

def to_s
  field.to_s
end

#update(name, value) ⇒ Object



167
168
169
# File 'lib/mail/field.rb', line 167

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

#valueObject



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

def value
  field.value
end

#value=(val) ⇒ Object



153
154
155
# File 'lib/mail/field.rb', line 153

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