← 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: Richard Lee (Canonical)
  • Date: 2010-10-15 15:17:58 UTC
  • mfrom: (190.1.3 use-case-mapper)
  • Revision ID: richard.lee@canonical.com-20101015151758-wcvmfxrexsongf9d
Merge

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