Mail::Encodings

Public Class Methods

address_encode(address, charset = 'utf-8') click to toggle source

     # File lib/mail/encodings.rb, line 172
172:     def Encodings.address_encode(address, charset = 'utf-8')
173:       if address.is_a?(Array)
174:         # loop back through for each element
175:         address.map { |a| Encodings.address_encode(a, charset) }.join(", ")
176:       else
177:         # find any word boundary that is not ascii and encode it
178:         encode_non_usascii(address, charset)
179:       end
180:     end

b_value_encode(str, encoding = nil) click to toggle source

Encode a string with Base64 Encoding and returns it ready to be inserted as a value for a field, that is, in the =??B??= format

Example:

 Encodings.b_value_encode('This is あ string', 'UTF-8') 
 #=> "=?UTF-8?B?VGhpcyBpcyDjgYIgc3RyaW5n?="

     # File lib/mail/encodings.rb, line 209
209:     def Encodings.b_value_encode(str, encoding = nil)
210:       return str if str.to_s.ascii_only?
211:       string, encoding = RubyVer.b_value_encode(str, encoding)
212:       map_lines(string) do |str|
213:         "=?#{encoding}?B?#{str.chomp}?="
214:       end.join(" ")
215:     end

decode_encode(str, output_type) click to toggle source

Decodes or encodes a string as needed for either Base64 or QP encoding types in the =??[QB]??=” format.

The output type needs to be :decode to decode the input string or :encode to encode the input string. The character set used for encoding will either be the value of $KCODE for Ruby < 1.9 or the encoding on the string passed in.

On encoding, will only send out Base64 encoded strings.

     # File lib/mail/encodings.rb, line 98
 98:     def Encodings.decode_encode(str, output_type)
 99:       case
100:       when output_type == :decode
101:         Encodings.value_decode(str)
102:       else
103:         if str.ascii_only?
104:           str
105:         else
106:           Encodings.b_value_encode(str, find_encoding(str))
107:         end
108:       end
109:     end

defined?( str ) click to toggle source

Is the encoding we want defined?

Example:

 Encodings.defined?(:base64) #=> true

    # File lib/mail/encodings.rb, line 29
29:     def Encodings.defined?( str )
30:       @transfer_encodings.include? get_name(str)
31:     end

encode_non_usascii(address, charset) click to toggle source

     # File lib/mail/encodings.rb, line 182
182:     def Encodings.encode_non_usascii(address, charset)
183:       return address if address.ascii_only?
184:       us_ascii = %{\x00-\x7f}
185:       # Encode any non usascii strings embedded inside of quotes
186:       address.gsub!(/(".*?[^#{us_ascii}].+?")/) { |s| Encodings.b_value_encode(unquote(s), charset) }
187:       # Then loop through all remaining items and encode as needed
188:       tokens = address.split(/\s/)
189:       map_with_index(tokens) do |word, i|
190:         if word.ascii_only?
191:           word
192:         else
193:           previous_non_ascii = tokens[i-1] && !tokens[i-1].ascii_only?
194:           if previous_non_ascii
195:             word = " #{word}"
196:           end
197:           Encodings.b_value_encode(word, charset)
198:         end
199:       end.join(' ')
200:     end

get_all() click to toggle source

    # File lib/mail/encodings.rb, line 45
45:     def Encodings.get_all
46:       @transfer_encodings.values
47:     end

get_encoding( str ) click to toggle source

Gets a defined encoding type, QuotedPrintable or Base64 for now.

Each encoding needs to be defined as a Mail::Encodings::ClassName for this to work, allows us to add other encodings in the future.

Example:

 Encodings.get_encoding(:base64) #=> Mail::Encodings::Base64

    # File lib/mail/encodings.rb, line 41
41:     def Encodings.get_encoding( str )
42:       @transfer_encodings[get_name(str)]
43:     end

get_name(enc) click to toggle source

    # File lib/mail/encodings.rb, line 49
49:     def Encodings.get_name(enc)
50:       enc = enc.to_s.gsub("-", "_").downcase
51:     end

param_decode(str, encoding) click to toggle source

Decodes a parameter value using URI Escaping.

Example:

 Mail::Encodings.param_decode("This%20is%20fun", 'us-ascii') #=> "This is fun"

 str = Mail::Encodings.param_decode("This%20is%20fun", 'iso-8559-1')
 str.encoding #=> 'ISO-8859-1'      ## Only on Ruby 1.9
 str #=> "This is fun"

    # File lib/mail/encodings.rb, line 86
86:     def Encodings.param_decode(str, encoding)
87:       RubyVer.param_decode(str, encoding)
88:     end

param_encode(str) click to toggle source

Encodes a parameter value using URI Escaping, note the language field ‘en’ can be set using Mail::Configuration, like so:

 Mail.defaults.do
   param_encode_language 'jp'
 end

The character set used for encoding will either be the value of $KCODE for Ruby < 1.9 or the encoding on the string passed in.

Example:

 Mail::Encodings.param_encode("This is fun") #=> "us-ascii'en'This%20is%20fun"

    # File lib/mail/encodings.rb, line 66
66:     def Encodings.param_encode(str)
67:       case
68:       when str.ascii_only? && str =~ TOKEN_UNSAFE
69:         %{"#{str}"}
70:       when str.ascii_only?
71:         str
72:       else
73:         RubyVer.param_encode(str)
74:       end
75:     end

q_value_encode(str, encoding = nil) click to toggle source

Encode a string with Quoted-Printable Encoding and returns it ready to be inserted as a value for a field, that is, in the =??Q??= format

Example:

 Encodings.q_value_encode('This is あ string', 'UTF-8') 
 #=> "=?UTF-8?Q?This_is_=E3=81=82_string?="

     # File lib/mail/encodings.rb, line 224
224:     def Encodings.q_value_encode(str, encoding = nil)
225:       return str if str.to_s.ascii_only?
226:       string, encoding = RubyVer.q_value_encode(str, encoding)
227:       string.gsub!("=\r\n", '') # We already have limited the string to the length we want
228:       map_lines(string) do |str|
229:         "=?#{encoding}?Q?#{str.chomp.gsub(/ /, '_')}?="
230:       end.join(" ")
231:     end

Example

Encodings.register “base64”, Mail::Encodings::Base64

    # File lib/mail/encodings.rb, line 20
20:     def Encodings.register(name, cls)
21:         @transfer_encodings[get_name(name)] = cls
22:     end

unquote_and_convert_to(str, to_encoding) click to toggle source

Takes an encoded string of the format =??[QB]??=

     # File lib/mail/encodings.rb, line 147
147:     def Encodings.unquote_and_convert_to(str, to_encoding)
148:       original_encoding, string = split_encoding_from_string( str )
149: 
150:       output = value_decode( str ).to_s
151: 
152:       if original_encoding.to_s.downcase.gsub("-", "") == to_encoding.to_s.downcase.gsub("-", "")
153:         output
154:       elsif original_encoding && to_encoding
155:         begin
156:           require 'iconv'
157:           Iconv.iconv(to_encoding, original_encoding, output).first
158:         rescue Iconv::IllegalSequence, Iconv::InvalidEncoding, Errno::EINVAL
159:           # the 'from' parameter specifies a charset other than what the text
160:           # actually is...not much we can do in this case but just return the
161:           # unconverted text.
162:           #
163:           # Ditto if either parameter represents an unknown charset, like
164:           # X-UNKNOWN.
165:           output
166:         end
167:       else
168:         output
169:       end
170:     end

value_decode(str) click to toggle source

Decodes a given string as Base64 or Quoted Printable, depending on what type it is.

String has to be of the format =??[QB]??=

     # File lib/mail/encodings.rb, line 115
115:     def Encodings.value_decode(str)
116:       # Optimization: If there's no encoded-words in the string, just return it
117:       return str unless str.index("=?")
118:       
119:       str = str.gsub(/\?=(\s*)=\?/, '?==?') # Remove whitespaces between 'encoded-word's
120: 
121:       # Split on white-space boundaries with capture, so we capture the white-space as well
122:       str.split(/([ \t])/).map do |text|
123:         if text.index('=?') != 0
124:           text
125:         else
126:           # Join QP encoded-words that are adjacent to avoid decoding partial chars
127:           text.gsub!(/\?\=\=\?.+?\?[Qq]\?/, '') if text =~ /\?==\?/
128:         
129:           # Separate encoded-words with a space, so we can treat them one by one
130:           text.gsub!(/\?\=\=\?/, '?= =?')
131: 
132:           text.split(/ /).map do |word|
133:             case 
134:             when word.to_str =~ /=\?.+\?[Bb]\?/
135:               b_value_decode(word)
136:             when text.to_str =~ /=\?.+\?[Qq]\?/
137:               q_value_decode(word)
138:             else
139:               word.to_str
140:             end
141:           end
142:         end
143:       end.join("")
144:     end

Private Class Methods

b_value_decode(str) click to toggle source

Decodes a Base64 string from the “=?UTF-8?B?VGhpcyBpcyDjgYIgc3RyaW5n?=” format

Example:

 Encodings.b_value_encode("=?UTF-8?B?VGhpcyBpcyDjgYIgc3RyaW5n?=") 
 #=> 'This is あ string'

     # File lib/mail/encodings.rb, line 241
241:     def Encodings.b_value_decode(str)
242:       RubyVer.b_value_decode(str)
243:     end

find_encoding(str) click to toggle source

     # File lib/mail/encodings.rb, line 264
264:     def Encodings.find_encoding(str)
265:       RUBY_VERSION >= '1.9' ? str.encoding : $KCODE
266:     end

q_value_decode(str) click to toggle source

Decodes a Quoted-Printable string from the “=?UTF-8?Q?This_is_=E3=81=82_string?=” format

Example:

 Encodings.b_value_encode("=?UTF-8?Q?This_is_=E3=81=82_string?=") 
 #=> 'This is あ string'

     # File lib/mail/encodings.rb, line 251
251:     def Encodings.q_value_decode(str)
252:       RubyVer.q_value_decode(str).gsub(/_/, ' ')
253:     end

split_encoding_from_string( str ) click to toggle source

     # File lib/mail/encodings.rb, line 255
255:     def Encodings.split_encoding_from_string( str )
256:       match = str.match(/\=\?([^?]+)?\?[QB]\?(.+)?\?\=/i)
257:       if match
258:         [match[1], match[2]]
259:       else
260:         nil
261:       end
262:     end

Home Classes Methods

In Files

Namespace

Methods

Included Modules

Files

Class Index

Mail::Encodings

Public Class Methods

Private Class Methods