nuke : in file name (IO::Adapter, Mail::Message)

1 files changed, 362 insertions, 0 deletions

diff --git a/fml/doc/ja/tutorial/module/Message.sgml b/fml/doc/ja/tutorial/module/Message.sgml
new file mode 100644
index 00000000..f8171d04
--- /dev/null
+++ b/fml/doc/ja/tutorial/module/Message.sgml
@@ -0,0 +1,362 @@
+<!--
+   $FML: Mail::Message.sgml,v 1.7 2002/07/07 01:57:11 fukachan Exp $
+-->
+
+<chapter id="module.mail.message">
+	<title>
+	Mail::Message モジュール
+	</title>
+
+<sect1>
+	<title>
+	Mail::Message の概要
+	</title>
+
+<para>
+このオブジェクトモジュールはメールの解析と、
+解析されたデータ構造へのさまざまな操作手段を提供してくれます。
+</para>
+
+<para>
+少し詳しく説明すると、このモジュールはメールを解析し、
+<screen>
+(multipart でない場合)
+
+header -> body
+
+(multipart の場合)
+
+header -> preamble -> part1 -> part2 -> trailor
+</screen>
+のようにオブジェクトが数珠つなぎのようなデータ構造を作ります。
+ちなみに鎖と鎖の間は double link list です。
+Mail::Message のクラスは
+このようなデータ構造に対して、さまざまなオペレーションを提供します。
+</para>
+
+<para>
+この鎖の部分部分それぞれが Mail::Message オブジェクトです。
+つまり一通のメールはメールヘッダから始まるオブジェクトの鎖として
+表現されます。
+</para>
+
+<para>
+header は Mail::Message のタイプが text/rfc822-headers で、
+data が Mail::Header オブジェクトになります。
+一方 part1 は
+text/plain
+で、
+data 部分が文字列へのリファレンスです。
+</para>
+
+<para>
+参照:
+<ulink url="../../en/modules/Mail/Message.txt">
+Mail::Message モジュールのマニュアル
+</ulink>
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: 解析する
+	</title>
+
+<para>
+parse() メソッドは
+引数で与えられた
+ファイル(名)かファイルディスクリプタに対し
+メッセージの解析をします。
+</para>
+
+<para>
+data_type_list()
+は
+鎖の列の情報を返します。
+情報は ARRAY REFERENCE の形で返されます。
+例えば MIME/Multipart は次のようになります。
+<screen>
+  type[ 1]: text/rfc822-headers       | multipart/mixed
+  type[ 2]: multipart/mixed           | multipart/mixed
+  type[ 3]: multipart.preamble        | multipart/mixed
+  type[ 4]: multipart.delimiter       | multipart/mixed
+  type[ 5]: text/plain                | multipart/mixed
+  type[ 6]: multipart.delimiter       | multipart/mixed
+  type[ 7]: image/gif                 | multipart/mixed
+  type[ 8]: multipart.close-delimiter | multipart/mixed
+  type[ 9]: text/plain                | multipart/mixed
+</screen>
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: 新しいメッセージを作る
+	</title>
+
+<para>
+new() メソッドは通常、新しいメッセージを作る際に使われます。
+</para>
+
+<para>
+MIME/multipart 専用のためのメソッドもあります。
+<screen>
+build_mime_multipart_chain($args)
+parse_and_build_mime_multipart_chain($args)
+build_mime_header($args)
+</screen>
+しかしながら、MIME/mulitpart の作成には
+Mail::Message::Compose クラスがあります。
+実のところ、このクラスの実態は MIME::Lite そのものです :-)
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: ヘッダの操作
+	</title>
+
+<para>
+dup_header() メソッドは
+RFC822 型のメッセージのヘッダ部分のみのコピーを行ないます。
+メールの本体の部分はそのままです。
+複製されたヘッダオブジェクトからのリンクは
+メールの本体です。
+<screen>
+              |<--------------- メール本体 ------------->
+header0 ----> part1 -> part2 -> ...
+               A
+               |
+dup_header0 ---
+</screen>
+</para>
+
+
+<para>
+whole_message_header()
+はメッセージの中のヘッダ部分のオブジェクトを返します。
+文字列ではないことに注意して下さい。
+</para>
+
+<para>
+__head_message() は鎖の先頭のオブジェクトを返します。
+__last_message() は鎖の最後のオブジェクトを返します。
+そのため、通常、図の header オブジェクトを返すことになりますので、
+多くの場合 whole_message_header() と等価です。
+</para>
+
+<para>
+header_data_type()
+はメール全体のタイプ(文字列)を返します。
+つまり、このメッセージは単なるテキストなのかマルチパートなのか？などを
+教えてくれます。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: メッセージ本文の操作
+	</title>
+
+<para>
+以下では、このような鎖を例にとるとします。
+<screen>
+(multipart でない場合)
+
+header -> body
+
+(multipart の場合)
+
+header -> preamble -> part1 -> part2 -> trailor
+</screen>
+</para>
+
+
+<para>
+まず header_data_type()
+はメール全体のタイプ(文字列)を返します。
+つまり、このメッセージは単なるテキストなのかマルチパートなのか？などを
+教えてくれます。
+つまり header の Content-Type で得られる情報です。
+</para>
+
+<para>
+whole_message_body() メソッドは
+body ないしは part1 の部分のオブジェクトを返します。
+whole_message_body_head() メソッドも同じ操作をします。
+</para>
+
+<para>
+__head_message() は鎖の先頭のオブジェクトを返します。
+__last_message() は鎖の最後のオブジェクトを返します。
+そのため、通常、図の header オブジェクトを返すことになりますので、
+多くの場合 whole_message_header() と等価です。
+__last_message() は鎖の最後の部分なのでメッセージ本文の最後になります。
+</para>
+
+<para>
+find_first_plaintext_message($args)
+は
+鎖の中で最初の plain/text タイプの Mail::Message オブジェクトを返します。
+フィルタリングでは最初の
+plain/text タイプのメッセージ部分に着目することが多いので
+この関数を使うと便利です。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: オブジェクトの検索
+	</title>
+
+<para>
+find() メソッドは Mail::Message の特定のタイプを探し、
+最初に見つけたオブジェクトを返します。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: メッセージを表示する。
+	</title>
+
+<para>
+print() メソッドは文字どおり print です。
+通常は引数で出力するファイルディスクリプタを渡して下さい。
+</para>
+
+<para>
+print() には CRLF なのか LF なのかを指定する mode という概念があります。
+このために
+set_print_mode(mode) および
+reset_print_mode()
+というメソッドがあります。
+通常は raw で、SMTP の時だけは smtp を指定して下さい。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Mail::Message モジュール: 便利な関数
+	</title>
+
+<sect2>
+	<title>
+	サイズ
+	</title>
+
+<para>
+size()
+はオブジェクトのサイズを返します。
+メール全体ではありません。
+header_size()
+や
+body_size()
+を使うと、ヘッダやメール本文全体の長さを教えてくれます。
+</para>
+
+<para>
+is_empty()
+はオブジェクトが空かどうかを教えてくれます。
+</para>
+</sect2>
+
+
+<sect2>
+	<title>
+	一般的な情報
+	</title>
+
+<para>
+envelope_sender()
+は
+メールの送信者情報(文字列)を返します。
+</para>
+
+<para>
+data_type()
+は
+Mail::Message オブジェクトのタイプ(文字列)を返します。
+これは、メール全体のタイプ（マルチパートとか text/plain)
+どではなく、鎖の各部分のオブジェクトのタイプであることに注意して下さい。
+</para>
+
+<para>
+encoding_mechanism()
+は
+Mail::Message オブジェクトのエンコーディングメカニズム(文字列)を返します。
+エンコーディングされていないなら undef が返ります。
+これは、メール全体のタイプ（マルチパートとか text/plain)
+どではなく、鎖の各部分のオブジェクトのタイプであることに注意して下さい。
+</para>
+
+</sect2>
+
+
+<sect2>
+	<title>
+	Mail::Message 内の構造
+	</title>
+
+<para>
+num_paragraph()
+は
+その Mail::Message オブジェクトの中に
+何個のパラグラフがあるか(数字)を返します。
+</para>
+
+
+<para>
+nth_paragraph(数字)
+は
+数字番目のパラグラフの内容を文字列として返します。
+例えば、一番目のパラグラフは 0 ではなく 1 と指定して下さい。
+</para>
+
+
+<para>
+header()
+は
+MIME/multipart の各ブロックにあるヘッダ部分を返します。
+data()
+は、データの部分です。
+それぞれ
+message_fields($size)
+message_text($size)
+の alias です。
+</para>
+
+</sect2>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	参照
+	</title>
+
+<para>
+
+<ulink url="../../en/modules/Mail/Message.txt">
+Mail::Message モジュールの(英語)マニュアル
+</ulink>
+</para>
+</sect1>
+
+
+</chapter>