tmail 1.2.1 → 1.2.2

data/site/outdated/rdd/mailbox.rrd.m

@@ -0,0 +1,228 @@
+= Mailbox Classes
+
+== class TMail::MhMailbox
+
+j
+MH 形式のメールボックスを隠蔽するクラス。
+e
+The class to handle MH mailboxes.
+.
+
+=== Class Methods
+
+: new(dirname) -> TMail::MhMailbox
+    dirname: String
+
+j
+    MhMailbox オブジェクトを生成します。
+    dirname は MH メールボックスとして使うディレクトリ名です。
+    すでに作成ずみでなければいけません。
+e
+    creates new MhMailbox object.
+    DIRNAME must be valid MH mailbox directory.
+.
+
+=== Instance Methods
+
+: each_port {|port| .... }
+: each {|port| .... }
+    port: TMail::FilePort
+
+j
+    メールボックスのメールに対して古いメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in assendant order (older mail first).
+.
+
+: reverse_each_port {|port| .... }
+: reverse_each {|port| .... }
+    port: TMail::FilePort
+
+j
+    ディレクトリ中のメールに対して新しいメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in descendant order (newer mail first).
+.
+
+: last_atime -> Time
+: last_atime=(time)
+    time: Time
+
+j
+    最後に each_new_port/each_port/reverse_each_port を呼び出した時間。
+e
+    The time which last each_new_port/each_port/reverse_each_port is called.
+.
+
+: each_new_port(time = last_atime()) {|port| .... }
+    time: Time
+    port: TMail::FilePort
+
+j
+    新着メールのみに対してくりかえします。
+    引数 time が与えられたときはその時刻以降に更新されたメールを新着とみなします。
+    与えられなかった時は前回の each_mail, reverse_each_mail, each_new_port の後に
+    更新されたメールを新着とみなします。
+e
+    iterates for each mails in mailbox, which are newer than TIME.
+.
+
+: new_port -> TMail::FilePort
+j
+    新しいメールに対応するファイルを作成し、
+    対応する TMail::Port オブジェクトを返す。
+e
+    creates a new file in the mailbox and returns its port.
+.
+
+: close
+j
+    なにもしません。
+e
+    does nothing.
+.
+
+== class TMail::UNIXMbox
+
+j
+UNIX mbox を扱うクラス。現在の実装では、生成時に MH 形式に変換し、
+明示的な close 呼び出しか GC のタイミングでファイルに書き戻します。
+e
+The class to handle UNIX mbox.
+Current implementation creates temporary MH mbox.
+.
+
+=== Class Methods
+
+: new(filename) -> TMail::UNIXMbox
+    filename: String
+
+j
+    新しい TMail::UNIXMbox オブジェクトを生成します。
+    filename は UNIX mbox ファイル名です。
+e
+    creates new TMail::UNIMbox object.
+    FILENAME must be valid UNIX mbox file name.
+.
+
+=== Instance Methods
+
+: each_port {|port| .... }
+: each {|port| .... }
+    port: TMail::FilePort
+
+j
+    メールボックスのメールに対して古いメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in assendant order (older mail first).
+.
+
+: reverse_each_port {|port| ... }
+: reverse_each {|port| ... }
+    port: TMail::FilePort
+
+j
+    ディレクトリ中のメールに対して新しいメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in descendant order (newer mail first).
+.
+
+: each_new_port(time = @last_loaded_time) {|port| .... }
+    time: Time
+    port: TMail::FilePort
+
+j
+    新着メールのみに対してくりかえします。
+    引数 time が与えられたときはその時刻以降に更新されたメールを新着とみなします。
+    与えられなかった時は前回の each_mail, reverse_each_mail, each_new_port の後に
+    更新されたメールを新着とみなします。
+e
+    iterates for each mails in mailbox, which are newer than TIME.
+    @last_loaded_time is updated when each_new_port/each_port is
+    called.
+.
+
+: new_port -> TMail::FilePort
+j
+    新しいメールに対応するファイルを作成し、
+    対応する TMail::Port オブジェクトを返す。
+e
+    creates a new file in the mailbox and returns its port.
+.
+
+: close
+j
+    明示的にメールボックスを書き戻します。以後、このオブジェクトに
+    対してメール操作メソッドを呼び出すと全て例外になります。
+e
+    forces an UNIXMbox to write back mails to real mbox file.
+    Once this method is called, any method calls causes to raise
+    IOError exception.
+.
+
+== class TMail::Maildir
+
+j
+qmail が使用するメールボックス maildir を隠蔽するクラス。
+e
+The class to handle "maildir" mailbox.
+.
+
+=== Class Methods
+
+: new(dirname) -> TMail::Maildir
+    dirname: String
+
+j
+    新しい TMail::Maildir オブジェクトを生成します。
+    dirname は maildir メールボックスとして使うディレクトリ名です。
+    ディレクトリはすでに作成ずみでなければいけません。
+e
+    creates new TMail::Maildir object.
+    DIRNAME must be valid maildir.
+.
+
+=== Instance Methods
+
+: each_port {|port| .... }
+: each {|port| .... }
+    port: TMail::FilePort
+
+j
+    メールボックスのメールに対して古いメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in assendant order (older mail first).
+.
+
+: reverse_each_port {|port| .... }
+: reverse_each {|port| .... }
+    port: TMail::FilePort
+
+j
+    ディレクトリ中のメールに対して新しいメールから順番に繰り返します。
+e
+    iterates for each mail in the mailbox,
+    in descendant order (newer mail first).
+.
+
+: each_new_port {|port| .... }
+    port: TMail::FilePort
+
+j
+    MAILDIR/new のメールに対して、cur に移動したのちに繰り返します。
+e
+    iterates for each mails in MAILDIR/new.
+.
+
+: new_port -> TMail::FilePort
+j
+    新しいメールに対応するファイルを作成し、
+    対応する Port オブジェクトを返す。
+e
+    creates a new file in the mailbox and returns its port.
+.

data/site/outdated/rdd/port.rrd.m

@@ -0,0 +1,69 @@
+= Port Classes
+
+== class TMail::Port
+
+j
+TMail::Port は TMail ライブラリでのファイルや文字列の抽象表現です。
+メール一通分にあたるリソースを隠蔽します。
+e
+TMail::Port is the abstruction of mail source.
+.
+
+=== Instance Methods
+
+: ropen -> IO
+j
+    読みこみ用ストリームを返します。
+e
+    opens stream for read.
+.
+
+: wopen -> IO
+j
+    書きこみ用ストリームを返します。
+e
+    opens stream for write.
+.
+
+: aopen -> IO
+j
+    追加書きこみ用ストリームを返します。
+e
+    opens stream for adding.
+.
+
+== class TMail::FilePort < TMail::Port
+
+=== Class Methods
+
+: new(filename) -> TMail::FilePort
+    filename: String
+
+j
+    FilePort オブジェクトを生成します。
+    filename はメール一通をおさめたファイル名でなければいけません。
+e
+    creates new TMail::FilePort object.
+.
+
+: filename -> String
+j
+    このポートが隠蔽しているファイル名を返します。
+e
+    returns file name which this port is wrapping.
+.
+
+== class TMail::StringPort < TMail::Port
+
+=== Class Methods
+
+: new(src = '') -> TMail::StringPort
+    src: String
+
+j
+    StringPort オブジェクトを生成します。
+    string はメール一通分の文字列でなければいけません。
+e
+    creates new TMail::StringPort object from
+    mail source string.
+.

data/site/outdated/rdd/tmail.rrd.m

@@ -0,0 +1,33 @@
+= module TMail
+
+== Module Functions
+
+: new_boundary -> String
+j
+    新しいバウンダリを作成して返します。
+e
+    creates new MIME multipart mail boundary.
+.
+
+: new_message_id(fqdn = Socket.gethostname) -> String
+    fqdn: String
+
+j
+    新しいメッセージ ID を作成して返します。
+    引数 fqdn が省略された場合はローカルホストの名前を使います。
+    一方 fqdn を指定する場合はダイヤルアップであるなどの事情により
+    ホストの名前を変える必要があるのだとみなし、それに '.tmail' を
+    つけたドメインを使用します。これは「本物の」ドメインで作成される
+    メッセージ ID との重複を避けるためです。
+e
+    creates new message ID.
+.
+
+: message_id?(str) -> true | false
+    str: String
+
+j
+    str がメッセージ ID を含むとき真。
+e
+    returns true if STR includes message ID string.
+.

data/site/outdated/rdd/usage.rd.m

@@ -0,0 +1,247 @@
+j
+= TMail の使い方
+e
+= TMail Usage
+.
+
+j
+== TMail の概要
+e
+== Abstruction
+.
+
+j
+TMail は電子メールを扱うための総合ライブラリです。メールとメール
+ボックスのハンドリングを隠蔽します。初期の目的がメーラの作成だった
+ため、主な使い方としては「メールから情報を得る」「新しいメールを作成する」
+の二種類が想定されており、クライアント側の処理に強くなっています。
+e
+TMail is 90% RFC compatible mail library. By using TMail, You can
+get data from internet mail (e-mail) and write data to mail,
+without knowning standard details.
+.
+
+j
+== メールから情報を得る
+
+これは一番最初に実装された部分であり、TMail が最も得意とする処理でも
+あります。
+e
+== Getting information from e-mail
+.
+
+j
+=== TMail::Mail クラス
+e
+=== class TMail::Mail
+.
+
+j
+TMail::Mail クラスはメール一通を隠蔽するオブジェクトです。まずどうにか
+してこのオブジェクトを作らないといけません。このオブジェクトを作る方法は
+三通りあります。
+
+  (1) 文字列からつくる
+  (2) ファイル(名)からつくる
+  (3) Port からつくる
+
+文字列、ファイルはそれぞれメール一通分だけを含んでいなければいけません。
+そのうえで以下のように作成します。
+e
+At first you must create TMail::Mail object. There's three ways
+to create Mail object. First one is "creating from string", second
+way is "creating from file (name)". Examples are below:
+.
+--
+require 'tmail'
+mail = TMail::Mail.parse(string)    # from String
+mail = TMail::Mail.load(filename)   # from file
+--
+j
+ここには特に問題はないと思います。
+.
+
+j
+=== Port と Loader
+e
+=== Port and Loader
+.
+
+j
+Port というのは TMail におけるメールソースの抽象表現です。たとえば
+上述した文字列やファイル名もメールソースで、TMail::Mail#parse や load は
+文字列やファイルを一度 Port でラップしたうえで Mail オブジェクトを作成
+しています。この Port でラップすることで文字列、ファイル
+(将来的には IMAP プロトコルも？) の違いを隠蔽しています。
+
+ただし、Port をユーザが直接作ることはあまりないでしょう。主にユーザが
+Port をさわることになるのは、メールボックスのラッパーである Loader を
+使うときです。たとえば MH メールボックスの中にあるメールを順番に処理する
+ためには以下のようにします。
+e
+The third way to get TMail::Mail object is using the "port".
+"port" is the abstruction of mail sources, e.g. strings or file names.
+You can get ports by using mail loaders (TMail::*Loader classes).
+Here's simple example:
+.
+--
+require 'tmail'
+
+loader = TMail::MhLoader.new( '/home/aamine/Mail/inbox' )
+loader.each_port do |port|
+  mail = TMail::Mail.new(port)
+  # ....
+end
+--
+
+j
+=== TMail::Mail オブジェクトから情報を得る
+e
+=== Accessing EMail Attributes via TMail::Mail object
+.
+
+j
+以上のような手段で TMail::Mail オブジェクトを作ったら、あとはそのメソッドを
+呼ぶだけでたいていのことはできます。たとえば To: アドレスを取るなら
+e
+Now you can get any data from e-mail, by calling methods of
+TMail::Mail object. For example, to get To: addresses...
+.
+--
+require 'tmail'
+mail = TMail::Mail.parse( 'To: Minero Aoki <aamine@loveruby.net>' )
+p mail.to   # => ["aamine@loveruby.net"]
+--
+j
+Subject: ならば
+e
+to get subject,
+.
+--
+p mail.subject
+--
+j
+メール本体ならば
+e
+to get mail body,
+--
+p mail.body
+--
+j
+というように、とても簡単です。
+.
+
+j
+詳しくは TMail::Mail クラスのリファレンスを、
+より実用的な例としては sample/from-check.rb を見てください。
+e
+For more TMail::Mail class details, see reference manual.
+For more examples, see sample/from-check.rb.
+.
+
+j
+=== MIME マルチパートメール
+
+MIME マルチパートメールにも対応しています。マルチパートのときは
+Mail#multipart? が真になり、#parts に TMail::Mail オブジェクトの
+配列が入ります。
+e
+=== MIME multipart mail
+
+TMail also supports MIME multipart mails.
+If mail is multipart mail, Mail#multipart? returns true,
+and Mail#parts contains an array of parts (TMail::Mail object).
+.
+--
+require 'tmail'
+mail = TMail::Mail.parse( multipart_mail_string )
+if mail.multipart? then
+  mail.parts.each do |m|
+    puts m.main_type
+  end
+end
+--
+j
+より具体的な例としては sample/multipart.rb を見てください。
+e
+For examples, see sample/multipart.rb.
+.
+
+j
+=== TMail がやらないこと
+
+TMail は、ヘッダは自動でデコード・エンコードしますが、本体(本文)は
+一切変更しません。ただし近い将来には Base64 のデコードは自動でやる
+かもしれません。
+e
+=== What TMail is NOT
+
+TMail does not touch mail body. Does not decode body,
+does not encode body, does not change line terminator.
+(I want to support Base64 auto-decoding although.)
+.
+
+
+j
+== 新しいメールを作成する
+
+こちらも TMail::Mail クラスが主体です。とにかくメールを作ればいい
+場合は空文字列から、メールボックスに作りたい場合はローダを経由して
+ポートを作成してそこから、メールオブジェクトを作ります。
+e
+== Creating New Mail
+.
+--
+require 'tmail'
+
+# Example 1: create mail on only memory
+mail = TMail::Mail.new
+
+# Example 2: create mail on mailbox (on disk)
+loader = TMail::MhLoader.new('/home/aamine/Mail/drafts')
+mail = TMail::Mail.new( loader.new_port )
+--
+j
+作ったら、中身を入れます。
+e
+then fill headers and body.
+.
+--
+mail.to = 'test@loveruby.net'
+mail.from = 'Minero Aoki <aamine@loveruby.net>'
+mail.subject = 'test mail'
+mail.date = Time.now
+mail.mime_version = '1.0'
+mail.set_content_type 'text', 'plain', {'charset'=>'iso-2022-jp'}
+mail.body = 'This is test mail.'
+--
+j
+どのヘッダをセットしたらいいかなど細かい部分ももうちょっとカバー
+したいのですが、まだ実装していません。とりあえず上記のヘッダは
+セットしたほうがよいでしょう。また返信・転送の場合はまたそれぞれ
+規約があります。これもカバーしたいのですがまだ実装していません。
+バージョン 1.0 に期待してください。
+
+最後に文字列化します。
+e
+At last, convert mail object to string.
+.
+--
+str = mail.encoded
+--
+j
+作成元ポートに書き戻すなら、かわりに以下のようにします。
+e
+If you want to write mails against files directly
+(without intermediate string), use Mail#write_back.
+.
+--
+mail.write_back
+--
+j
+write_back は中間文字列を介することなくファイルに直接書きこみます。
+
+より実用的な例としては sample/sendmail.rb を見てください。
+e
+For more examples, see sample/sendmail.rb.
+.