← Back to branch summary

~michaelforrest/use-case-mapper/trunk

« back to all changes in this revision

Viewing changes to vendor/rails/actionmailer/lib/action_mailer/vendor/tmail-1.2.3/tmail/interface.rb

  • Committer: Michael Forrest
  • Date: 2010-10-15 16:28:50 UTC
  • Revision ID: michael.forrest@canonical.com-20101015162850-tj2vchanv0kr0dun
refroze gems

Show diffs side-by-side

added added

removed removed

Lines of Context:
vendor/rails/actionmailer/lib/action_mailer/vendor/tmail-1.2.3/tmail/interface.rb
 
1
=begin rdoc
 
2
 
 
3
= interface.rb Provides an interface to the TMail object
 
4
 
 
5
=end
 
6
#--
 
7
# Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 
8
#
 
9
# Permission is hereby granted, free of charge, to any person obtaining
 
10
# a copy of this software and associated documentation files (the
 
11
# "Software"), to deal in the Software without restriction, including
 
12
# without limitation the rights to use, copy, modify, merge, publish,
 
13
# distribute, sublicense, and/or sell copies of the Software, and to
 
14
# permit persons to whom the Software is furnished to do so, subject to
 
15
# the following conditions:
 
16
#
 
17
# The above copyright notice and this permission notice shall be
 
18
# included in all copies or substantial portions of the Software.
 
19
#
 
20
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 
21
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 
22
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 
23
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 
24
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 
25
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 
26
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
27
#
 
28
# Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 
29
# with permission of Minero Aoki.
 
30
#++
 
31
 
 
32
# TMail::Mail objects get accessed primarily through the methods in this file.
 
33
# 
 
34
# 
 
35
 
 
36
require 'tmail/utils'
 
37
 
 
38
module TMail
 
39
 
 
40
  class Mail
 
41
 
 
42
    # Allows you to query the mail object with a string to get the contents
 
43
    # of the field you want.
 
44
    # 
 
45
    # Returns a string of the exact contents of the field
 
46
    # 
 
47
    #  mail.from = "mikel <mikel@lindsaar.net>"
 
48
    #  mail.header_string("From") #=> "mikel <mikel@lindsaar.net>"
 
49
    def header_string( name, default = nil )
 
50
      h = @header[name.downcase] or return default
 
51
      h.to_s
 
52
    end
 
53
 
 
54
    #:stopdoc:
 
55
    #--
 
56
    #== Attributes
 
57
 
 
58
    include TextUtils
 
59
 
 
60
    def set_string_array_attr( key, strs )
 
61
      strs.flatten!
 
62
      if strs.empty?
 
63
        @header.delete key.downcase
 
64
      else
 
65
        store key, strs.join(', ')
 
66
      end
 
67
      strs
 
68
    end
 
69
    private :set_string_array_attr
 
70
 
 
71
    def set_string_attr( key, str )
 
72
      if str
 
73
        store key, str
 
74
      else
 
75
        @header.delete key.downcase
 
76
      end
 
77
      str
 
78
    end
 
79
    private :set_string_attr
 
80
 
 
81
    def set_addrfield( name, arg )
 
82
      if arg
 
83
        h = HeaderField.internal_new(name, @config)
 
84
        h.addrs.replace [arg].flatten
 
85
        @header[name] = h
 
86
      else
 
87
        @header.delete name
 
88
      end
 
89
      arg
 
90
    end
 
91
    private :set_addrfield
 
92
 
 
93
    def addrs2specs( addrs )
 
94
      return nil unless addrs
 
95
      list = addrs.map {|addr|
 
96
          if addr.address_group?
 
97
          then addr.map {|a| a.spec }
 
98
          else addr.spec
 
99
          end
 
100
      }.flatten
 
101
      return nil if list.empty?
 
102
      list
 
103
    end
 
104
    private :addrs2specs
 
105
 
 
106
    #:startdoc:
 
107
 
 
108
    #== Date and Time methods
 
109
 
 
110
    # Returns the date of the email message as per the "date" header value or returns
 
111
    # nil by default (if no date field exists).  
 
112
    # 
 
113
    # You can also pass whatever default you want into this method and it will return 
 
114
    # that instead of nil if there is no date already set. 
 
115
    def date( default = nil )
 
116
      if h = @header['date']
 
117
        h.date
 
118
      else
 
119
        default
 
120
      end
 
121
    end
 
122
 
 
123
    # Destructively sets the date of the mail object with the passed Time instance,
 
124
    # returns a Time instance set to the date/time of the mail
 
125
    # 
 
126
    # Example:
 
127
    # 
 
128
    #  now = Time.now
 
129
    #  mail.date = now
 
130
    #  mail.date #=> Sat Nov 03 18:47:50 +1100 2007
 
131
    #  mail.date.class #=> Time
 
132
    def date=( time )
 
133
      if time
 
134
        store 'Date', time2str(time)
 
135
      else
 
136
        @header.delete 'date'
 
137
      end
 
138
      time
 
139
    end
 
140
 
 
141
    # Returns the time of the mail message formatted to your taste using a 
 
142
    # strftime format string.  If no date set returns nil by default or whatever value
 
143
    # you pass as the second optional parameter.
 
144
    # 
 
145
    #  time = Time.now # (on Nov 16 2007)
 
146
    #  mail.date = time
 
147
    #  mail.strftime("%D") #=> "11/16/07"
 
148
    def strftime( fmt, default = nil )
 
149
      if t = date
 
150
        t.strftime(fmt)
 
151
      else
 
152
        default
 
153
      end
 
154
    end
 
155
 
 
156
    #== Destination methods
 
157
 
 
158
    # Return a TMail::Addresses instance for each entry in the "To:" field of the mail object header.
 
159
    # 
 
160
    # If the "To:" field does not exist, will return nil by default or the value you
 
161
    # pass as the optional parameter.
 
162
    # 
 
163
    # Example:
 
164
    # 
 
165
    #  mail = TMail::Mail.new
 
166
    #  mail.to_addrs #=> nil
 
167
    #  mail.to_addrs([]) #=> []
 
168
    #  mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
169
    #  mail.to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
170
    def to_addrs( default = nil )
 
171
      if h = @header['to']
 
172
        h.addrs
 
173
      else
 
174
        default
 
175
      end
 
176
    end
 
177
 
 
178
    # Return a TMail::Addresses instance for each entry in the "Cc:" field of the mail object header.
 
179
    # 
 
180
    # If the "Cc:" field does not exist, will return nil by default or the value you
 
181
    # pass as the optional parameter.
 
182
    # 
 
183
    # Example:
 
184
    # 
 
185
    #  mail = TMail::Mail.new
 
186
    #  mail.cc_addrs #=> nil
 
187
    #  mail.cc_addrs([]) #=> []
 
188
    #  mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
189
    #  mail.cc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
190
     def cc_addrs( default = nil )
 
191
      if h = @header['cc']
 
192
        h.addrs
 
193
      else
 
194
        default
 
195
      end
 
196
    end
 
197
 
 
198
    # Return a TMail::Addresses instance for each entry in the "Bcc:" field of the mail object header.
 
199
    # 
 
200
    # If the "Bcc:" field does not exist, will return nil by default or the value you
 
201
    # pass as the optional parameter.
 
202
    # 
 
203
    # Example:
 
204
    # 
 
205
    #  mail = TMail::Mail.new
 
206
    #  mail.bcc_addrs #=> nil
 
207
    #  mail.bcc_addrs([]) #=> []
 
208
    #  mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
209
    #  mail.bcc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
210
    def bcc_addrs( default = nil )
 
211
      if h = @header['bcc']
 
212
        h.addrs
 
213
      else
 
214
        default
 
215
      end
 
216
    end
 
217
 
 
218
    # Destructively set the to field of the "To:" header to equal the passed in string.
 
219
    # 
 
220
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
221
    # object before assigning it to the mail message.
 
222
    #
 
223
    # Example:
 
224
    # 
 
225
    #  mail = TMail::Mail.new
 
226
    #  mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
227
    #  mail.to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
228
    def to_addrs=( arg )
 
229
      set_addrfield 'to', arg
 
230
    end
 
231
 
 
232
    # Destructively set the to field of the "Cc:" header to equal the passed in string.
 
233
    # 
 
234
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
235
    # object before assigning it to the mail message.
 
236
    #
 
237
    # Example:
 
238
    # 
 
239
    #  mail = TMail::Mail.new
 
240
    #  mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
241
    #  mail.cc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
242
    def cc_addrs=( arg )
 
243
      set_addrfield 'cc', arg
 
244
    end
 
245
 
 
246
    # Destructively set the to field of the "Bcc:" header to equal the passed in string.
 
247
    # 
 
248
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
249
    # object before assigning it to the mail message.
 
250
    #
 
251
    # Example:
 
252
    # 
 
253
    #  mail = TMail::Mail.new
 
254
    #  mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
255
    #  mail.bcc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
256
    def bcc_addrs=( arg )
 
257
      set_addrfield 'bcc', arg
 
258
    end
 
259
 
 
260
    # Returns who the email is to as an Array of email addresses as opposed to an Array of 
 
261
    # TMail::Address objects which is what Mail#to_addrs returns
 
262
    # 
 
263
    # Example:
 
264
    # 
 
265
    #  mail = TMail::Mail.new
 
266
    #  mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
267
    #  mail.to #=>  ["mikel@me.org", "mikel@you.org"]
 
268
    def to( default = nil )
 
269
      addrs2specs(to_addrs(nil)) || default
 
270
    end
 
271
 
 
272
    # Returns who the email cc'd as an Array of email addresses as opposed to an Array of 
 
273
    # TMail::Address objects which is what Mail#to_addrs returns
 
274
    # 
 
275
    # Example:
 
276
    # 
 
277
    #  mail = TMail::Mail.new
 
278
    #  mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
279
    #  mail.cc #=>  ["mikel@me.org", "mikel@you.org"]
 
280
    def cc( default = nil )
 
281
      addrs2specs(cc_addrs(nil)) || default
 
282
    end
 
283
 
 
284
    # Returns who the email bcc'd as an Array of email addresses as opposed to an Array of 
 
285
    # TMail::Address objects which is what Mail#to_addrs returns
 
286
    # 
 
287
    # Example:
 
288
    # 
 
289
    #  mail = TMail::Mail.new
 
290
    #  mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
291
    #  mail.bcc #=>  ["mikel@me.org", "mikel@you.org"]
 
292
    def bcc( default = nil )
 
293
      addrs2specs(bcc_addrs(nil)) || default
 
294
    end
 
295
 
 
296
    # Destructively sets the "To:" field to the passed array of strings (which should be valid 
 
297
    # email addresses)
 
298
    # 
 
299
    # Example:
 
300
    # 
 
301
    #  mail = TMail::Mail.new
 
302
    #  mail.to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
 
303
    #  mail.to #=>  ["mikel@abc.org", "mikel@xyz.org"]
 
304
    #  mail['to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
 
305
    def to=( *strs )
 
306
      set_string_array_attr 'To', strs
 
307
    end
 
308
 
 
309
    # Destructively sets the "Cc:" field to the passed array of strings (which should be valid 
 
310
    # email addresses)
 
311
    # 
 
312
    # Example:
 
313
    # 
 
314
    #  mail = TMail::Mail.new
 
315
    #  mail.cc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
 
316
    #  mail.cc #=>  ["mikel@abc.org", "mikel@xyz.org"]
 
317
    #  mail['cc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
 
318
    def cc=( *strs )
 
319
      set_string_array_attr 'Cc', strs
 
320
    end
 
321
 
 
322
    # Destructively sets the "Bcc:" field to the passed array of strings (which should be valid 
 
323
    # email addresses)
 
324
    # 
 
325
    # Example:
 
326
    # 
 
327
    #  mail = TMail::Mail.new
 
328
    #  mail.bcc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
 
329
    #  mail.bcc #=>  ["mikel@abc.org", "mikel@xyz.org"]
 
330
    #  mail['bcc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
 
331
    def bcc=( *strs )
 
332
      set_string_array_attr 'Bcc', strs
 
333
    end
 
334
 
 
335
    #== Originator methods
 
336
 
 
337
    # Return a TMail::Addresses instance for each entry in the "From:" field of the mail object header.
 
338
    # 
 
339
    # If the "From:" field does not exist, will return nil by default or the value you
 
340
    # pass as the optional parameter.
 
341
    # 
 
342
    # Example:
 
343
    # 
 
344
    #  mail = TMail::Mail.new
 
345
    #  mail.from_addrs #=> nil
 
346
    #  mail.from_addrs([]) #=> []
 
347
    #  mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
348
    #  mail.from_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
349
    def from_addrs( default = nil )
 
350
      if h = @header['from']
 
351
        h.addrs
 
352
      else
 
353
        default
 
354
      end
 
355
    end
 
356
 
 
357
    # Destructively set the to value of the "From:" header to equal the passed in string.
 
358
    # 
 
359
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
360
    # object before assigning it to the mail message.
 
361
    #
 
362
    # Example:
 
363
    # 
 
364
    #  mail = TMail::Mail.new
 
365
    #  mail.from_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
366
    #  mail.from_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
367
    def from_addrs=( arg )
 
368
      set_addrfield 'from', arg
 
369
    end
 
370
 
 
371
    # Returns who the email is from as an Array of email address strings instead to an Array of 
 
372
    # TMail::Address objects which is what Mail#from_addrs returns
 
373
    # 
 
374
    # Example:
 
375
    # 
 
376
    #  mail = TMail::Mail.new
 
377
    #  mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
378
    #  mail.from #=>  ["mikel@me.org", "mikel@you.org"]
 
379
    def from( default = nil )
 
380
      addrs2specs(from_addrs(nil)) || default
 
381
    end
 
382
 
 
383
    # Destructively sets the "From:" field to the passed array of strings (which should be valid 
 
384
    # email addresses)
 
385
    # 
 
386
    # Example:
 
387
    # 
 
388
    #  mail = TMail::Mail.new
 
389
    #  mail.from = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
 
390
    #  mail.from #=>  ["mikel@abc.org", "mikel@xyz.org"]
 
391
    #  mail['from'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
 
392
    def from=( *strs )
 
393
      set_string_array_attr 'From', strs
 
394
    end
 
395
 
 
396
    # Returns the "friendly" human readable part of the address
 
397
    # 
 
398
    # Example:
 
399
    # 
 
400
    #  mail = TMail::Mail.new
 
401
    #  mail.from = "Mikel Lindsaar <mikel@abc.com>"
 
402
    #  mail.friendly_from #=> "Mikel Lindsaar"
 
403
    def friendly_from( default = nil )
 
404
      h = @header['from']
 
405
      a, = h.addrs
 
406
      return default unless a
 
407
      return a.phrase if a.phrase
 
408
      return h.comments.join(' ') unless h.comments.empty?
 
409
      a.spec
 
410
    end
 
411
 
 
412
    # Return a TMail::Addresses instance for each entry in the "Reply-To:" field of the mail object header.
 
413
    # 
 
414
    # If the "Reply-To:" field does not exist, will return nil by default or the value you
 
415
    # pass as the optional parameter.
 
416
    # 
 
417
    # Example:
 
418
    # 
 
419
    #  mail = TMail::Mail.new
 
420
    #  mail.reply_to_addrs #=> nil
 
421
    #  mail.reply_to_addrs([]) #=> []
 
422
    #  mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
423
    #  mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
424
    def reply_to_addrs( default = nil )
 
425
      if h = @header['reply-to']
 
426
        h.addrs.blank? ? default : h.addrs
 
427
      else
 
428
        default
 
429
      end
 
430
    end
 
431
 
 
432
    # Destructively set the to value of the "Reply-To:" header to equal the passed in argument.
 
433
    # 
 
434
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
435
    # object before assigning it to the mail message.
 
436
    #
 
437
    # Example:
 
438
    # 
 
439
    #  mail = TMail::Mail.new
 
440
    #  mail.reply_to_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
441
    #  mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
442
    def reply_to_addrs=( arg )
 
443
      set_addrfield 'reply-to', arg
 
444
    end
 
445
 
 
446
    # Returns who the email is from as an Array of email address strings instead to an Array of 
 
447
    # TMail::Address objects which is what Mail#reply_to_addrs returns
 
448
    # 
 
449
    # Example:
 
450
    # 
 
451
    #  mail = TMail::Mail.new
 
452
    #  mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
453
    #  mail.reply_to #=>  ["mikel@me.org", "mikel@you.org"]
 
454
    def reply_to( default = nil )
 
455
      addrs2specs(reply_to_addrs(nil)) || default
 
456
    end
 
457
 
 
458
    # Destructively sets the "Reply-To:" field to the passed array of strings (which should be valid 
 
459
    # email addresses)
 
460
    # 
 
461
    # Example:
 
462
    # 
 
463
    #  mail = TMail::Mail.new
 
464
    #  mail.reply_to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
 
465
    #  mail.reply_to #=>  ["mikel@abc.org", "mikel@xyz.org"]
 
466
    #  mail['reply_to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
 
467
    def reply_to=( *strs )
 
468
      set_string_array_attr 'Reply-To', strs
 
469
    end
 
470
 
 
471
    # Return a TMail::Addresses instance of the "Sender:" field of the mail object header.
 
472
    # 
 
473
    # If the "Sender:" field does not exist, will return nil by default or the value you
 
474
    # pass as the optional parameter.
 
475
    # 
 
476
    # Example:
 
477
    # 
 
478
    #  mail = TMail::Mail.new
 
479
    #  mail.sender #=> nil
 
480
    #  mail.sender([]) #=> []
 
481
    #  mail.sender = "Mikel <mikel@me.org>"
 
482
    #  mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>]
 
483
    def sender_addr( default = nil )
 
484
      f = @header['sender'] or return default
 
485
      f.addr                or return default
 
486
    end
 
487
 
 
488
    # Destructively set the to value of the "Sender:" header to equal the passed in argument.
 
489
    # 
 
490
    # TMail will parse your contents and turn each valid email address into a TMail::Address 
 
491
    # object before assigning it to the mail message.
 
492
    #
 
493
    # Example:
 
494
    # 
 
495
    #  mail = TMail::Mail.new
 
496
    #  mail.sender_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
 
497
    #  mail.sender_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
 
498
    def sender_addr=( addr )
 
499
      if addr
 
500
        h = HeaderField.internal_new('sender', @config)
 
501
        h.addr = addr
 
502
        @header['sender'] = h
 
503
      else
 
504
        @header.delete 'sender'
 
505
      end
 
506
      addr
 
507
    end
 
508
 
 
509
    # Returns who the sender of this mail is as string instead to an Array of 
 
510
    # TMail::Address objects which is what Mail#sender_addr returns
 
511
    # 
 
512
    # Example:
 
513
    # 
 
514
    #  mail = TMail::Mail.new
 
515
    #  mail.sender = "Mikel <mikel@me.org>"
 
516
    #  mail.sender #=>  "mikel@me.org"
 
517
    def sender( default = nil )
 
518
      f = @header['sender'] or return default
 
519
      a = f.addr            or return default
 
520
      a.spec
 
521
    end
 
522
 
 
523
    # Destructively sets the "Sender:" field to the passed string (which should be a valid 
 
524
    # email address)
 
525
    # 
 
526
    # Example:
 
527
    # 
 
528
    #  mail = TMail::Mail.new
 
529
    #  mail.sender = "mikel@abc.com"
 
530
    #  mail.sender #=>  "mikel@abc.org"
 
531
    #  mail['sender'].to_s #=> "mikel@abc.com"
 
532
    def sender=( str )
 
533
      set_string_attr 'Sender', str
 
534
    end
 
535
 
 
536
    #== Subject methods
 
537
 
 
538
    # Returns the subject of the mail instance.
 
539
    # 
 
540
    # If the subject field does not exist, returns nil by default or you can pass in as
 
541
    # the parameter for what you want the default value to be.
 
542
    # 
 
543
    # Example:
 
544
    # 
 
545
    #  mail = TMail::Mail.new
 
546
    #  mail.subject #=> nil
 
547
    #  mail.subject("") #=> ""
 
548
    #  mail.subject = "Hello"
 
549
    #  mail.subject #=> "Hello"
 
550
    def subject( default = nil )
 
551
      if h = @header['subject']
 
552
        h.body
 
553
      else
 
554
        default
 
555
      end
 
556
    end
 
557
    alias quoted_subject subject
 
558
 
 
559
    # Destructively sets the passed string as the subject of the mail message.
 
560
    # 
 
561
    # Example
 
562
    # 
 
563
    #  mail = TMail::Mail.new
 
564
    #  mail.subject #=> "This subject"
 
565
    #  mail.subject = "Another subject"
 
566
    #  mail.subject #=> "Another subject"
 
567
    def subject=( str )
 
568
      set_string_attr 'Subject', str
 
569
    end
 
570
 
 
571
    #== Message Identity & Threading Methods
 
572
    
 
573
    # Returns the message ID for this mail object instance.
 
574
    # 
 
575
    # If the message_id field does not exist, returns nil by default or you can pass in as
 
576
    # the parameter for what you want the default value to be.
 
577
    # 
 
578
    # Example:
 
579
    # 
 
580
    #  mail = TMail::Mail.new
 
581
    #  mail.message_id #=> nil
 
582
    #  mail.message_id(TMail.new_message_id) #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
 
583
    #  mail.message_id = TMail.new_message_id
 
584
    #  mail.message_id #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
 
585
    def message_id( default = nil )
 
586
      if h = @header['message-id']
 
587
        h.id || default
 
588
      else
 
589
        default
 
590
      end
 
591
    end
 
592
 
 
593
    # Destructively sets the message ID of the mail object instance to the passed in string
 
594
    # 
 
595
    # Invalid message IDs are ignored (silently, unless configured otherwise) and result in 
 
596
    # a nil message ID.  Left and right angle brackets are required.
 
597
    #
 
598
    # Example:
 
599
    # 
 
600
    #  mail = TMail::Mail.new
 
601
    #  mail.message_id = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
 
602
    #  mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
 
603
    #  mail.message_id = "this_is_my_badly_formatted_message_id"
 
604
    #  mail.message_id #=> nil
 
605
    def message_id=( str )
 
606
      set_string_attr 'Message-Id', str
 
607
    end
 
608
 
 
609
    # Returns the "In-Reply-To:" field contents as an array of this mail instance if it exists
 
610
    # 
 
611
    # If the in_reply_to field does not exist, returns nil by default or you can pass in as
 
612
    # the parameter for what you want the default value to be.
 
613
    # 
 
614
    # Example:
 
615
    # 
 
616
    #  mail = TMail::Mail.new
 
617
    #  mail.in_reply_to #=> nil
 
618
    #  mail.in_reply_to([]) #=> []
 
619
    #  TMail::Mail.load("../test/fixtures/raw_email_reply")
 
620
    #  mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
621
    def in_reply_to( default = nil )
 
622
      if h = @header['in-reply-to']
 
623
        h.ids
 
624
      else
 
625
        default
 
626
      end
 
627
    end
 
628
 
 
629
    # Destructively sets the value of the "In-Reply-To:" field of an email.
 
630
    # 
 
631
    # Accepts an array of a single string of a message id
 
632
    #
 
633
    # Example: 
 
634
    # 
 
635
    #  mail = TMail::Mail.new
 
636
    #  mail.in_reply_to = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
637
    #  mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
638
    def in_reply_to=( *idstrs )
 
639
      set_string_array_attr 'In-Reply-To', idstrs
 
640
    end
 
641
 
 
642
    # Returns the references of this email (prior messages relating to this message)
 
643
    # as an array of message ID strings.  Useful when you are trying to thread an
 
644
    # email.
 
645
    # 
 
646
    # If the references field does not exist, returns nil by default or you can pass in as
 
647
    # the parameter for what you want the default value to be.
 
648
    # 
 
649
    # Example:
 
650
    #
 
651
    #  mail = TMail::Mail.new
 
652
    #  mail.references #=> nil
 
653
    #  mail.references([]) #=> []
 
654
    #  mail = TMail::Mail.load("../test/fixtures/raw_email_reply")
 
655
    #  mail.references #=> ["<473FF3B8.9020707@xxx.org>", "<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
656
    def references( default = nil )
 
657
      if h = @header['references']
 
658
        h.refs
 
659
      else
 
660
        default
 
661
      end
 
662
    end
 
663
 
 
664
    # Destructively sets the value of the "References:" field of an email.
 
665
    # 
 
666
    # Accepts an array of strings of message IDs
 
667
    #
 
668
    # Example: 
 
669
    # 
 
670
    #  mail = TMail::Mail.new
 
671
    #  mail.references = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
672
    #  mail.references #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
 
673
    def references=( *strs )
 
674
      set_string_array_attr 'References', strs
 
675
    end
 
676
 
 
677
    #== MIME header methods
 
678
 
 
679
    # Returns the listed MIME version of this email from the "Mime-Version:" header field
 
680
    # 
 
681
    # If the mime_version field does not exist, returns nil by default or you can pass in as
 
682
    # the parameter for what you want the default value to be.
 
683
    # 
 
684
    # Example:
 
685
    #
 
686
    #  mail = TMail::Mail.new
 
687
    #  mail.mime_version #=> nil
 
688
    #  mail.mime_version([]) #=> []
 
689
    #  mail = TMail::Mail.load("../test/fixtures/raw_email")
 
690
    #  mail.mime_version #=> "1.0"
 
691
    def mime_version( default = nil )
 
692
      if h = @header['mime-version']
 
693
        h.version || default
 
694
      else
 
695
        default
 
696
      end
 
697
    end
 
698
 
 
699
    def mime_version=( m, opt = nil )
 
700
      if opt
 
701
        if h = @header['mime-version']
 
702
          h.major = m
 
703
          h.minor = opt
 
704
        else
 
705
          store 'Mime-Version', "#{m}.#{opt}"
 
706
        end
 
707
      else
 
708
        store 'Mime-Version', m
 
709
      end
 
710
      m
 
711
    end
 
712
 
 
713
    # Returns the current "Content-Type" of the mail instance.
 
714
    #
 
715
    # If the content_type field does not exist, returns nil by default or you can pass in as
 
716
    # the parameter for what you want the default value to be.
 
717
    # 
 
718
    # Example:
 
719
    #
 
720
    #  mail = TMail::Mail.new
 
721
    #  mail.content_type #=> nil
 
722
    #  mail.content_type([]) #=> []
 
723
    #  mail = TMail::Mail.load("../test/fixtures/raw_email")
 
724
    #  mail.content_type #=> "text/plain"
 
725
    def content_type( default = nil )
 
726
      if h = @header['content-type']
 
727
        h.content_type || default
 
728
      else
 
729
        default
 
730
      end
 
731
    end
 
732
 
 
733
    # Returns the current main type of the "Content-Type" of the mail instance.
 
734
    #
 
735
    # If the content_type field does not exist, returns nil by default or you can pass in as
 
736
    # the parameter for what you want the default value to be.
 
737
    # 
 
738
    # Example:
 
739
    #
 
740
    #  mail = TMail::Mail.new
 
741
    #  mail.main_type #=> nil
 
742
    #  mail.main_type([]) #=> []
 
743
    #  mail = TMail::Mail.load("../test/fixtures/raw_email")
 
744
    #  mail.main_type #=> "text"
 
745
    def main_type( default = nil )
 
746
      if h = @header['content-type']
 
747
        h.main_type || default
 
748
      else
 
749
        default
 
750
      end
 
751
    end
 
752
 
 
753
    # Returns the current sub type of the "Content-Type" of the mail instance.
 
754
    #
 
755
    # If the content_type field does not exist, returns nil by default or you can pass in as
 
756
    # the parameter for what you want the default value to be.
 
757
    # 
 
758
    # Example:
 
759
    #
 
760
    #  mail = TMail::Mail.new
 
761
    #  mail.sub_type #=> nil
 
762
    #  mail.sub_type([]) #=> []
 
763
    #  mail = TMail::Mail.load("../test/fixtures/raw_email")
 
764
    #  mail.sub_type #=> "plain"
 
765
    def sub_type( default = nil )
 
766
      if h = @header['content-type']
 
767
        h.sub_type || default
 
768
      else
 
769
        default
 
770
      end
 
771
    end
 
772
 
 
773
    # Destructively sets the "Content-Type:" header field of this mail object
 
774
    # 
 
775
    # Allows you to set the main type, sub type as well as parameters to the field.
 
776
    # The main type and sub type need to be a string.
 
777
    # 
 
778
    # The optional params hash can be passed with keys as symbols and values as a string,
 
779
    # or strings as keys and values.
 
780
    # 
 
781
    # Example:
 
782
    # 
 
783
    #  mail = TMail::Mail.new
 
784
    #  mail.set_content_type("text", "plain")
 
785
    #  mail.to_s #=> "Content-Type: text/plain\n\n"
 
786
    # 
 
787
    #  mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
 
788
    #  mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
 
789
    #
 
790
    #  mail.set_content_type("text", "plain", {"charset" => "EUC-KR", "format" => "flowed"})
 
791
    #  mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
 
792
    def set_content_type( str, sub = nil, param = nil )
 
793
      if sub
 
794
        main, sub = str, sub
 
795
      else
 
796
        main, sub = str.split(%r</>, 2)
 
797
        raise ArgumentError, "sub type missing: #{str.inspect}" unless sub
 
798
      end
 
799
      if h = @header['content-type']
 
800
        h.main_type = main
 
801
        h.sub_type  = sub
 
802
        h.params.clear
 
803
      else
 
804
        store 'Content-Type', "#{main}/#{sub}"
 
805
      end
 
806
      @header['content-type'].params.replace param if param
 
807
      str
 
808
    end
 
809
 
 
810
    alias content_type= set_content_type
 
811
    
 
812
    # Returns the named type parameter as a string, from the "Content-Type:" header.
 
813
    # 
 
814
    # Example:
 
815
    # 
 
816
    #  mail = TMail::Mail.new
 
817
    #  mail.type_param("charset") #=> nil
 
818
    #  mail.type_param("charset", []) #=> []
 
819
    #  mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
 
820
    #  mail.type_param("charset") #=> "EUC-KR"
 
821
    #  mail.type_param("format") #=> "flowed"
 
822
    def type_param( name, default = nil )
 
823
      if h = @header['content-type']
 
824
        h[name] || default
 
825
      else
 
826
        default
 
827
      end
 
828
    end
 
829
 
 
830
    # Returns the character set of the email.  Returns nil if no encoding set or returns
 
831
    # whatever default you pass as a parameter - note passing the parameter does NOT change
 
832
    # the mail object in any way.
 
833
    # 
 
834
    # Example:
 
835
    # 
 
836
    #  mail = TMail::Mail.load("path_to/utf8_email")
 
837
    #  mail.charset #=> "UTF-8"
 
838
    # 
 
839
    #  mail = TMail::Mail.new
 
840
    #  mail.charset #=> nil
 
841
    #  mail.charset("US-ASCII") #=> "US-ASCII"
 
842
    def charset( default = nil )
 
843
      if h = @header['content-type']
 
844
        h['charset'] or default
 
845
      else
 
846
        default
 
847
      end
 
848
    end
 
849
 
 
850
    # Destructively sets the character set used by this mail object to the passed string, you
 
851
    # should note though that this does nothing to the mail body, just changes the header
 
852
    # value, you will need to transliterate the body as well to match whatever you put 
 
853
    # in this header value if you are changing character sets.
 
854
    # 
 
855
    # Example:
 
856
    # 
 
857
    #  mail = TMail::Mail.new
 
858
    #  mail.charset #=> nil
 
859
    #  mail.charset = "UTF-8"
 
860
    #  mail.charset #=> "UTF-8"
 
861
    def charset=( str )
 
862
      if str
 
863
        if h = @header[ 'content-type' ]
 
864
          h['charset'] = str
 
865
        else
 
866
          store 'Content-Type', "text/plain; charset=#{str}"
 
867
        end
 
868
      end
 
869
      str
 
870
    end
 
871
 
 
872
    # Returns the transfer encoding of the email.  Returns nil if no encoding set or returns
 
873
    # whatever default you pass as a parameter - note passing the parameter does NOT change
 
874
    # the mail object in any way.
 
875
    # 
 
876
    # Example:
 
877
    # 
 
878
    #  mail = TMail::Mail.load("path_to/base64_encoded_email")
 
879
    #  mail.transfer_encoding #=> "base64"
 
880
    # 
 
881
    #  mail = TMail::Mail.new
 
882
    #  mail.transfer_encoding #=> nil
 
883
    #  mail.transfer_encoding("base64") #=> "base64"
 
884
    def transfer_encoding( default = nil )
 
885
      if h = @header['content-transfer-encoding']
 
886
        h.encoding || default
 
887
      else
 
888
        default
 
889
      end
 
890
    end
 
891
 
 
892
    # Destructively sets the transfer encoding of the mail object to the passed string, you
 
893
    # should note though that this does nothing to the mail body, just changes the header
 
894
    # value, you will need to encode or decode the body as well to match whatever you put 
 
895
    # in this header value.
 
896
    # 
 
897
    # Example:
 
898
    # 
 
899
    #  mail = TMail::Mail.new
 
900
    #  mail.transfer_encoding #=> nil
 
901
    #  mail.transfer_encoding = "base64"
 
902
    #  mail.transfer_encoding #=> "base64"
 
903
    def transfer_encoding=( str )
 
904
      set_string_attr 'Content-Transfer-Encoding', str
 
905
    end
 
906
 
 
907
    alias encoding                   transfer_encoding
 
908
    alias encoding=                  transfer_encoding=
 
909
    alias content_transfer_encoding  transfer_encoding
 
910
    alias content_transfer_encoding= transfer_encoding=
 
911
 
 
912
    # Returns the content-disposition of the mail object, returns nil or the passed 
 
913
    # default value if given
 
914
    # 
 
915
    # Example:
 
916
    # 
 
917
    #  mail = TMail::Mail.load("path_to/raw_mail_with_attachment") 
 
918
    #  mail.disposition #=> "attachment"
 
919
    #
 
920
    #  mail = TMail::Mail.load("path_to/plain_simple_email")
 
921
    #  mail.disposition #=> nil
 
922
    #  mail.disposition(false) #=> false
 
923
    def disposition( default = nil )
 
924
      if h = @header['content-disposition']
 
925
        h.disposition || default
 
926
      else
 
927
        default
 
928
      end
 
929
    end
 
930
 
 
931
    alias content_disposition     disposition
 
932
 
 
933
    # Allows you to set the content-disposition of the mail object.  Accepts a type
 
934
    # and a hash of parameters.
 
935
    # 
 
936
    # Example:
 
937
    # 
 
938
    #  mail.set_disposition("attachment", {:filename => "test.rb"})
 
939
    #  mail.disposition #=> "attachment"
 
940
    #  mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
 
941
    def set_disposition( str, params = nil )
 
942
      if h = @header['content-disposition']
 
943
        h.disposition = str
 
944
        h.params.clear
 
945
      else
 
946
        store('Content-Disposition', str)
 
947
        h = @header['content-disposition']
 
948
      end
 
949
      h.params.replace params if params
 
950
    end
 
951
 
 
952
    alias disposition=            set_disposition
 
953
    alias set_content_disposition set_disposition
 
954
    alias content_disposition=    set_disposition
 
955
 
 
956
    # Returns the value of a parameter in an existing content-disposition header
 
957
    # 
 
958
    # Example:
 
959
    # 
 
960
    #  mail.set_disposition("attachment", {:filename => "test.rb"})
 
961
    #  mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
 
962
    #  mail.disposition_param("filename") #=> "test.rb"
 
963
    #  mail.disposition_param("missing_param_key") #=> nil
 
964
    #  mail.disposition_param("missing_param_key", false) #=> false
 
965
    #  mail.disposition_param("missing_param_key", "Nothing to see here") #=> "Nothing to see here"
 
966
    def disposition_param( name, default = nil )
 
967
      if h = @header['content-disposition']
 
968
        h[name] || default
 
969
      else
 
970
        default
 
971
      end
 
972
    end
 
973
 
 
974
    # Convert the Mail object's body into a Base64 encoded email
 
975
    # returning the modified Mail object
 
976
    def base64_encode!
 
977
      store 'Content-Transfer-Encoding', 'Base64'
 
978
      self.body = base64_encode
 
979
    end
 
980
 
 
981
    # Return the result of encoding the TMail::Mail object body
 
982
    # without altering the current body
 
983
    def base64_encode
 
984
      Base64.folding_encode(self.body)
 
985
    end
 
986
 
 
987
    # Convert the Mail object's body into a Base64 decoded email
 
988
    # returning the modified Mail object
 
989
    def base64_decode!
 
990
      if /base64/i === self.transfer_encoding('')
 
991
        store 'Content-Transfer-Encoding', '8bit'
 
992
        self.body = base64_decode
 
993
      end
 
994
    end
 
995
 
 
996
    # Returns the result of decoding the TMail::Mail object body
 
997
    # without altering the current body
 
998
    def base64_decode
 
999
      Base64.decode(self.body, @config.strict_base64decode?)
 
1000
    end
 
1001
 
 
1002
    # Returns an array of each destination in the email message including to: cc: or bcc:
 
1003
    # 
 
1004
    # Example:
 
1005
    # 
 
1006
    #  mail.to = "Mikel <mikel@lindsaar.net>"
 
1007
    #  mail.cc = "Trans <t@t.com>"
 
1008
    #  mail.bcc = "bob <bob@me.com>"
 
1009
    #  mail.destinations #=> ["mikel@lindsaar.net", "t@t.com", "bob@me.com"]
 
1010
    def destinations( default = nil )
 
1011
      ret = []
 
1012
      %w( to cc bcc ).each do |nm|
 
1013
        if h = @header[nm]
 
1014
          h.addrs.each {|i| ret.push i.address }
 
1015
        end
 
1016
      end
 
1017
      ret.empty? ? default : ret
 
1018
    end
 
1019
 
 
1020
    # Yields a block of destination, yielding each as a string.
 
1021
    #  (from the destinations example)
 
1022
    #  mail.each_destination { |d| puts "#{d.class}: #{d}" }
 
1023
    #  String: mikel@lindsaar.net
 
1024
    #  String: t@t.com
 
1025
    #  String: bob@me.com
 
1026
    def each_destination( &block )
 
1027
      destinations([]).each do |i|
 
1028
        if Address === i
 
1029
          yield i
 
1030
        else
 
1031
          i.each(&block)
 
1032
        end
 
1033
      end
 
1034
    end
 
1035
 
 
1036
    alias each_dest each_destination
 
1037
 
 
1038
    # Returns an array of reply to addresses that the Mail object has, 
 
1039
    # or if the Mail message has no reply-to, returns an array of the
 
1040
    # Mail objects from addresses.  Else returns the default which can
 
1041
    # either be passed as a parameter or defaults to nil
 
1042
    # 
 
1043
    # Example:
 
1044
    #  mail.from = "Mikel <mikel@lindsaar.net>"
 
1045
    #  mail.reply_to = nil
 
1046
    #  mail.reply_addresses #=> [""]  
 
1047
    # 
 
1048
    def reply_addresses( default = nil )
 
1049
      reply_to_addrs(nil) or from_addrs(nil) or default
 
1050
    end
 
1051
 
 
1052
    # Returns the "sender" field as an array -> useful to find out who to 
 
1053
    # send an error email to.
 
1054
    def error_reply_addresses( default = nil )
 
1055
      if s = sender(nil)
 
1056
        [s]
 
1057
      else
 
1058
        from_addrs(default)
 
1059
      end
 
1060
    end
 
1061
 
 
1062
    # Returns true if the Mail object is a multipart message
 
1063
    def multipart?
 
1064
      main_type('').downcase == 'multipart'
 
1065
    end
 
1066
 
 
1067
    # Creates a new email in reply to self.  Sets the In-Reply-To and
 
1068
    # References headers for you automagically.
 
1069
    #
 
1070
    # Example:
 
1071
    #  mail = TMail::Mail.load("my_email")
 
1072
    #  reply_email = mail.create_reply
 
1073
    #  reply_email.class         #=> TMail::Mail
 
1074
    #  reply_email.references  #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
 
1075
    #  reply_email.in_reply_to #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
 
1076
    def create_reply
 
1077
      setup_reply create_empty_mail()
 
1078
    end
 
1079
 
 
1080
    # Creates a new email in reply to self.  Sets the In-Reply-To and
 
1081
    # References headers for you automagically.
 
1082
    #
 
1083
    # Example:
 
1084
    #  mail = TMail::Mail.load("my_email")
 
1085
    #  forward_email = mail.create_forward
 
1086
    #  forward_email.class         #=> TMail::Mail
 
1087
    #  forward_email.content_type  #=> "multipart/mixed"
 
1088
    #  forward_email.body          #=> "Attachment: (unnamed)"
 
1089
    #  forward_email.encoded       #=> Returns the original email as a MIME attachment
 
1090
    def create_forward
 
1091
      setup_forward create_empty_mail()
 
1092
    end
 
1093
 
 
1094
    #:stopdoc:
 
1095
    private
 
1096
 
 
1097
    def create_empty_mail
 
1098
      self.class.new(StringPort.new(''), @config)
 
1099
    end
 
1100
 
 
1101
    def setup_reply( mail )
 
1102
      if tmp = reply_addresses(nil)
 
1103
        mail.to_addrs = tmp
 
1104
      end
 
1105
 
 
1106
      mid = message_id(nil)
 
1107
      tmp = references(nil) || []
 
1108
      tmp.push mid if mid
 
1109
      mail.in_reply_to = [mid] if mid
 
1110
      mail.references = tmp unless tmp.empty?
 
1111
      mail.subject = 'Re: ' + subject('').sub(/\A(?:\[[^\]]+\])?(?:\s*Re:)*\s*/i, '')
 
1112
      mail.mime_version = '1.0'
 
1113
      mail
 
1114
    end
 
1115
 
 
1116
    def setup_forward( mail )
 
1117
      m = Mail.new(StringPort.new(''))
 
1118
      m.body = decoded
 
1119
      m.set_content_type 'message', 'rfc822'
 
1120
      m.encoding = encoding('7bit')
 
1121
      mail.parts.push m
 
1122
      # call encoded to reparse the message
 
1123
      mail.encoded
 
1124
      mail
 
1125
    end
 
1126
 
 
1127
  #:startdoc:
 
1128
  end   # class Mail
 
1129
 
 
1130
end   # module TMail