Module: Mail::Utilities

Includes:
Constants
Included in:
Address, Encodings, Field, Header, Message, ParameterHash, ReceivedElement, StructuredField, UnstructuredField
Defined in:
lib/mail/utilities.rb

Constant Summary collapse

LF = 
"\n"
CRLF = 
"\r\n"
TO_CRLF_REGEX = 
if RUBY_VERSION >= '1.9'
  # This 1.9 only regex can save a reasonable amount of time (~20%)
  # by not matching "\r\n" so the string is returned unchanged in
  # the common case.
  Regexp.new("(?<!\r)\n|\r(?!\n)")
else
  /\n|\r\n|\r/
end

Constants included from Constants

Constants::ASTERISK, Constants::ATOM_UNSAFE, Constants::B_VALUES, Constants::CAPITAL_M, Constants::COLON, Constants::CONTROL_CHAR, Constants::CR, 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_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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.binary_unsafe_to_crlf(string) ⇒ Object

:nodoc:



268
269
270
 
# File 'lib/mail/utilities.rb', line 268

def self.binary_unsafe_to_crlf(string) #:nodoc:
  string.gsub(TO_CRLF_REGEX, CRLF)
end

.binary_unsafe_to_lf(string) ⇒ Object

:nodoc:



254
255
256
 
# File 'lib/mail/utilities.rb', line 254

def self.binary_unsafe_to_lf(string) #:nodoc:
  string.gsub(/\r\n|\r/, LF)
end

.blank?(value) ⇒ Boolean

Returns true if the object is considered blank. A blank includes things like ”, ‘ ’, nil, and arrays and hashes that have nothing in them.

This logic is mostly shared with ActiveSupport’s blank?

Returns:

  • (Boolean) 


314
315
316
317
318
319
320
321
322
 
# File 'lib/mail/utilities.rb', line 314

def self.blank?(value)
  if value.kind_of?(NilClass)
    true
  elsif value.kind_of?(String)
    value !~ /\S/
  else
    value.respond_to?(:empty?) ? value.empty? : !value
  end
end

.safe_for_line_ending_conversion?(string) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


273
274
275
 
# File 'lib/mail/utilities.rb', line 273

def self.safe_for_line_ending_conversion?(string) #:nodoc:
  string.ascii_only?
end

.to_crlf(string) ⇒ Object

Convert line endings to rn unless the string is binary. Used for encoding 8bit and base64 Content-Transfer-Encoding and for convenience when parsing emails with n line endings instead of the required rn.



300
301
302
303
304
305
306
307
 
# File 'lib/mail/utilities.rb', line 300

def self.to_crlf(string)
  string = string.to_s
  if safe_for_line_ending_conversion? string
    binary_unsafe_to_crlf string
  else
    string
  end
end

.to_lf(string) ⇒ Object

Convert line endings to n unless the string is binary. Used for sendmail delivery and for decoding 8bit Content-Transfer-Encoding.



288
289
290
291
292
293
294
295
 
# File 'lib/mail/utilities.rb', line 288

def self.to_lf(string)
  string = string.to_s
  if safe_for_line_ending_conversion? string
    binary_unsafe_to_lf string
  else
    string
  end
end

.unescape(str) ⇒ Object

Removes any -escaping.

Example:

string = 'This is \"a string\"'
unescape(string) #=> 'This is "a string"'

string = '"This is \"a string\""'
unescape(string) #=> '"This is "a string""'



103
104
105
 
# File 'lib/mail/utilities.rb', line 103

def unescape( str )
  str.gsub(/\\(.)/, '\1')
end

.unquote(str) ⇒ Object

Unwraps supplied string from inside double quotes and removes any -escaping.

Example:

string = '"This is a string"'
unquote(string) #=> 'This is a string'

string = '"This is \"a string\""'
unqoute(string) #=> 'This is "a string"'



85
86
87
88
89
90
91
 
# File 'lib/mail/utilities.rb', line 85

def unquote( str )
  if str =~ /^"(.*?)"$/
    unescape($1)
  else
    str
  end
end

Instance Method Details

#atom_safe?(str) ⇒ Boolean

Returns true if the string supplied is free from characters not allowed as an ATOM

Returns:

  • (Boolean) 


14
15
16
 
# File 'lib/mail/utilities.rb', line 14

def atom_safe?( str )
  not ATOM_UNSAFE === str
end

#bracket(str) ⇒ Object

Wraps a string in angle brackets and escapes any that are in the string itself

Example:

bracket( 'This is a string' ) #=> '<This is a string>'



133
134
135
 
# File 'lib/mail/utilities.rb', line 133

def bracket( str )
  RubyVer.bracket( str )
end

#capitalize_field(str) ⇒ Object

Capitalizes a string that is joined by hyphens correctly.

Example:

string = 'resent-from-field'
capitalize_field( string ) #=> 'Resent-From-Field'



187
188
189
 
# File 'lib/mail/utilities.rb', line 187

def capitalize_field( str )
  str.to_s.split("-").map { |v| v.capitalize }.join("-")
end

#constantize(str) ⇒ Object

Takes an underscored word and turns it into a class name

Example:

constantize("hello") #=> "Hello"
constantize("hello-there") #=> "HelloThere"
constantize("hello-there-mate") #=> "HelloThereMate"



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

def constantize( str )
  str.to_s.split(/[-_]/).map { |v| v.capitalize }.to_s
end

#dasherize(str) ⇒ Object

Swaps out all underscores (_) for hyphens (-) good for stringing from symbols a field name.

Example:

string = :resent_from_field
dasherize( string ) #=> 'resent-from-field'



209
210
211
 
# File 'lib/mail/utilities.rb', line 209

def dasherize( str )
  str.to_s.tr(UNDERSCORE, HYPHEN)
end

#dquote(str) ⇒ Object

Wraps supplied string in double quotes and applies -escaping as necessary, unless it is already wrapped.

Example:

string = 'This is a string'
dquote(string) #=> '"This is a string"'

string = 'This is "a string"'
dquote(string #=> '"This is \"a string\"'



71
72
73
 
# File 'lib/mail/utilities.rb', line 71

def dquote( str )
  '"' + unquote(str).gsub(/[\\"]/n) {|s| '\\' + s } + '"'
end

#escape_paren(str) ⇒ Object

Escape parenthesies in a string

Example:

str = 'This is (a) string'
escape_paren( str ) #=> 'This is \(a\) string'



154
155
156
 
# File 'lib/mail/utilities.rb', line 154

def escape_paren( str )
  RubyVer.escape_paren( str )
end

#map_lines(str, &block) ⇒ Object 



226
227
228
229
230
231
232
 
# File 'lib/mail/utilities.rb', line 226

def map_lines( str, &block )
  results = []
  str.each_line do |line|
    results << yield(line)
  end
  results
end

#map_with_index(enum, &block) ⇒ Object 



234
235
236
237
238
239
240
 
# File 'lib/mail/utilities.rb', line 234

def map_with_index( enum, &block )
  results = []
  enum.each_with_index do |token, i|
    results[i] = yield(token, i)
  end
  results
end

#match_to_s(obj1, obj2) ⇒ Object

Matches two objects with their to_s values case insensitively

Example:

obj2 = "This_is_An_object"
obj1 = :this_IS_an_object
match_to_s( obj1, obj2 ) #=> true



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

def match_to_s( obj1, obj2 )
  obj1.to_s.casecmp(obj2.to_s) == 0
end

#paren(str) ⇒ Object

Wraps a string in parenthesis and escapes any that are in the string itself.

Example:

paren( 'This is a string' ) #=> '(This is a string)'



113
114
115
 
# File 'lib/mail/utilities.rb', line 113

def paren( str )
  RubyVer.paren( str )
end

#quote_atom(str) ⇒ Object

If the string supplied has ATOM unsafe characters in it, will return the string quoted in double quotes, otherwise returns the string unmodified



20
21
22
 
# File 'lib/mail/utilities.rb', line 20

def quote_atom( str )
  atom_safe?( str ) ? str : dquote(str)
end

#quote_phrase(str) ⇒ Object

If the string supplied has PHRASE unsafe characters in it, will return the string quoted in double quotes, otherwise returns the string unmodified



26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/mail/utilities.rb', line 26

def quote_phrase( str )
  if str.respond_to?(:force_encoding)
    original_encoding = str.encoding
    ascii_str = str.to_s.dup.force_encoding('ASCII-8BIT')
    if (PHRASE_UNSAFE === ascii_str)
      dquote(ascii_str).force_encoding(original_encoding)
    else
      str
    end
  else
    (PHRASE_UNSAFE === str) ? dquote(str) : str
  end
end

#quote_token(str) ⇒ Object

If the string supplied has TOKEN unsafe characters in it, will return the string quoted in double quotes, otherwise returns the string unmodified



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/mail/utilities.rb', line 47

def quote_token( str )
  if str.respond_to?(:force_encoding)
    original_encoding = str.encoding
    ascii_str = str.to_s.dup.force_encoding('ASCII-8BIT')
    if token_safe?( ascii_str )
      str
    else
      dquote(ascii_str).force_encoding(original_encoding)
    end
  else
    token_safe?( str ) ? str : dquote(str)
  end
end

#token_safe?(str) ⇒ Boolean

Returns true if the string supplied is free from characters not allowed as a TOKEN

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/mail/utilities.rb', line 41

def token_safe?( str )
  not TOKEN_UNSAFE === str
end

#unbracket(str) ⇒ Object

Unwraps a string from being wrapped in parenthesis

Example:

str = '<This is a string>'
unbracket( str ) #=> 'This is a string'



143
144
145
146
 
# File 'lib/mail/utilities.rb', line 143

def unbracket( str )
  match = str.match(/^\<(.*?)\>$/)
  match ? match[1] : str
end

#underscoreize(str) ⇒ Object

Swaps out all hyphens (-) for underscores (_) good for stringing to symbols a field name.

Example:

string = :resent_from_field
underscoreize ( string ) #=> 'resent_from_field'



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

def underscoreize( str )
  str.to_s.downcase.tr(HYPHEN, UNDERSCORE)
end

#unparen(str) ⇒ Object

Unwraps a string from being wrapped in parenthesis

Example:

str = '(This is a string)'
unparen( str ) #=> 'This is a string'



123
124
125
126
 
# File 'lib/mail/utilities.rb', line 123

def unparen( str )
  match = str.match(/^\((.*?)\)$/)
  match ? match[1] : str
end

#uri_escape(str) ⇒ Object 



158
159
160
 
# File 'lib/mail/utilities.rb', line 158

def uri_escape( str )
  uri_parser.escape(str)
end

#uri_parser ⇒ Object 



166
167
168
 
# File 'lib/mail/utilities.rb', line 166

def uri_parser
  @uri_parser ||= URI.const_defined?(:Parser) ? URI::Parser.new : URI
end

#uri_unescape(str) ⇒ Object 



162
163
164
 
# File 'lib/mail/utilities.rb', line 162

def uri_unescape( str )
  uri_parser.unescape(str)
end