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:



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

def self.binary_unsafe_to_crlf(string) #:nodoc:
  string.encode(string.encoding, :universal_newline => true).encode!(string.encoding, :crlf_newline => true)
end

.binary_unsafe_to_lf(string) ⇒ Object

:nodoc:



251
252
253
 
# File 'lib/mail/utilities.rb', line 251

def self.binary_unsafe_to_lf(string) #:nodoc:
  string.encode(string.encoding, :universal_newline => true)
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) 


259
260
261
 
# File 'lib/mail/utilities.rb', line 259

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



93
94
95
 
# File 'lib/mail/utilities.rb', line 93

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



75
76
77
78
79
80
81
 
# File 'lib/mail/utilities.rb', line 75

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



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

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'



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

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"



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

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'



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

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\"'



61
62
63
 
# File 'lib/mail/utilities.rb', line 61

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'



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

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

#map_lines(str, &block) ⇒ Object 



216
217
218
219
220
221
222
 
# File 'lib/mail/utilities.rb', line 216

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

#map_with_index(enum, &block) ⇒ Object 



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

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



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

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



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

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 RUBY_VERSION >= '1.9'
    original_encoding = str.encoding
    ascii_str = str.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
 
# File 'lib/mail/utilities.rb', line 47

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



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

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'



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

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'



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

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

#uri_escape(str) ⇒ Object 



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

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

#uri_parser ⇒ Object 



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

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

#uri_unescape(str) ⇒ Object 



152
153
154
 
# File 'lib/mail/utilities.rb', line 152

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