@comment $OpenXM: OpenXM/src/asir-doc/parts/builtin/io.texi,v 1.13 2003/11/27 15:56:08 ohara Exp $
\BJP
@node 入出力,,, 組み込み函数
@section 入出力
\E
\BEG
@node Inputs and Outputs,,, Built-in Function
@section Inputs and Outputs
\E

@menu
* end quit::
* load::
* which::
* output::
* bsave bload::
* bload27::
* print::
* access::
* open_file close_file get_line get_byte put_byte purge_stdin::
@end menu

\JP @node end quit,,, 入出力
\EG @node end quit,,, Inputs and Outputs
@subsection @code{end}, @code{quit}
@findex end
@findex quit

@table @t
@item end, quit
\BJP
:: 現在読み込み中のファイルを閉じる. 
トップレベルにおいてはセッションを終了することになる. 
\E
\BEG
:: Close the currently reading file.
At the top level, terminate the @b{Asir} session.
\E
@end table

@itemize @bullet
\BJP
@item
@code{end}, @code{quit} ともに無引数の函数であるが, @samp{()} なしで
呼び出すことができる. いずれも現在読み込み中のファイルを閉じる. 
これは, トップレベルにおいてはセッションを終了させることになる. 
@item
ファイルの場合, ファイルの終端まで読めば, 自動的にファイルは閉じられる
が, トップレベルの場合プロンプトが出ないまま, 入力待ちになるので, 
ファイルの終端には @code{end$} を書くのが望ましい. 
\E
\BEG
@item
These two functions take no arguments.  These functions can be called
without a @samp{()}.  Either function close the current input file.
This means the termination of the @b{Asir} session at the top level.
@item
An input file will be automatically closed if it is read to its end.
However, if no @code{end$} is written at the last of the input file,
the control will be returned to the top level and @b{Asir} will be
waiting for an input without any prompting.
Thus, in order to avoid confusion, putting a @code{end$} at the last
line of the input file is strongly recommended.
\E
@end itemize

@example
[6] quit;
%
@end example

@table @t
\JP @item 参照
\EG @item References
@fref{load}.
@end table

\JP @node load,,, 入出力
\EG @node load,,, Inputs and Outputs
@subsection @code{load}
@findex load

@table @t
@item load("@var{filename}")
\JP :: @var{filename} を読み込む. 
\EG :: Reads a program file @var{filename}.
@end table

@table @var
@item return
(1|0)
@item filename
\JP ファイル名 (パス名)
\EG file (path) name
@end table

@itemize @bullet
\BJP
@item
実際のプログラムの書き方は, @pxref{ユーザ言語 Asir}.
 テキストファイルを読み込む場合, @code{cpp} 
を通すので, C のプログラム同様 @code{#include}, @code{#define} を使うことができる. 
@item
指定したファイルが存在した時には 1 を返し, 存在しなかった時は 0 を返す. 
@item
ファイル名が @samp{/} で始まる場合は絶対パス, @samp{.} で始まる場合は
カレントディレクトリからの相対パスと見なされる. それ以外の場合, 
環境変数 @code{ASIRLOADPATH} に設定されているディレクトリを左から順に
サーチする. それらに該当するファイルが存在しない場合, 標準ライブラリ
ディレクトリ (あるいは環境変数 @code{ASIR_LIBDIR} に設定されている
ディレクトリ) もサーチする. 
Windows 版の場合, @code{ASIR_LIBDIR} が設定されていない場合には, 
@code{get_rootdir()/lib} をサーチする. 
@item
読み込むファイルの最後に, @code{end$} がないと @code{load()} 
終了後にプロンプトがでないが, 実際には入力を受け付ける. しかし, 
混乱を招くおそれがあるのでファイルの最後に @code{end$} を書いておくこと
が望ましい. (@code{end;} でもよいが, @code{end} が返す値 0 が表示される
ため, @code{end$} をお勧めする. )
@item
Windows 版もディレクトリのセパレータとして @samp{/} を用いる.
\E
\BEG
@item
See @ref{User language Asir} for practical programming.
Since text files are read through @code{cpp},
the user can use, as in C programs, @code{#include} and @code{#define}
in @b{Asir} program source codes.
@item
It returns 1 if the designated file exists, 0 otherwise.
@item
If the @var{filename} begins with @samp{/}, it is understood as an
absolute path name; with  @samp{.}, relative path name from current
directory; otherwise, the file is searched first from directories
assigned to an environmental variable @code{ASIRLOADPATH}, then
if the search ends up in failure, the standard library directory
(or directories assigned to @code{ASIR_LIBDIR}) shall be searched.
On Windows, @code{get_rootdir()/lib} is searched if 
@code{ASIR_LIBDIR} is not set.
@item
We recommend to write an @code{end} command at the last line of
your program.  If not, @b{Asir} will not give you a prompt after it
will have executed @code{load} command.
(Escape with an interrupt character (@ref{Interruption}),
if you have lost yourself.)
Even in such a situation,
@b{Asir} itself is still ready to read keyboard inputs as usual.
It is, however, embarrassing and may cause other errors.
Therefore, to put an @code{end$} at the last line is desirable.
(Command @code{end;} will work as well,
but it also returns and displays verbose.)
@item
On Windows one has to use @samp{/} as the separator of directory names.
\E
@end itemize

@table @t
\JP @item 参照
\EG @item References
@fref{end quit}, @fref{which}, @fref{get_rootdir}.
@end table

\JP @node which,,, 入出力
\EG @node which,,, Inputs and Outputs
@subsection @code{which}
@findex which

@table @t
@item which("@var{filename}")
\JP :: 引数 @var{filename} に対し, @code{load()} が読み込むパス名を返す. 
\EG :: This returns the path name for the @var{filename} which @code{load()} will read.
@end table

@table @var
@item return
\JP パス名
\EG path name
@item filename
\JP ファイル名 (パス名) または 0
\EG filename (path name) or 0
@end table

@itemize @bullet
\BJP
@item
@code{load()} がファイルをサーチする手順に従ってサーチし, 
ファイルが存在する場合にはパス名を文字列として, 存在しない場合
には 0 を返す. 
@item
サーチの手順については @code{load()} を参照. 
@item
Windows 版もディレクトリのセパレータとして @samp{/} を用いる.
\E
\BEG
@item
This function searches directory trees according to the same procedure
as @code{load()} will do.  Then, returns a string, the path name to the
file if the named file exists; 0 unless otherwise.
@item
For details of searching procedure,
refer to the description about @code{load()}.
@item
On Windows one has to use @samp{/} as the separator of directory names.
\E
@end itemize

@example
[0] which("gr");               
./gb/gr
[1] which("/usr/local/lib/gr");
0
[2] which("/usr/local/lib/asir/gr");
/usr/local/lib/asir/gr
@end example

@table @t
\JP @item 参照
\EG @item References
@fref{load}.
@end table

\JP @node output,,, 入出力
\EG @node output,,, Inputs and Outputs
@subsection @code{output}
@findex output

@table @t
@item output(["@var{filename}"])
\JP :: 以降の出力先を @var{filename}または標準出力に切替える. 
\EG :: Writes the return values and prompt onto file @var{filename}.
@end table

@table @var
@item return
1
@item filename
\JP ファイル名
\EG filename
@end table

@itemize @bullet
\BJP
@item
@b{Asir} の出力を標準出力から, ファイルへの出力に切替える. 
なお, ファイル出力の間は, 標準出力にはキーボードからの入力以外, 
出力されない. 
@item
別のファイル出力に切替える時には, 再び @code{output("@var{filename}")} 
を実行する. 
又, ファイル出力を終了し標準出力に戻りたい時には, 引数なしで 
@code{output()} を実行する. 
@item
指定したファイル @var{filename} が存在した時は, そのファイルの末尾に
追書きされ, 存在しなかった時には, 新たにファイルを作成し, そこに書き込まれる. 
@item
ファイルネームを "" ダブルクォートなしで指定をしたり, 
ユーザが, 書き込めないファイルを指定したりすると, 
エラーによりトップレベルに戻る. 
@item
入力したものも込めてファイルに出力したい場合には, @code{ctrl("echo",1)} 
を実行した後でファイル出力に切替えれば良い. 
@item
計算時間など, 標準エラー出力に書き出されるものはファイルには書き出されない. 
@item
函数形式, 未定係数 (@code{vtype()} 参照) を含まない数式のファイルへの読み書きは, 
@code{bload()}, @code{bsave()} を使うのが, 時間, 空間ともに効率がよい. 
@item
Windows 版もディレクトリのセパレータとして @samp{/} を用いる.
\E
\BEG
@item
Standard output stream of @b{Asir} is redirected to the specified file.
While @b{Asir} is writing its outputs onto a file, no outputs, except for
keyboard inputs and some of error messages, are written onto the standard
output. (You cannot see the result on the display.)
@item
To direct the @b{Asir} outputs to the standard output, issue the command
without argument, i.e., @code{output()}.
@item
If the specified file already exists, new outputs will be added to the
tail of the file. If not, a file is newly created and the outputs
will be written onto the file.
@item
When file name is specified without double quotes (@code{""}), or
when protected file is specified, an error occurs and the system returns
to the top level.
@item
If you want to write inputs from the key board onto the file as well
as @b{Asir} outputs, put command @code{ctrl("echo",1)}, and then
redirect the standard output to your desired file.
@item
Contents which are written onto the standard error output, CPU time etc.,
are not written onto the file.
@item
Reading and writing algebraic expressions which contain neither
functional forms nor unknown coefficients (@code{vtype()} References)
are performed more efficiently, with respect to both time and space,
by @code{bload()} and  @code{bsave()}.
@item
On Windows one has to use @samp{/} as the separator of directory names.
\E
@end itemize

@example
[83] output("afo");
fctr(x^2-y^2);
print("afo");
output();
1
[87] quit;
% cat afo
1
[84] [[1,1],[x+y,1],[x-y,1]]
[85] afo
0
[86]
@end example

@table @t
\JP @item 参照
\EG @item References
@fref{ctrl}, @fref{bsave bload}.
@end table

\JP @node bsave bload,,, 入出力
\EG @node bsave bload,,, Inputs and Outputs
@subsection @code{bsave}, @code{bload}
@findex bsave
@findex bload

@table @t
@item bsave(@var{obj},"@var{filename}")
\JP :: @var{filename} に @var{obj} をバイナリ形式で書き込む. 
\EG :: This function writes @var{obj} onto @var{filename} in binary form.
@item bload("@var{filename}")
\JP :: @var{filename} から数式をバイナリ形式で読み込む. 
\EG :: This function reads an expression from @var{filename} in binary form.
@end table

@table @var
@item return
\JP @code{bsave()} : 1, @code{bload()} : 読み込んだ数式
\EG @code{bsave()} : 1, @code{bload()} : the expression read
@item obj
\JP 函数形式, 未定係数を含まない任意の数式
\BEG
arbitrary expression which does not contain neither function forms
nor unknown coefficients.
\E
@item filename
\JP ファイル名
\EG filename
@end table

@itemize @bullet
\BJP
@item
@code{bsave()} は内部形式をほぼそのままバイナリ形式でファイルに書き込む. 
@code{bload()} は, @code{bsave()} で書き込んだ数式を読み込んで内部形式
に変換する. 現在のインプリメンテーションの制限により, 函数形式, 未定係数 
(@code{vtype()} 参照) を含まないリスト, 配列などを含む任意の数式をファ
イルに保存することができる.
@item
@code{output()} などで保存した場合, 読み込み時にパーザが起動されるが, 
@code{bsave()} で保存したものを @code{bload()} で読む場合, 直接
内部形式が構成できるため, 時間的, 空間的に効率がよい. 
@item
多項式の場合, 書き込み時と読み込み時で変数順序が異なる場合があるが, 
その場合には, 自動的に現在の変数順序における内部形式に変換される. 
@item
Windows 版もディレクトリのセパレータとして @samp{/} を用いる.
\E
\BEG
@item
Function @code{bsave()} writes an object onto a file in its internal
form (not exact internal form but very similar).
Function @code{bload()} read the expression from files
which is written by @code{bsave()}.
Current implementation support arbitrary expressions, including
lists, arrays (i.e., vectors and matrices), except for function forms
and unknown coefficients (@code{vtype()} References.)
@item
The parser is activated to retrieve expressions written by
@code{output()} , whereas internal forms are directly reconstructed
by @code{bload()} from the @code{bsave()}'ed object in the file.
The latter is much more efficient with respect to both time and space.
@item
It may happen that the variable ordering at reading is changed from
that at writing.  In such a case, the variable ordering in the internal
expression is automatically rearranged according to the current
variable ordering.
@item
On Windows one has to use @samp{/} as the separator of directory names.
\E
@end itemize

@example
[0] A=(x+y+z+u+v+w)^20$
[1] bsave(A,"afo");
1
[2] B = bload("afo")$
[3] A == B;
1
[4] X=(x+y)^2; 
x^2+2*y*x+y^2
[5] bsave(X,"afo")$
[6] quit;
% asir
[0] ord([y,x])$    
[1] bload("afo");
y^2+2*x*y+x^2
@end example

@table @t
\JP @item 参照
\EG @item References
@fref{output}.
@end table

\JP @node bload27,,, 入出力
\EG @node bload27,,, Inputs and Outputs
@subsection @code{bload27}
@findex bload27

@table @t
@item bload27("@var{filename}") 
\JP :: 旧版で作られた bsave file の読み込み
\EG :: Reads bsaved file created by older version of @b{Asir}.
@end table

@table @var
@item return
\JP 読み込んだ数式
\EG expression read
@item filename
\JP ファイル名
\EG filename
@end table

@itemize @bullet
\BJP
@item
旧版では, 多倍長整数が, 1 ワード 27 bit で表現されていたが, 新版では 1 ワード 32 bit
に変更された. このため, 旧版で @code{bsave} されたバイナリファイルはそのままでは
読み込めない. このようなファイルを読み込むために @code{bload27} を用いる. 
@item
Windows 版もディレクトリのセパレータとして @samp{/} を用いる.
\E
\BEG
@item
In older versions an arbitrary precision integer is represented as
an array of 27bit integers. In the current version it is represented
as an array of 32bit integers. By this incompatibility the bsaved
file created by older versions cannot be read in the current version
by @code{bload}.
@code{bload27} is used to read such files.
@item
On Windows one has to use @samp{/} as the separator of directory names.
\E
@end itemize

@table @t
\JP @item 参照
\EG @item References
@fref{bsave bload}.
@end table

\JP @node print,,, 入出力
\EG @node print,,, Inputs and Outputs
@subsection @code{print}
@findex print

@table @t
@item print(@var{obj} [,@var{nl}])
\JP :: @var{obj} を表示する. 
\EG :: Displays (or outputs) @var{obj}.
@end table

@table @var
@item return
0
@item obj
\JP 任意
\EG arbitrary
@item nl
\JP フラグ (任意)
\EG flag (arbitrary)
@end table

@itemize @bullet
\BJP
@item
@var{obj} を評価して表示する. 
@item
第 2 引数がないか, または 0, 2 以外の場合, 改行する. 
第 2 引数が 1 の場合, 改行せず, 出力はバッファに書き込まれ, 
バッファはフラッシュされない. 
第 2 引数が 2 の場合, 改行しないがバッファはフラッシュされる. 
@item
この函数の戻り値は 0 であるから, @code{print();}
で実行すると, 出力の後に 0 が返される.
@code{print()$} とすれば, 最後の 0 は出力されない.
@item
複数の @var{obj} を同時に出力したい時は @var{obj} をリストにするとよい.
\E
\BEG
@item 
Displays (or outputs) @var{obj}.
@item 
It normally adds linefeed code to cause the cursor moving to the next
line.  If 0 or 2 is given as the second argument, it does not add a linefeed.
If the second argument is 0, the output is simply written in the buffer.
If the second argument is 2, the output is flushed.
@item 
The return value of this function is 0.
If command @code{print(@var{rat});} is performed at the top level,
first the value of @var{rat} will be printed,
followed by a linefeed, followed by a 0 which is the value of the
function and followed by a linefeed and the next prompt.
(If the command is terminated by a `$', e.g., @code{print(@var{rat})$},
The last 0 will not be printed. )
@item 
Formatted outputs are not currently supported.
If one wishes to output multiple objects by a single @code{print()} command,
use list like @code{[@var{obj1},...]}, which is not so beautiful, but
convenient to minimize programming efforts.
\E
@end itemize

@example
[8] def cat(L) @{ while ( L != [] ) @{ print(car(L),0); L = cdr(L);@}
print(""); @}
[9] cat([xyz,123,"gahaha"])$
xyz123gahaha
@end example

\JP @node access,,, 入出力
\EG @node aceess,,, Inputs and Outputs
@subsection @code{access}
@findex access

@table @t
@item access(@var{file})
\JP :: @var{file} の存在をテストする. 
\EG :: testing an existence of @var{file}.
@end table

@table @var
@item return
0 or 1
@item file
\JP ファイル名
\EG filename
@end table

@itemize @bullet
\BJP
@item
@var{file} が存在すれば 1, 存在しなければ 0 を返す. 
\E
@end itemize

\JP @node open_file close_file get_line get_byte put_byte purge_stdin,,, 入出力
\EG @node open_file close_file get_line get_byte put_byte purge_stdin,,, Inputs and Outputs
@subsection @code{open_file}, @code{close_file}, @code{get_line}, @code{get_byte}, @code{put_byte}, @code{purge_stdin}
@findex open_file
@findex close_file
@findex get_line
@findex get_byte
@findex put_byte
@findex purge_stdin

@table @t
@item open_file("@var{filename}"[,"@var{mode}"])
\JP :: @var{filename} をオープンする. 
\EG :: Opens @var{filename} for reading.
@item close_file(@var{num})
\JP :: 識別子 @var{num} のファイルをクローズする. 
\EG :: Closes the file indicated by a descriptor @var{num}.
@item get_line([@var{num}])
\JP :: 識別子 @var{num} のファイルから 1 行読む. 
\EG :: Reads a line from the file indicated by a descriptor @var{num}.
@item get_byte(@var{num})
\JP :: 識別子 @var{num} のファイルから 1 バイト読む. 
\EG :: Reads a byte from the file indicated by a descriptor @var{num}.
@item put_byte(@var{num},@var{c})
\JP :: 識別子 @var{num} のファイルに 1 バイト @var{c} を書く.
\EG :: Writes a byte @var{c} to the file indicated by a descriptor @var{num}.
@item purge_stdin()
@item purge_stdin()
\JP :: 標準入力のバッファをクリアする.
\EG :: Clears the buffer for the standard input.
@end table

@table @var
@item return
\JP @code{open_file()} : 整数 (識別子); @code{close_file()} : 1; @code{get_line()} : 文字列; @code{get_byte()}, @code{put_byte()} : 整数
\EG @code{open_file()} : integer (fild id); @code{close_file()} : 1; @code{get_line()} : string; @code{get_byte()}, @code{put_byte()} : integer
@item filename
\JP ファイル名 (パス名)
\EG file (path) name
@item mode
\JP 文字列
\EG string
@item num
\JP 非負整数 (ファイル識別子)
\EG non-negative integer (file descriptor)
@end table

@itemize @bullet
\BJP
@item @code{open_file()} はファイルをオープンする. @var{mode} 指定が
ない場合読み出し用, @var{mode} 指定がある場合には, C の標準入出力
関数 @code{fopen()} に対するモード指定とみなす. たとえば新規書き込み
用の場合 @code{"w"}, 末尾追加の場合 @code{"a"} など.
成功した場合, ファイル識別子として非負整数を返す. 失敗の場合エラーとなる. 
不要になったファイルは @code{close_file()} でクローズする. 
特別なファイル名 unix://stdin, unix://stdout, unix://stderr を与えると
それぞれ標準入力, 標準出力, 標準エラー出力をオープンする.
この場合モード指定は無視される.
@item @code{get_line()} は現在オープンしているファイルから 1 行読み, 
文字列として返す. 引数がない場合, 標準入力から 1 行読む.
@item @code{get_byte()} は現在オープンしているファイルから 1 バイト読み
整数として返す.
@item @code{put_byte()} は現在オープンしているファイルに 1 バイト書き, 
そのバイトを整数として返す.
@item ファイルの終りまで読んだ後に @code{get_line()} が呼ばれた場合, 
整数の 0 を返す. 
@item 読み出した文字列は, 必要があれば @code{sub_str()} などの文字列処理
関数で加工したのち @code{eval_str()} により内部形式に変換できる. 
@item @code{purge_stdin()} は, 標準入力バッファを空にする. 
関数内で @code{get_line()} により標準入力から文字列を受け取る場合,
既にバッファ内に存在する文字列による誤動作を防ぐためにあらかじめ
呼び出す.
\E
\BEG
@item @code{open_file()} opens a file.
If @var{mode} is not specified, a file is opened for reading.
If @var{mode} is specified, it is used as the mode specification for
C standard I/O function @code{fopen()}. For example @code{"w"} requests
that the file is truncated to zero length or created for writing.
@code{"a"} requests that the file is opened for writing or created 
if it does not exist.
The stream pointer is set at the end of the file.
If successful, it returns a non-negative integer as the file descriptor.
Otherwise the system error function is called.
Unnecessary files should be closed by @code{close_file()}.
If the special file name unix://stdin or unix://stdout or unix://stderr
is given, it returns the file descriptor for the standard input or
the standard output or the standard error stream respectively.
The mode argument is ignored in this case.
@item @code{get_line()} reads a line from an opened file and returns the
line as a string. If no argument is supplied, it reads a line from the
standard input.
@item @code{get_byte()} reads a byte from an opened file and returns the
it as an integer.
@item @code{put_byte()} writes a byte from an opened file and returns the
the byte as an integer.
@item A @code{get_line()} call after reading the end of file returns
an integer 0.
@item Strings can be converted into internal forms with string manipulation
functions such as @code{sub_str()}, @code{eval_str()}.
@item @code{purge_stdin()} clears the buffer for the standard input.
When a function receives a character string from @code{get_line()},
this functions should be called in advance in order to avoid 
an incorrect behavior which is caused by the characters already
exists in the buffer.
\E
@end itemize

@example
[185] Id = open_file("test");
0
[186] get_line(Id);
12345

[187] get_line(Id);
67890

[188] get_line(Id);
0
[189] type(@@@@);
0
[190] close_file(Id);
1
[191] open_file("test");
1
[192] get_line(1);   
12345

[193] get_byte(1);
54                   /* the ASCII code of '6' */
[194] get_line(1);
7890                 /* the rest of the last line */
[195] def test() @{ return get_line(); @}
[196] def test1() @{ purge_stdin(); return get_line(); @}
[197] test();
                     /* a remaining newline character has been read */
                     /* returns immediately */
[198] test1();
123;                 /* input from a keyboard */
123;                 /* returned value */

[199] 

@end example

@table @t
\JP @item 参照
\EG @item References
@fref{eval_str}, @fref{str_len str_chr sub_str}.
@end table