Module: Mail::Utilities

Includes:
Constants
Included in:
Address, Encodings, Field, Header, Message, ParameterHash, ReceivedElement, StructuredField, UnstructuredField
Defined in:
lib/mail/utilities.rb

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?

Returns:

  • (Boolean)


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

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



241
242
243
# File 'lib/mail/utilities.rb', line 241

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



237
238
239
# File 'lib/mail/utilities.rb', line 237

def self.to_lf(input)
  input.kind_of?(String) ? input.to_str.encode(input.encoding, :universal_newline => true) : ''
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 =~ /^"(.*?)"$/
    $1.gsub(/\\(.)/, '\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>'


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

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'


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

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"


174
175
176
# File 'lib/mail/utilities.rb', line 174

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'


185
186
187
# File 'lib/mail/utilities.rb', line 185

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'


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

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

#map_lines(str, &block) ⇒ Object



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

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

#map_with_index(enum, &block) ⇒ Object



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

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


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

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


89
90
91
# File 'lib/mail/utilities.rb', line 89

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'


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

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'


196
197
198
# File 'lib/mail/utilities.rb', line 196

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'


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

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

#uri_escape(str) ⇒ Object



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

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

#uri_parserObject



142
143
144
# File 'lib/mail/utilities.rb', line 142

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

#uri_unescape(str) ⇒ Object



138
139
140
# File 'lib/mail/utilities.rb', line 138

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