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

1 files changed, 275 insertions, 0 deletions

diff --git a/fml/doc/ja/tutorial/module/IO.sgml b/fml/doc/ja/tutorial/module/IO.sgml
new file mode 100644
index 00000000..ac2e070b
--- /dev/null
+++ b/fml/doc/ja/tutorial/module/IO.sgml
@@ -0,0 +1,275 @@
+<!--
+   $FML: IO::Adapter.sgml,v 1.7 2002/09/28 14:14:06 fukachan Exp $
+-->
+
+<chapter id="module.io.adapter">
+	<title>
+	IO へのアダプター層 (IO::Adapter クラス)
+	</title>
+
+
+<sect1 id="module.io.adapter.overview">
+	<title>
+	IO::Adapter の概要
+	</title>
+
+<para>
+&fmldevel; でのメンバーリストの読み書き、
+例えばアドレスの登録/削除、は
+IO::Adapter という抽象クラスを通じて行ないます。
+使い方は例えば次のような感じです。
+<screen>
+use IO::Adapter;
+$obj = new IO::Adapter $map, $map_params;
+$obj->open || croak("cannot open $map");
+while ($x = $obj->get_next_key()) { ... }
+$obj->close;
+</screen>
+</para>
+
+<para>
+現在のところ $map は次のようなものが使えます。
+<screen>
+file:/var/spool/ml/elena/actives
+unix.group:root
+nis.group:root
+mysql:id
+postgresql:id  (未実装)
+ldap:id        (未実装)
+</screen>
+</para>
+
+<para>
+file: は通常のファイルです。
+unix.group:root は /etc/group の root のエントリにあるユーザのリストを、
+nis.group:root は NIS の root のエントリにあるユーザのリストです。
+mysql:id は MySQL へのアクセスです。
+mysql:id で指定されたパラメータを用います。
+このパラメータは new() を実行する際に別途与える必要があります。
+</para>
+
+</sect1>
+
+
+<sect1 id="module.io.adapter.methods">
+	<title>
+	メソッド
+	</title>
+
+<para>
+IO::Adapter の提供する公式なメソッドは次の通りです。
+<screen>
+new()
+open()
+close()
+
+get_next_key()
+
+add(KEY)
+delete(KEY)
+
+getpos()
+setpos(NUM)
+eof()
+
+touch()
+
+find(REGEXP, $args)
+</screen>
+です。
+KEY はデータベースのプライマリキーで、
+通常メールアドレスです。
+REGEXP は正規表現ですが、たいていはメールアドレスです。
+</para>
+
+<para>
+多くのマップを同じように扱うために、
+メソッドは極力最少限に、少数精鋭なものだけに限定する必要があります。
+</para>
+
+<para>
+最低限のメソッド群の定義は実際に実装してみる実験を通じて選ばれました。
+その際、ファイルの IO よりは、SQL との IO を想定しつつ、
+メソッドの組を考えています。
+そのため、&fml4; のファイルを前提にした処理とくらべると、
+少し不自由に思えるでしょうが、
+そのおかげで抽象化が高くなっています。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	&fmldevel; で必要なメソッドの型
+	</title>
+
+<para>
+get_next_key() のように引数なしか STR を引数にして STR を返り値にする
+ものが多いです。これはファイルの一覧を見るとか、特定のアドレスに対する
+何かの値を取り寄せるとかいう操作でよく使われるためです。
+</para>
+
+<para>
+しかし、特定のアドレスに対する値が組になっているものがあります。
+これは
+<screen>
+KEY_STR => [
+     VALUE_STR_1
+     VALUE_STR_2
+     VALUE_STR_3
+]
+</screen>
+のようなデータ構造が返ってくることを期待する場合です。
+&fml4; の actives はメールアドレスに対していくつかのオプションの値を記
+述するので、こういったデータ構造と考えられます。
+<screen> 
+例
+
+rudo@nuinui.net	s=skip m=xxx.yyy.z # commnet
+
+rudo@nuinui.net => [
+        s=skip
+        m=xxx.yyy.z
+        # comment
+]
+</screen> 
+</para>
+
+<para>
+まとめると引数はないか STR なので STR とひとまとめにしても良いです。
+一方、返り値は STR か ARRAY_REF になります。
+<screen>
+引数    返り値
+---------------------------------------
+なし => STR
+
+STR  => STR
+
+なし => [STR, STR, ... ]
+
+STR  => [STR, STR, ... ]
+</screen>
+</para>
+
+</sect1>
+
+
+<sect1 id="module.io.adapter.map.file">
+	<title>
+	file マップ	
+	</title>
+
+<para>
+『file:ファイル名』もしくは単なる『ファイル名』は
+ごく普通のテキストファイルへの IO を抽象化したものです。
+</para>
+
+</sect1>
+
+
+<sect1 id="module.io.adapter.map.unixgroup">
+	<title>
+	unixgroup マップ	
+	</title>
+
+<para>
+/etc/group を抽象化します。
+当然 READ ONLY です。
+</para>
+
+<para>
+/etc/group の
+<screen>
+wheel:*:0:root,rudo,kenken
+</screen>
+は IO::Adapter では unixgroup:wheel としてアクセスできます。
+<screen>
+$obj = new IO::Adapter "unixgroup:wheel";
+</screen>
+というオブジェクトに対し get_next_key() すると
+グループのメンバーが順に返されます。
+つまり 3 行のファイルを読みだすものとして、
+<screen>
+root
+rudo
+kenken
+</screen>
+のようなファイルとみなされます。
+</para>
+
+</sect1>
+
+
+<sect1 id="module.io.adapter.map.nis">
+	<title>
+	NIS マップ	
+	</title>
+
+<para>
+/etc/group とほぼ同様ですが、ソースが
+NIS/YP から group にあたるものを引っ張ってくるところだけが異なります。
+</para>
+
+</sect1>
+
+
+<sect1 id="module.io.adapter.map.mysql">
+	<title>
+	MySQL マップ	
+	</title>
+
+<para>
+&fmldevel; の設定では .cf の中にSQL の設定を書いておきたいと思います。
+つまり一つの cf ファイルにいろいろ書けるようにしておきたい。
+</para>
+
+<para>
+そこで、[mysql:members] (から終りまで、もしくは次の =head 文まで)の
+ブロックで、マップのタイプと識別子を表現しています。
+<screen>
+config.cf の例
+
+member_maps     =       mysql:members
+
+recipient_maps  =       mysql:recipients
+
+[mysql:members]
+
+sql_server      =       localhost
+sql_user        =       fml
+sql_password    =       uja
+sql_database    =       fml
+sql_table       =       ml
+
+sql_find	=	select * from ...
+
+		...
+</screen>
+</para>
+
+<para>
+IO::Adapter は
+<screen>
+new IO::Adapter "mysql:members", $config;
+</screen>
+のように呼び出します。
+この $config は次のようなハッシュ・リファレンスになっていることが
+期待されています。
+<screen>
+$config => {
+	[mysql:members] => {
+		sql_sever => localhost
+			...	
+	}
+}
+</screen>
+FML::Config は .cf から上のようなハッシュを構成します。
+よって IO::Adapter の new() の際には、
+FML::Config のオブジェクトを引数で渡せば OK です。
+</para>
+
+</sect1>
+
+
+</chapter>