Included Modules

Class Index [+]

Quicksearch

Mail::Encodings

Public Class Methods

address_encode(address, charset = 'utf-8') click to toggle source
     # File lib/mail/encodings.rb, line 178
178:     def Encodings.address_encode(address, charset = 'utf-8')
179:       if address.is_a?(Array)
180:         # loop back through for each element
181:         address.map { |a| Encodings.address_encode(a, charset) }.join(", ")
182:       else
183:         # find any word boundary that is not ascii and encode it
184:         encode_non_usascii(address, charset)
185:       end
186:     end
b_value_encode(encoded_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 215
215:     def Encodings.b_value_encode(encoded_str, encoding = nil)
216:       return encoded_str if encoded_str.to_s.ascii_only?
217:       string, encoding = RubyVer.b_value_encode(encoded_str, encoding)
218:       map_lines(string) do |str|
219:         "=?#{encoding}?B?#{str.chomp}?="
220:       end.join(" ")
221:     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 188
188:     def Encodings.encode_non_usascii(address, charset)
189:       return address if address.ascii_only? or charset.nil?
190:       us_ascii = %{\x00-\x7f}
191:       # Encode any non usascii strings embedded inside of quotes
192:       address.gsub!(/(".*?[^#{us_ascii}].*?")/) { |s| Encodings.b_value_encode(unquote(s), charset) }
193:       # Then loop through all remaining items and encode as needed
194:       tokens = address.split(/\s/)
195:       map_with_index(tokens) do |word, i|
196:         if word.ascii_only?
197:           word
198:         else
199:           previous_non_ascii = tokens[i-1] && !tokens[i-1].ascii_only?
200:           if previous_non_ascii
201:             word = " #{word}"
202:           end
203:           Encodings.b_value_encode(word, charset)
204:         end
205:       end.join(' ')
206:     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(encoded_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 230
230:     def Encodings.q_value_encode(encoded_str, encoding = nil)
231:       return encoded_str if encoded_str.to_s.ascii_only?
232:       string, encoding = RubyVer.q_value_encode(encoded_str, encoding)
233:       string.gsub!("=\r\n", '') # We already have limited the string to the length we want
234:       map_lines(string) do |str|
235:         "=?#{encoding}?Q?#{str.chomp.gsub(/ /, '_')}?="
236:       end.join(" ")
237:     end
register(name, cls) click to toggle source

Register transfer encoding

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 149
149:     def Encodings.unquote_and_convert_to(str, to_encoding)
150:       original_encoding = split_encoding_from_string( str )
151: 
152:       output = value_decode( str ).to_s
153: 
154:       if original_encoding.to_s.downcase.gsub("-", "") == to_encoding.to_s.downcase.gsub("-", "")
155:         output
156:       elsif original_encoding && to_encoding
157:         begin
158:           if RUBY_VERSION >= '1.9'
159:             output.encode(to_encoding)
160:           else
161:             require 'iconv'
162:             Iconv.iconv(to_encoding, original_encoding, output).first
163:           end
164:         rescue Iconv::IllegalSequence, Iconv::InvalidEncoding, Errno::EINVAL
165:           # the 'from' parameter specifies a charset other than what the text
166:           # actually is...not much we can do in this case but just return the
167:           # unconverted text.
168:           #
169:           # Ditto if either parameter represents an unknown charset, like
170:           # X-UNKNOWN.
171:           output
172:         end
173:       else
174:         output
175:       end
176:     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('=?') .nil?
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:           # Search for occurences of quoted strings or plain strings
130:           text.scan(/(                                  # Group around entire regex to include it in matches
131:                        \=\?[^?]+\?([QB])\?[^?]+?\?\=  # Quoted String with subgroup for encoding method
132:                        |                                # or
133:                        .+?(?=\=\?|$)                    # Plain String
134:                      )/mi).map do |matches|
135:             string, method = *matches
136:             if    method == 'b' || method == 'B'
137:               b_value_decode(string)
138:             elsif method == 'q' || method == 'Q'
139:               q_value_decode(string)
140:             else
141:               string
142:             end
143:           end
144:         end
145:       end.join("")
146:     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_decode("=?UTF-8?B?VGhpcyBpcyDjgYIgc3RyaW5n?=")
 #=> 'This is あ string'
     # File lib/mail/encodings.rb, line 247
247:     def Encodings.b_value_decode(str)
248:       RubyVer.b_value_decode(str)
249:     end
find_encoding(str) click to toggle source
     # File lib/mail/encodings.rb, line 270
270:     def Encodings.find_encoding(str)
271:       RUBY_VERSION >= '1.9' ? str.encoding : $KCODE
272:     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.q_value_decode("=?UTF-8?Q?This_is_=E3=81=82_string?=")
 #=> 'This is あ string'
     # File lib/mail/encodings.rb, line 257
257:     def Encodings.q_value_decode(str)
258:       RubyVer.q_value_decode(str)
259:     end
split_encoding_from_string( str ) click to toggle source
     # File lib/mail/encodings.rb, line 261
261:     def Encodings.split_encoding_from_string( str )
262:       match = str.match(/\=\?([^?]+)?\?[QB]\?(.+)?\?\=/i)
263:       if match
264:         match[1]
265:       else
266:         nil
267:       end
268:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.