Module: Mail::Utilities

Extended by:
Utilities
Included in:
Encodings, Utilities
Defined in:
lib/mail/utilities.rb

Constant Summary collapse

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.binary_unsafe_to_crlf(string) ⇒ Object

:nodoc:


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

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

.binary_unsafe_to_lf(string) ⇒ Object

:nodoc:


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

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

.safe_for_line_ending_conversion?(string) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean)

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

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.


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

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.


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

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

Instance Method Details

#atom_safe?(str) ⇒ Boolean

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

Returns:

  • (Boolean)

11
12
13
# File 'lib/mail/utilities.rb', line 11

def atom_safe?( str )
  not Constants::ATOM_UNSAFE === str
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)

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

def 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

#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>'

131
132
133
# File 'lib/mail/utilities.rb', line 131

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'

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

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"

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

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'

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

def dasherize( str )
  str.to_s.tr(Constants::UNDERSCORE, Constants::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\"'

68
69
70
# File 'lib/mail/utilities.rb', line 68

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'

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

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

#generate_message_idObject


325
326
327
# File 'lib/mail/utilities.rb', line 325

def generate_message_id
  "<#{Mail.random_tag}@#{::Socket.gethostname}.mail>"
end

#map_lines(str, &block) ⇒ Object


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

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

#map_with_index(enum, &block) ⇒ Object


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

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

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

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

108
109
110
# File 'lib/mail/utilities.rb', line 108

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


17
18
19
# File 'lib/mail/utilities.rb', line 17

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


23
24
25
26
27
28
29
30
31
32
33
34
35
# File 'lib/mail/utilities.rb', line 23

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 Constants::PHRASE_UNSAFE === ascii_str
      dquote(ascii_str).force_encoding(original_encoding)
    else
      str
    end
  else
    Constants::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


44
45
46
47
48
49
50
51
52
53
54
55
56
# File 'lib/mail/utilities.rb', line 44

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)

38
39
40
# File 'lib/mail/utilities.rb', line 38

def token_safe?( str )
  not Constants::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'

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

def unbracket( str )
  if str.start_with?('<') && str.end_with?('>')
    str.slice(1..-2)
  else
    str
  end
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'

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

def underscoreize( str )
  str.to_s.downcase.tr(Constants::HYPHEN, Constants::UNDERSCORE)
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""'

99
100
101
# File 'lib/mail/utilities.rb', line 99

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

#unparen(str) ⇒ Object

Unwraps a string from being wrapped in parenthesis

Example:

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

118
119
120
121
122
123
124
# File 'lib/mail/utilities.rb', line 118

def unparen( str )
  if str.start_with?('(') && str.end_with?(')')
    str.slice(1..-2)
  else
    str
  end
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"'

82
83
84
85
86
87
88
# File 'lib/mail/utilities.rb', line 82

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

#uri_escape(str) ⇒ Object


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

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

#uri_parserObject


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

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

#uri_unescape(str) ⇒ Object


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

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