* ext/pty: moved documents and samples to the appropriate places.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@28400 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

doc/pty/README

@@ -0,0 +1,84 @@
+pty extension version 0.3 by A.ito
+
+1. Introduction
+
+This extension module adds ruby a functionality to execute an 
+arbitrary command through pseudo tty (pty).
+
+2. Install
+
+Follow the instruction below.
+
+(1) Execute
+
+      ruby extconf.rb
+
+    then Makefile is generated.
+
+(3) Do make; make install.
+
+3. What you can do
+
+This extension module defines a module named PTY, which contains
+following module fungtions:
+
+   getpty(command)
+   spawn(command)
+
+      This function reserves a pty, executes command over the pty 
+      and returns an array. The return value is an array with three
+      elements. The first element in the array is for reading and the 
+      second for writing. The third element is the process ID of the
+      child process. If this function is called with an iterator block,
+      the array is passed to the block as block parameters, and the
+      function itself returns nil.
+
+      When the child process is suspended or finished, an exception is
+      raised.  If this function is called with an iterator block,
+      exception is raised only within the block.  Child process
+      monitor is terminated on block exit.
+
+   protect_signal
+   reset_signal
+
+      These functions are obsolete in this version of pty.
+
+   PTY.open
+
+      Allocates a pty (pseudo-terminal).
+
+      It returns an array which contains an IO object and a File object.
+      The former is the master of the pty.
+      The latter is the slave of the pty.
+
+      If a block is given, it yields the array instead of return.
+      The value of the block is returned.
+      master_io and slave_file is closed when return if they are not closed.
+
+   PTY.check(pid[, raise=false])
+
+      checks the status of the child process specified by pid, and
+      returns nil if the process is still alive and active.
+      Otherwise, returns Process::Status about the process if raise is
+      false, or PTY::ChildExited exception is raised.
+
+4. License
+
+(C) Copyright 1998 by Akinori Ito.
+
+This software may be redistributed freely for this purpose, in full 
+or in part, provided that this entire copyright notice is included 
+on any copies of this software and applications and derivations thereof.
+
+This software is provided on an "as is" basis, without warranty of any
+kind, either expressed or implied, as to any matter including, but not
+limited to warranty of fitness of purpose, or merchantability, or
+results obtained from use of this software.
+
+5. Bug report
+
+Please feel free to send E-mail to
+
+   aito@ei5sun.yz.yamagata-u.ac.jp
+
+for any bug report, opinion, contribution, etc.

doc/pty/README.expect

@@ -0,0 +1,22 @@
+	README for expect
+		by A. Ito, 28 October, 1998
+
+	Expect library adds IO class a method called expect(), which
+does similar act to tcl's expect extension. 
+
+The usage of the method is:
+
+   IO#expect(pattern,timeout=9999999)
+
+where `pattern' is an instance of String or Regexp and `timeout'
+is Fixnum, which can be omitted. 
+	When the method is called without block, it waits until the
+input which matches the pattern is obtained from the IO or the time
+specified as the timeout passes. When the pattern is obtained from the
+IO, the method returns an array. The first element of the array is the
+entire string obtained from the IO until the pattern matches. The
+following elements indicates the specific pattern which matched to the
+anchor in the regular expression. If the method ends because of
+timeout, it returns nil. 
+ 	When the method is called with block, the array is passed as
+the block parameter.

doc/pty/README.expect.ja

@@ -0,0 +1,21 @@
+	README for expect
+		by A. Ito, 28 October, 1998
+
+  Expectライブラリは，tcl の expect パッケージと似たような機能を
+IOクラスに追加します．
+
+  追加されるメソッドの使い方は次の通りです．
+
+   IO#expect(pattern,timeout=9999999)
+
+pattern は String か Regexp のインスタンス，timeout は Fixnum
+のインスタンスです．timeout は省略できます．
+  このメソッドがブロックなしで呼ばれた場合，まずレシーバである
+IOオブジェクトから pattern にマッチするパターンが読みこまれる
+まで待ちます．パターンが得られたら，そのパターンに関する配列を
+返します．配列の最初の要素は，pattern にマッチするまでに読みこ
+まれた内容の文字列です．2番目以降の要素は，pattern の正規表現
+の中にアンカーがあった場合に，そのアンカーにマッチする部分です．
+もしタイムアウトが起きた場合は，このメソッドはnilを返します．
+  このメソッドがブロック付きで呼ばれた場合には，マッチした要素の
+配列がブロック引数として渡され，ブロックが評価されます．

doc/pty/README.ja

@@ -0,0 +1,76 @@
+pty 拡張モジュール version 0.3 by A.ito
+
+1. はじめに
+
+この拡張モジュールは，仮想tty (pty) を通して適当なコマンドを
+実行する機能を ruby に提供します．
+
+2. インストール
+
+次のようにしてインストールしてください．
+
+(1)  ruby extconf.rb
+
+    を実行すると Makefile が生成されます．
+
+(2) make; make install を実行してください．
+
+3. 何ができるか
+
+この拡張モジュールは，PTY というモジュールを定義します．その中
+には，次のようなモジュール関数が含まれています．
+
+   getpty(command)
+   spawn(command)
+
+      この関数は，仮想ttyを確保し，指定されたコマンドをその仮想tty
+      の向こうで実行し，配列を返します．戻り値は3つの要素からなる
+      配列です．最初の要素は仮想ttyから読み出すためのIOオブジェクト，
+      2番目は書きこむためのIOオブジェクト，3番目は子プロセスのプロ
+      セスIDです．この関数がイテレータとして呼ばれた場合，これらの
+      要素はブロックパラメータとして渡され，関数自体はnilを返します．
+
+      子プロセスが終了したり停止した場合には，例外が発生します．この関
+      数がブロックパラメータ付きで呼ばれた場合には，そのブロックの中で
+      のみ例外が発生します．子プロセスをモニターしているスレッドはブロッ
+      クを抜けるときに終了します．
+      
+   protect_signal
+   reset_signal
+
+      廃止予定です．
+
+   PTY.open
+
+      仮想ttyを確保し，マスター側に対応するIOオブジェクトとスレーブ側に
+      対応するFileオブジェクトの配列を返します．ブロック付きで呼び出さ
+      れた場合は，これらの要素はブロックパラメータとして渡され，ブロッ
+      クから返された結果を返します．また、このマスターIOとスレーブFile
+      は、ブロックを抜けるときにクローズ済みでなければクローズされます．
+
+   PTY.check(pid[, raise=false])
+
+      pidで指定された子プロセスの状態をチェックし，実行中であればnilを
+      返します．終了しているか停止している場合、第二引数が偽であれば、
+      対応するProcess::Statusオブジェクトを返します。真であれば
+      PTY::ChildExited例外が発生します．
+
+4. 利用について
+
+伊藤彰則が著作権を保有します．
+
+ソースプログラムまたはドキュメントに元の著作権表示が改変されずに
+表示されている場合に限り，誰でも，このソフトウェアを無償かつ著作
+権者に無断で利用・配布・改変できます．利用目的は限定されていませ
+ん．
+
+このプログラムの利用・配布その他このプログラムに関係する行為によ
+って生じたいかなる損害に対しても，作者は一切責任を負いません．
+
+5. バグ報告等
+
+バグレポートは歓迎します．
+
+	aito@ei5sun.yz.yamagata-u.ac.jp
+
+まで電子メールでバグレポートをお送りください．