Module: Mail::Utilities

Constant Summary

LF =
"\n"
CRLF =
"\r\n"
CRLF_REGEX =

This 1.9 only regex can save a reasonable amount of time (~20%) by not matching “rn” so the string is returned unchanged in the common case.

/\n|\r\n|\r/

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

.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?



269
270
271
272
273
274
275
276
277
# File 'lib/mail/utilities.rb', line 269

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(input) ⇒ Object



239
240
241
# File 'lib/mail/utilities.rb', line 239

def self.to_crlf(input)
  input.kind_of?(String) ? input.to_str.encode(input.encoding, :universal_newline => true).encode!(input.encoding, :crlf_newline => true) : ''
end

.to_lf(input) ⇒ Object

Using String#encode is better performing than Regexp



235
236
237
# File 'lib/mail/utilities.rb', line 235

def self.to_lf(input)
  input.kind_of?(String) ? input.to_str.encode(input.encoding, :universal_newline => true) : ''
end

Instance Method Details

#atom_safe?(str) ⇒ Boolean

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



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

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


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

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'


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

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"


172
173
174
# File 'lib/mail/utilities.rb', line 172

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'


183
184
185
# File 'lib/mail/utilities.rb', line 183

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


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

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'


128
129
130
# File 'lib/mail/utilities.rb', line 128

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

#map_lines(str, &block) ⇒ Object



200
201
202
203
204
205
206
# File 'lib/mail/utilities.rb', line 200

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

#map_with_index(enum, &block) ⇒ Object



208
209
210
211
212
213
214
# File 'lib/mail/utilities.rb', line 208

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


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

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


87
88
89
# File 'lib/mail/utilities.rb', line 87

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
36
37
# File 'lib/mail/utilities.rb', line 23

def quote_phrase( str )
  if RUBY_VERSION >= '1.9'
    original_encoding = str.encoding
    str.force_encoding('ASCII-8BIT')
    if (PHRASE_UNSAFE === str)
      quoted_str = dquote(str).force_encoding(original_encoding)
      str.force_encoding(original_encoding)
      quoted_str
    else
      str.force_encoding(original_encoding)
    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



46
47
48
# File 'lib/mail/utilities.rb', line 46

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



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

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'


117
118
119
120
# File 'lib/mail/utilities.rb', line 117

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'


194
195
196
# File 'lib/mail/utilities.rb', line 194

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'


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

def unparen( str )
  match = str.match(/^\((.*?)\)$/)
  match ? match[1] : str
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"'


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

def unquote( str )
  if str =~ /^"(.*?)"$/
    $1.gsub(/\\(.)/, '\1')
  else
    str
  end
end

#uri_escape(str) ⇒ Object



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

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

#uri_parserObject



140
141
142
# File 'lib/mail/utilities.rb', line 140

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

#uri_unescape(str) ⇒ Object



136
137
138
# File 'lib/mail/utilities.rb', line 136

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