module Mail::Utilities

def atom_safe?( str )

Returns true if the string supplied is free from characters not allowed as an ATOM 
def atom_safe?( str )
  not ATOM_UNSAFE === str
end

def bracket( str )

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

Example:

Wraps a string in angle brackets and escapes any that are in the string itself 
def bracket( str )
  RubyVer.bracket( str )
end

def capitalize_field( str )

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

Example:

Capitalizes a string that is joined by hyphens correctly. 
def capitalize_field( str )
  str.to_s.split("-").map { |v| v.capitalize }.join("-")
end

def constantize( str )

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

Example:

Takes an underscored word and turns it into a class name 
def constantize( str )
  str.to_s.split(/[-_]/).map { |v| v.capitalize }.to_s
end

def dasherize( str )

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

Example:

a field name.
Swaps out all underscores (_) for hyphens (-) good for stringing from symbols 
def dasherize( str )
  str.to_s.gsub('_', '-')
end

def dquote( str )

backslash in front of the '"' character.
Additionally will escape any double quotation marks in the string with a single

Wraps supplied string in double quotes unless it is already wrapped. 
def dquote( str )
  match = str.match(/^"(.*)?"$/)
  str = match[1] if match
  # First remove all escaped double quotes:
  str = str.gsub(/\\"/, '"')
  # Then wrap and re-escape all double quotes
  '"' + str.gsub(/["]/n) {|s| '\\' + s } + '"'
end

def escape_paren( str )

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

Example:

Escape parenthesies in a string 
def escape_paren( str )
  RubyVer.escape_paren( str )
end

def map_lines( str, &block ) 

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

def map_lines( str, &block ) 

def map_lines( str, &block )
  str.each_line.map(&block)
end

def map_with_index( enum, &block ) 

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

def map_with_index( enum, &block ) 

def map_with_index( enum, &block )
  enum.each_with_index.map(&block)
end

def match_to_s( obj1, obj2 )

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

Example:

Matches two objects with their to_s values case insensitively 
def match_to_s( obj1, obj2 )
  obj1.to_s.downcase == obj2.to_s.downcase
end

def paren( str )

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

Example:

Wraps a string in parenthesis and escapes any that are in the string itself. 
def paren( str )
  RubyVer.paren( str )
end

def quote_atom( str )

in double quotes, otherwise returns the string unmodified
If the string supplied has ATOM unsafe characters in it, will return the string quoted 
def quote_atom( str )
  atom_safe?( str ) ? str : dquote(str)
end

def quote_phrase( str )

in double quotes, otherwise returns the string unmodified
If the string supplied has PHRASE unsafe characters in it, will return the string quoted 
def quote_phrase( str )
  if RUBY_VERSION >= '1.9'
    original_encoding = str.encoding
    str.force_encoding('ASCII-8BIT')
    if (PHRASE_UNSAFE === str)
      dquote(str).force_encoding(original_encoding)
    else
      str.force_encoding(original_encoding)
    end
  else
    (PHRASE_UNSAFE === str) ? dquote(str) : str
  end
end

def quote_token( str )

in double quotes, otherwise returns the string unmodified
If the string supplied has TOKEN unsafe characters in it, will return the string quoted 
def quote_token( str )
  token_safe?( str ) ? str : dquote(str)
end

def token_safe?( str )

Returns true if the string supplied is free from characters not allowed as a TOKEN 
def token_safe?( str )
  not TOKEN_UNSAFE === str
end

def unbracket( str )

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

Example:

Unwraps a string from being wrapped in parenthesis 
def unbracket( str )
  match = str.match(/^\<(.*?)\>$/)
  match ? match[1] : str
end

def underscoreize( str )

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

Example:

a field name.
Swaps out all hyphens (-) for underscores (_) good for stringing to symbols 
def underscoreize( str )
  str.to_s.downcase.gsub('-', '_')
end

def unparen( str )

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

Example:

Unwraps a string from being wrapped in parenthesis 
def unparen( str )
  match = str.match(/^\((.*?)\)$/)
  match ? match[1] : str
end

def unquote( str )

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

Example:

Unwraps supplied string from inside double quotes. 
def unquote( str )
  match = str.match(/^"(.*?)"$/)
  match ? match[1] : str
end

def uri_escape( str ) 

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

def uri_parser 

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

def uri_unescape( str ) 

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