module Mail::Utilities

Constants

CRLF
LF
TO_CRLF_REGEX

Public Class Methods

blank?(value) click to toggle source

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?

# 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
to_crlf(string) click to toggle source

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.

# 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) click to toggle source

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

# 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 ) click to toggle source

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""'
# File lib/mail/utilities.rb, line 103
def unescape( str )
  str.gsub(/\\(.)/, '\1')
end
unquote( str ) click to toggle source

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"'
# File lib/mail/utilities.rb, line 85
def unquote( str )
  if str =~ /^"(.*?)"$/
    unescape($1)
  else
    str
  end
end

Public Instance Methods

atom_safe?( str ) click to toggle source

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

# File lib/mail/utilities.rb, line 14
def atom_safe?( str )
  not ATOM_UNSAFE === str
end
bracket( str ) click to toggle source

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>'
# File lib/mail/utilities.rb, line 133
def bracket( str )
  RubyVer.bracket( str )
end
capitalize_field( str ) click to toggle source

Capitalizes a string that is joined by hyphens correctly.

Example:

string = 'resent-from-field'
capitalize_field( string ) #=> 'Resent-From-Field'
# File lib/mail/utilities.rb, line 187
def capitalize_field( str )
  str.to_s.split("-").map { |v| v.capitalize }.join("-")
end
constantize( str ) click to toggle source

Takes an underscored word and turns it into a class name

Example:

constantize("hello") #=> "Hello"
constantize("hello-there") #=> "HelloThere"
constantize("hello-there-mate") #=> "HelloThereMate"
# File lib/mail/utilities.rb, line 198
def constantize( str )
  str.to_s.split(/[-_]/).map { |v| v.capitalize }.to_s
end
dasherize( str ) click to toggle source

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

Example:

string = :resent_from_field
dasherize( string ) #=> 'resent-from-field'
# File lib/mail/utilities.rb, line 209
def dasherize( str )
  str.to_s.tr(UNDERSCORE, HYPHEN)
end
dquote( str ) click to toggle source

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\"'
# File lib/mail/utilities.rb, line 71
def dquote( str )
  '"' + unquote(str).gsub(/[\\"]/n) {|s| '\\' + s } + '"'
end
escape_paren( str ) click to toggle source

Escape parenthesies in a string

Example:

str = 'This is (a) string'
escape_paren( str ) #=> 'This is \(a\) string'
# File lib/mail/utilities.rb, line 154
def escape_paren( str )
  RubyVer.escape_paren( str )
end
map_lines( str ) { |line| ... } click to toggle source
# 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 ) { |token, i| ... } click to toggle source
# 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 ) click to toggle source

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
# File lib/mail/utilities.rb, line 177
def match_to_s( obj1, obj2 )
  obj1.to_s.casecmp(obj2.to_s) == 0
end
paren( str ) click to toggle source

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

Example:

paren( 'This is a string' ) #=> '(This is a string)'
# File lib/mail/utilities.rb, line 113
def paren( str )
  RubyVer.paren( str )
end
quote_atom( str ) click to toggle source

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

# File lib/mail/utilities.rb, line 20
def quote_atom( str )
  atom_safe?( str ) ? str : dquote(str)
end
quote_phrase( str ) click to toggle source

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

# 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 ) click to toggle source

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

# 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 ) click to toggle source

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

# File lib/mail/utilities.rb, line 41
def token_safe?( str )
  not TOKEN_UNSAFE === str
end
unbracket( str ) click to toggle source

Unwraps a string from being wrapped in parenthesis

Example:

str = '<This is a string>'
unbracket( str ) #=> 'This is a string'
# File lib/mail/utilities.rb, line 143
def unbracket( str )
  match = str.match(/^\<(.*?)\>$/)
  match ? match[1] : str
end
underscoreize( str ) click to toggle source

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

Example:

string = :resent_from_field
underscoreize ( string ) #=> 'resent_from_field'
# File lib/mail/utilities.rb, line 220
def underscoreize( str )
  str.to_s.downcase.tr(HYPHEN, UNDERSCORE)
end
unparen( str ) click to toggle source

Unwraps a string from being wrapped in parenthesis

Example:

str = '(This is a string)'
unparen( str ) #=> 'This is a string'
# File lib/mail/utilities.rb, line 123
def unparen( str )
  match = str.match(/^\((.*?)\)$/)
  match ? match[1] : str
end
uri_escape( str ) click to toggle source
# File lib/mail/utilities.rb, line 158
def uri_escape( str )
  uri_parser.escape(str)
end
uri_parser() click to toggle source
# File lib/mail/utilities.rb, line 166
def uri_parser
  @uri_parser ||= URI.const_defined?(:Parser) ? URI::Parser.new : URI
end
uri_unescape( str ) click to toggle source
# File lib/mail/utilities.rb, line 162
def uri_unescape( str )
  uri_parser.unescape(str)
end

Private Instance Methods

unescape( str ) click to toggle source

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""'
# File lib/mail/utilities.rb, line 103
def unescape( str )
  str.gsub(/\\(.)/, '\1')
end
unquote( str ) click to toggle source

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"'
# File lib/mail/utilities.rb, line 85
def unquote( str )
  if str =~ /^"(.*?)"$/
    unescape($1)
  else
    str
  end
end