第二部 - ライブラリルーチン

1. はじめに

 
多数のライブラリルーチンが提供されています。正確にはインタプリタex.exe, exw.exe, exwc.exeまたはexuにいくつか組み込まれています。その他はEuphoriaで記述されており利用するにはeuphoria\includeにある.eファイルのうち一つをインクルードする必要があります。この場合は、特に"構文"の一種としてインクルードファイルは使用されます。もちろんインクルードファイルはプログラムから一度だけインクルードされます。インタプリタに組み込まれているルーチンはEuphoria標準エディタではマゼンタ(深紅色)で表示され、インクルードファイルは不要です。同名のルーチンを定義すことにより組み込みルーチンの上書き(override)ができます。こうしたときは警告は抑制されます。

オブジェクトを渡したり返すために、オブジェクトの種類を示す次の接頭辞が使用されます:

x - 一般的な オブジェクト (アトムまたはシーケンス)
s - シーケンス
a - アトム
i - 整数
fn - ファイル番号で使用される整数
st - 文字列シーケンス、 または単一の文字アトム

いくつかのルーチンは4つの動作環境うち1つまたは2つのみ利用可能です。この注釈は、"動作環境: DOS32" または "動作環境: WIN32" または "動作環境: Linux" のルーチンの解説であり、(DOS32) または (WIN32) または (Linux)は、その他に数種に位置します。通常はLinuxで動作するものはFreeBSDでも動作します。ただし、マウスルーチンのみ例外となります。

通常は違法な引数値がルーチンに与えられたときは、ランタイムエラーメッセージを出力します。



2. アプリケーション向けルーチン


2.1 定義済み型

これらの型で変数を宣言できるだけではなく、値が特定の型であるかどうか調べるために、通常の関数のように呼び出すことができます。

integer - オブジェクトがinteger型(整数)であるかどうか調べます。
atom - オブジェクトがatom型(アトム)であるかどうか調べます。
sequence - オブジェクトがsequence型(シーケンス)であるかどうか調べます。
object - オブジェクトがobject型(オブジェクト)であるかどうか調べます(常に真値)。



2.2 シーケンスの操作

length - シーケンスの長さを返します。
repeat - オブジェクトをn回複製した長さnのシーケンスを返します。
reverse - シーケンス内の要素の順列を反転します。
append - シーケンスの後尾に新しい要素を追加します。
prepend - シーケンスの先頭に新しい要素を追加します。



2.3 検索とソート

compare - 二つのオブジェクトを比較します。
equal - 2つのオブジェクトが同一であるか比較します。
find - シーケンスからオブジェクトを検索します - 要素番号1から検索を開始します。
find_from - シーケンスからオブジェクトを検索します。 - 任意の要素番号から検索を開始します。
match - シーケンスから別のシーケンスのスライスを検索します。 - 要素番号1から検索を開始します。
match_from - シーケンスから別のシーケンスのスライスを検索します。 - 任意の要素番号から検索を開始します。
sort - シーケンスの要素を昇順にソートします。
custom_sort - 自作した比較関数を使用してシーケンスの要素をソートします。



2.4 パターンマッチング

lower - アトムまたはシーケンスを半角英数小文字へ変換します。
upper - アトムまたはシーケンスを半角英数大文字へ変換します。
wildcard_match - ワイルドカード(?および*)を含むパターンとマッチします。
wildcard_file - ワイルドカード指定に一致(マッチ)するファイル名を返します。



2.5 算術

これらルーチンはアトムまたはシーケンスの値に対して個別に適用することができます。詳細は第一部 - シーケンスの演算を参照してください。

sqrt - オブジェクトの平方根(Square root)を計算します。
rand - 乱数を生成します。
sin - サイン(正弦)の角度を計算します。
arcsin - サインを与えて角度を計算します。
cos - コサインの角度を計算します。
arccos - コサインを与えて角度を計算します。
tan - タンジェントの角度を計算します。
arctan - タンジェントを与えて角度を計算します
log - 自然対数(natural logarithm)を計算します。
floor - 近似値で丸め込みます。
remainder - 別の値で割って剰余を求めます。
power - 数値を累乗したものを求めます。
PI - 円周率 PI (3.14159...)を算術値の返します。



2.6 ビット論理演算

これらのルーチンは数値を2進数のビット集合として扱い、2進数表現の数値に対応するビットに対して論理演算を行います。ビットの左側に対するビットシフトルーチンはありませんが、乗算または2の累乗で除算することにより類似の効果を得えられます。

and_bits - 対応するビットに対して論理AND処理を行います。
or_bits - 対応するビットに対して論理OR処理を行います。
xor_bits - 対応するビットに対して論理XOR処理を行います。
not_bits - 全てのビットに対して論理OR処理を行います。



2.7 ファイルとデバイスI/O

最初にファイルまたはデバイスに対して出入力を行う場合はファイルまたはデバイスを開く必要があり、次に後述するルーチンによって読み書きを行い、最後にファイルまたはデバイスを閉じる必要があります。open()は他のI/Oルーチンの最初の引数で使用するファイル番号を生成します。特定のファイルまたはデバイスは自動的に開かれます(テキストファイルとして):

0 - 標準入力
1 - 標準出力
2 - 標準エラー出力
コマンドライン(command-line)へリダイレクトを行わない限り、標準入力はキーボードから入力され、標準出力と標準エラー出力はスクリーンに出力されます。スクリーンへ何かを出力する場合はバッファリングなしで即時出力されます。ファイル書き込み時、効率的にファイルに書き出すために十分な量がバッファに蓄積されるまで文字はバッファに配置されます。ファイルまたはデバイスに対してclose() またはflush()を実行したとき、バッファに残っている全ての文字は書き出されます。ファイルからの入力もバッファリングされます。まだ開いている最中のファイルはプログラム終了時に自動的に閉じられます。
注意事項:
もしプログラム(Euphoriaまたは任意の他の言語で記述されたもの)がファイルを書くために開いたときに、何らかの理由で強制的にコンピュータが再起動したならば、なんらかのファイルシステムの破壊が発生するかもしれないため、ファイルシステムを全て修復するために速やかにscandisk(ボリュームのエラーチェック)を再起動後に行う必要があります。
open - ファイルまたはデバイスを開きます。
close - ファイルまたはデバイスを閉じます。
flush - ファイルまたはデバイスのバッファ済みデータをフラッシュして出力します。
lock_file - ファイルまたはデバイスをロック(施錠)します。
unlock_file - ファイルまたはデバイスをアンロック(解錠)します。
print - 一行でブレースブラケットとカンマ{,,}で表現したEuphoriaのオブジェクトの構造を出力します。
pretty_print - Euphoriaのオブジェクトを複数行分割と適切なインデントを用いて読みやすい形式にします。
? x - print(1, x)の略記です。
sprint - Euphroiaのオブジェクトを文字列シーケンスとして出力したものを返します。
printf - ファイルまたはデバイスに対して書式つき出力を行います。
sprintf - 文字列シーケンスを整形して出力したものを返します。
puts - ファイルまたはデバイスに対して文字列シーケンスを出力します。
getc - 次の文字をファイルまたはデバイスから読み取ります。
gets - 次の行をファイルまたはデバイスから読み取ります。
get_bytes - 次のnバイトをファイルまたはデバイスから読み取ります。
prompt_string - プロンプトを表示してユーザから数値の入力を待ちます。
get_key - ユーザによるキー入力を待ち時間なしで調べます。
wait_key - ユーザのキー入力を待ちます。
get - ファイルから任意のEuphoriaオブジェクトの表現を読み取ります。
prompt_number - プロンプトを表示してユーザから数値の入力を待ちます。
value - 任意のEuphoriaオブジェクト表現を文字列から読み込みます。
seek - 開いているファイル内の任意のバイト位置に移動します。
where - 開いているファイルの位置が何バイト目か報告します。
current_dir - カレントディレクトリ名を返します。
chdir - カレントディレクトリを変更します。
dir - ディレクトリ内の完全なファイル情報を返します。
walk_dir - 再帰的にディレクトリ内の全てのファイルを渡り歩きます。
allow_break - Ctrl+C/Ctrl+Breakによるプログラムの強制終了を許可または禁止します。
check_break - Crtl+C/Ctrl+Breakが押されたか調べます。



2.8 マウスサポート(DOS32/Linux)

注意事項: Windows XPで、DOSウィンドウ(非フルスクリーン)でマウスを動作させたいときは、DOSウィンドウのプロパティにあるクイックエディットモードを無効にする必要があります。
get_mouse - マウス"イベント"を返します(クリック、移動)。
mouse_events - どのマウスイベントを検出するか決定します。
mouse_pointer - マウスポインタの表示・非表示を指定します。



2.9 オペレーティングシステム

time - 固定地点からの経過秒数を得ます。
tick_rate - 秒ごとの割り込みタイマ割り込みを設定します(DOS32)
date - 現在の年、月、日、時、分、秒などを取得します。
command_line - プログラムでコマンドライン引数を使用します。
getenv - 環境変数の値を取得します。
system - オペレーティングシステムのコマンドラインを実行します。
system_exec - プログラムを実行後に終了コードを取得します。
abort - プログラムの実行を停止します。
sleep - 任意の指定時間まで実行を一時停止します。
platform - 現在のプログラムを実行しているオペレーティングシステムを検出します。



2.10 特殊機種依存ルーチン

machine_func - インタプリタ内部の操作に特化した値を返す関数です。
machine_proc - インタプリタ内部の操作に特化した値を返さない手続き型関数です。



2.11 デバッグ

trace - トレース機能の有効と無効を動的に切り替えます。
profile - プロファイル機能の有効と無効を動的に切り替えます。



2.12 グラフィックとサウンド

後述のルーチンにより、各種情報をスクリーンに表示することができます。DOSでは多数のグラフィックスモードのうち1つをPCの表示スクリーンとして選択することができます。モードの解説はinclude\graphics.eの先頭を参照してください。利用可能なグラフィックスモードとして2つの基本的な方式があります。テキストモードではスクリーンを行単位で分割され、行ごとに特定の文字数(桁)を持ちます。ピクセルグラフィックスモードでは多数の点の列、または"ピクセル"によりスクリーンを分割されます。ピクセルごとに違う色を扱うことができます。テキストモードではテキストのみ表示でき、文字ごとに前景色と背景色を選択することができます。ピクセルグラフィックスモードでは線、円、点、さらにテキストを表示することができます。スクリーンからはみ出した任意のピクセルは安全にクリッピングされます。

DOS32向けにPCスピーカーで音を奏でるためのルーチンがあります。より洗練された音を奏でるためには、ジャック・デシェンス(Jacques Deschenes)によって開発されたSound Blasterライブラリを使用してください。これはEuphoriaウェブページより入手可能です。

次のルーチンは全てテキストおよびグラフィックスモードで動作します:

clear_screen - スクリーンを消去します。
position - カーソルの行と桁の位置を設定します。
get_position - 現在のカーソルの行と桁の位置を返します。
graphics_mode - 新規にピクセルグラフィックスモードかテキストモードを選択します。
video_config - 現在のモードのパラメータを返します。
scroll - テキストをスクロールアップ・ダウンします。
wrap - スクリーン右端のラップの制御を指定します。
text_color - テキストの前景色を設定します。
bk_color - テキストの背景色を設定します。
palette - 単一の色番号の色を変更します(DOS32)
all_palette - すべての色番号の色を変更します(DOS32)
get_all_palette - すべての色番号の色を取得します(DOS32)
read_bitmap - ビットマップファイル(.bmp)を読み込んでパレットと2次元シーケンスからなるピクセルを返します。
save_bitmap - パレットと2次元シーケンスからなるピクセルを与えてビットマップファイル(.bmp)作成します。
get_active_page - 現在の書き込み対象のページを返します(DOS32)
set_active_page - 現在の書き込み対象のページを変更します(DOS32)
get_display_page - 現在表示中のページを返します(DOS32)
set_display_page - 現在表示中のページを変更します(DOS32)
sound - PCのスピーカーから音を鳴らします(DOS32)

次のルーチンはテキストモード専用です:

cursor - カーソルの形状を選択します。
text_rows - テキストスクリーンの行数を設定します。
get_screen_char - スクリーンから半角一文字を取得します。
put_screen_char - スクリーンへ半角文字を一文字以上を出力します。
save_text_image - テキストスクリーンから矩形領域を保存します。
display_text_image - テキストイメージをテキストスクリーンに表示します。

次のルーチンはピクセルグラフィックスモード専用です(DOS32):

pixel - ピクセルの色またはピクセル自身を設置します。
get_pixel - ピクセルの色を読み出すかピクセルを設置します。
draw_line - グラフィックの点の並びをつないで線にします。
polygon - n辺形を描画します。
ellipse - 正円または楕円を描きます。
save_screen - スクリーンをビットマップファイル(.bmp)に保存します。
save_image - ピクセルグラフィックスクリーンから矩形領域を保存します。
display_image - ピクセルグラフィックスクリーンにイメージを表示します。



2.13 マシンレベルインタフェース

ハードウェア(マシン)にアクセスできる低レベルルーチンが下記に多数集められています。これら低レベルマシンインタフェースでメモリーを読み書きすることができます。またi386以降のマシン語ルーチンを作成・設定して呼び出すことができます。

これらを誤用したとき、Euphoriaの保護外であるため後述のルーチンのいくつかは安全ではありません。これによりプログラムまたはシステムのクラッシュが発生します。DOS32では不正なメモリーアドレスを参照したときはCauseWay DOSエクステンダにより問題なく補足され、スクリーンおよびcw.errファイルにマシンレベルのダンプ情報とエラーメッセージが出力されます。WIN32では、オペレーティングシステムが診断メッセージとレジスタ情報をポップアップウィンドウ(このプログラムは不正な処理を行ったので強制終了されます)のテキストボックス内に出力します。一般的にLinuxではセグメント違反を出力します。

注意事項:
プログラマーが安全ではないルーチンを含むコードのデバックを支援するためにmachine.eの代わりとしてsafe.eが提供されています。プログラムがあるディレクトリにeuphoria\include\safe.eをコピーしてsafe.emachine.eへ名前を変更すると、プログラムは安全なバージョンの低レベルルーチンを使用します。safe.eは不正なメモリー位置に書き込んでしまったなど大部分のエラーを捕まえることができます。どのようにして適切なプログラムを構成すべきかなどの使用法はsaf.eの先頭のコメントの手順を参照してください。

Euphoriaプログラマーがハードウェアおよびオペレーティングシステムの低レベル機能にアクセスするためにマシンレベルインターフェースルーチンは重要です。また、これはいくつかのアプリケーションでは必要不可欠です。

マシン語は手作業で記述するか、C言語などの他の言語のコンパイラの出力を逆アセンブルすることにより得ることができます。この用途のためにピート・エヴァレインはEuphoria用に"Mini-Assembler(小型アセンブラ)"を開発しました。これはアーカイブで配布されています。なお、作成したマシン語は32bitプロテクトモードで動作することを覚えておいてください。

peek - 1バイト以上のメモリーを読み出します。
peek4s - メモリーから符号付き(正数)4byte値を読み出します。
peek4u - メモリーから符号なし(負数)4byte値を読み出します。
poke - 1バイト以上の値をメモリーに書き込みます。
poke4 - 4バイトの値をメモリーに書き込みます。
mem_copy - メモリーブロックをコピーします。
mem_set - メモリーブロックに値を設定します。
call - マシン語ルーチンを呼び出します。
dos_interrupt - DOSソフトウェア割り込みルーチンを呼び出します(DOS32)
allocate - メモリーブロックを確保します。
free - メモリーブロックを開放します。
allocate_low - 下位メモリーブロックを確保します(1Mb以下のアドレス) (DOS32)
free_low - allocate_low()よって確保されたブロックを開放します(DOS32)
allocate_string - 末尾に0を付加した文字列をメモリーを確保します。
register_block - 保済みの外部メモリーブロックを登録します。
unregister_block - 確保済みの外部メモリーブロックの登録を解除します。
get_vector - 割り込みハンドラのアドレスを返します(DOS32)
set_vector - 割り込みハンドラのアドレスを設定します(DOS32)
lock_memory - 記憶領域がスワップアウトされないようにします(DOS32)
int_to_bytes - 整数を4バイトシーケンスに変換します。
bytes_to_int - 4バイトシーケンスを整数に変換します。
int_to_bits - 整数をビットからなるシーケンスへ変換します。
bits_to_int - ビットからなるシーケンスを整数に変換します。
atom_to_float64 - アトムを8バイトからなるIEEE浮動小数点数のシーケンスに変換します。
atom_to_float32 - アトムを4バイトからなるIEEE浮動小数点数のシーケンスに変換します
float64_to_atom - アトムを8バイトからなるIEEE浮動小数点数のシーケンスに変換します。
float32_to_atom - 32bit形式のIEEE浮動小数点数からなる4バイトシーケンスをアトムへ変換します。
set_rand - 特定値を反復可能にした乱数の列を生成できるように乱数生成器を設定します。
use_vesa - 強制的にVESAグラフィック規格を使用します(DOS32)
crash_file - Euphoriaがプログラムでエラーを検出したときにエラー診断情報を出力するファイルを指定します。
crash_message - Euphoriaがプログラムでエラーを検出したときに出力するメッセージを指定します。
crash_routine - Euphoriaがプログラムでエラーを検出したときに呼び出すルーチン(id)を指定します。



2.14 動的呼び出し

これらのルーチンはEuphoriaの手続きおよび関数をルーチン名ではなく、ルーチン識別子として知られている固有の整数値を指定することにより呼び出すことができます。

routine_id - Euphoriaルーチンの固有識別番号を取得します。
call_proc - ユーザ定義によるEuphoria手続きをルーチンIDを使用して呼び出します。
call_func - ユーザ定義によるEuphoria関数をルーチンIDを使用して呼び出します。



2.15 C言語の関数の呼び出し(WIN32/Linux)

WIN32およびLinuxのEuphoriaプログラミング方法の詳細についてはplatform.docを参照してください。

open_dll - Windowsダイナミックリンクライブラリ(.dllファイル)またはLinux共有ライブラリ(.soファイル)を開きます。
define_c_proc - 手続き型のC言語関数を定義します。これはVOID(値を返さない)型のC言語関数や値を返すC言語関数においてユーザプログラム側で受け取った返値を破棄する動作を仕様としたい場合に使用します。
define_c_func - 返値を返すC言語関数を定義します。これによりユーザプログラムで返値を受け取って使用することができます。
define_c_var - C言語変数メモリーアドレスを取得します。
c_proc - C言語関数を呼び出しますが、返値を取得しません。
c_func - C言語関数を呼び出して、返値を取得します。
call_back - Euphoriaのルーチンで使用するコールバックアドレスである32bitマシンアドレスを取得します。
message_box - はい/いいえ/キャンセルといったボタンを含むメッセージボックスを表示してのユーザからの応答を待ちます。
free_console - コンソールウィンドウを開放(削除)します。
instance - 現在のプログラムのインスタンスハンドルを取得します。



2.16 マルチタスク

これらルーチンの集合は複数の独立したタスクを構成します。タスクごとに固有実行対象の命令文と、固有のサブルーチンのコールスタック、固有のプライベート変数を一式保有しています。プログラムのローカルおよびグローバル変数は全タスクで共有されます。タスクがtask_yield()を呼ぶとタスクは動作を休止して、Euphoriaのスケジューラは次にどのタスクを実行するか決定します。

言語戦争デモプログラム lw.ex では多数の独立した船体の移動、魚雷、光線銃、その他を生成して戦闘をシミュレートするためにタスクを酷使します。関連事項としてtaskwire.exwはWindows向けのデモプログラムであり、news.exuはLinuxおよびFreeBSD向けのデモプログラムです。

task_clock_start - スケジューラのクロックを再起動します。
task_clock_stop - スケジューラのクロックを停止します。
task_create - タスクを新規作成します。
task_list - 全タスクのリストを取得します。
task_schedule - タスクを実行するためにスケジュールを行います。
task_self - 現在タスクのタスクIDを返します。
task_status - 現在のタスクの状態(動作、休止、停止)を取得します。
task_suspend - タスクを休止します。
task_yield - タスクの移譲制御を行い実行対象の新規タスクを選択します。

 

3. 全ルーチンリスト(アルファベット順) - AからBまで 続きます...