Vnano Engine の各種仕様
ここでは、Vnano Engine のメソッド群や、オプション項目の一覧など、各種仕様を掲載しています。
Vnano Engine のメソッド
下記は、Vnano Engine (org.vcssl.nano.VnanoEngine クラス) の全メソッドのリストです。
| 形式 | void activate() |
|---|---|
| 説明 |
アクティベーションを行い、このエンジンがスクリプトを実行可能な状態にします。 デフォルトでは、スクリプトを実行する直前のタイミングで、自動でアクティベーションが行われます。しかし、"AUTOMATIC_ACTIVATION_ENABLED" オプションが FALSE に設定されている場合には、自動アクティベーションは行われません。そのような場合には、このメソッドによって、適切なタイミングでアクティベーションを行う必要があります（詳細は "AUTOMATIC_ACTIVATION_ENABLED" オプションの説明を参照してください）。 なお、このアクティベーション処理では、接続されている全てのプラグインの初期化処理（各プラグインのinitializeForExecution() メソッドとして実装）が実行されます。従って、このメソッドの処理の所要時間は、接続されているプラグインの数や、個々のプラグインの実装に依存します。 |
| 引数 | なし |
| 戻り値 | なし |
| 例外 | VnanoException: 接続されているプラグインの初期化処理において、何らかのエラーが発生した場合に、VnanoException がスローされます。 |
| 形式 | void deactivate() |
|---|---|
| 説明 |
ディアクティベーションを行い、スクリプト実行が可能な状態を解除します。ある種の後始末的な処理も行われます。 デフォルトでは、スクリプトを実行した直後のタイミングで、自動でディアクティベーションが行われます。しかし、"AUTOMATIC_ACTIVATION_ENABLED" オプションが FALSE に設定されている場合には、自動ディアクティベーションは行われません。そのような場合には、このメソッドによって、適切なタイミングでディアクティベーションを行う必要があります（詳細は "AUTOMATIC_ACTIVATION_ENABLED" オプションの説明を参照してください）。 なお、このディアクティベーション処理では、接続されている全てのプラグインの終了時処理（各プラグインのfinalizeForTermination() メソッドとして実装）が実行されます。従って、このメソッドの処理の所要時間は、接続されているプラグインの数や、個々のプラグインの実装に依存します。 |
| 引数 | なし |
| 戻り値 | なし |
| 例外 | VnanoException: 接続されているプラグインの終了時処理において、何らかのエラーが発生した場合に、VnanoException がスローされます。 |
| 形式 | Object executeScript(String script) |
|---|---|
| 説明 | 引数に指定された式またはスクリプトコードを実行します。 |
| 引数 | script: 実行対象の式またはスクリプトコード |
| 戻り値 | 式、またはスクリプトコード内の最後の式文の評価値。 もしも評価値が無かった場合は null が返されます。 |
| 例外 | VnanoException: スクリプトの内容または実行過程にエラーが検出された場合にスローされます。 |
| 形式 | void terminateScript() |
|---|---|
| 説明 | 現在実行中のスクリプトの処理を、可能な限り早期に放棄して終了させます。 より正確には、スクリプトからコンパイルされた命令列を処理している、エンジン内の VirtualMachine が、現在実行中の命令(1個)の処理を完了した時点で, 残りの命令列の実行を放棄して終了します。これは通常は一瞬で終わりますが、プラグインが提供する外部関数などを実行している最中の場合は、その外部関数の処理が完了するまでの時間を要します。 なお、このメソッドを呼び出して実行を終了させた後に、再び（新規に）スクリプトを実行する際には、事前に resetTerminator() メソッドを呼び出す必要があります。前者の呼び出しから後者の呼び出しまでの間、実行が要求されたスクリプトは全てすぐに終了します。（この仕様により、このメソッドの呼び出しと新規実行リクエストが、別スレッドからシビアに競合したタイミングで行われた場合においても、スクリプトは確実に終了します。） |
| 引数 | なし |
| 戻り値 | なし |
| 例外 |
VnanoFatalException (非検査例外): isTerminatorEnabled() メソッドが false を返す状態で、 このメソッドがコールされた場合にスローされます。 なお、スクリプトの終了時に通常発生し得る例外（プラグインの終了時処理の失敗など）については、 このメソッド側ではなく、 実行中の executeScript(String script) メソッド側からスローされます。 このメソッドは、終了をリクエストする事自体に失敗した場合に例外をスローします。 |
| 形式 | boolean isTerminatorEnabled() |
|---|---|
| 説明 | スクリプトを途中で終了させるための機能（ターミネーター）が、有効化されているかどうかを返します。 内部的には、このメソッドは「 TERMINATOR_ENABLED 」オプションの設定値を読んで返します。 |
| 引数 | なし |
| 戻り値 | スクリプトを途中で終了させるための機能（ターミネーター）が、有効化されている場合に true が返されます。 |
| 例外 | なし |
| 形式 | void resetTerminator() |
|---|---|
| 説明 | terminateScript() メソッドによって終了させたエンジンを、 再び(新規)スクリプト実行可能な状態に戻します。 |
| 引数 | なし |
| 戻り値 | なし |
| 例外 | VnanoFatalException (非検査例外): isTerminatorEnabled() メソッドが false を返す状態で、このメソッドがコールされた場合にスローされます。 |
| 形式 | void connectPlugin(String bindingName, Object plugin) |
|---|---|
| 説明 | 外部関数/変数などを提供する、各種のプラグインを接続します。 |
| 引数 | bindingName: 接続されるプラグインが提供する変数/関数/名前空間の、スクリプト内での名前。なお、"___VNANO_AUTO_KEY" を指定する事で、有効な値の指定を自動で行う事もできます。 plugin: 外部関数/変数などを提供するプラグイン。型は java.lang.reflect.Field や Method、 java.lang.Class や Object、 および org.vcssl.connect.ExternalVariableConnectorInterface1、 ExternalFunctionConnectorInterface1、 ExternalNamespaceConnectorInterface1、 PermissionAuthorizerConnectorInterface1 がサポートされています。 |
| 戻り値 | なし |
| 例外 | VnanoException: サポートされていないインターフェースの使用や、データ型の互換性などの原因により、 プラグインの接続に失敗した場合にスローされます。 |
| 形式 | void disconnectAllPlugins() |
|---|---|
| 説明 | 全てのプラグインの接続を解除します。 |
| 引数 | なし |
| 戻り値 | なし |
| 例外 | VnanoException: プラグインの終了時処理でエラーが発生した場合にスローされます。 |
| 形式 | void includeLibraryScript(String libraryScriptName, String libraryScriptContent) |
|---|---|
| 説明 | 実行対象スクリプトの先頭に "include" される, ライブラリスクリプトを追加します。 |
| 引数 | libraryScriptName: ライブラリスクリプトの名称 (エラーメッセージ等で使用されます) libraryScriptContent: ライブラリスクリプトのコード内容 |
| 戻り値 | なし |
| 例外 | VnanoException: ライブラリに異常があった場合にスローされます。 |
| 形式 | void unincludeAllLibraryScripts() |
|---|---|
| 説明 | 全てのライブラリスクリプトの include 登録を解除します。 |
| 引数 | なし |
| 戻り値 | なし |
| 例外 | VnanoException: 現状ではスローされませんが、将来的な互換性維持のためのために catch する必要があります。 |
| 形式 | void setOptionMap(Map<String,Object> optionMap) |
|---|---|
| 説明 | オプションの名前と値を格納するマップ（オプションマップ）によって, オプションを設定します。 オプションマップの型は Map<String,Object> で、オプション項目の名前をキーにします。項目の一覧と詳細は [オプション項目](#options) のセクションを参照してください。 |
| 引数 | optionMap: オプションの名前と値を格納するマップ（オプションマップ） |
| 戻り値 | なし |
| 例外 | VnanoException: オプションの指定内容が正しくなかった場合にスローされます。 |
| 形式 | boolean hasOptionMap() |
|---|---|
| 説明 | 「getOptionMap() メソッドがマップを返せるかどうか」を判定します。 |
| 引数 | なし |
| 戻り値 | getOptionMap() メソッドがマップを返せる場合に true が返されます。 |
| 例外 | なし |
| 形式 | Map<String,Object> getOptionMap() |
|---|---|
| 説明 | オプションの名前と値を格納するマップ（オプションマップ）を取得します。 |
| 引数 | なし |
| 戻り値 | オプションの名前と値を格納するマップ（オプションマップ） |
| 例外 | VnanoFatalException (非検査例外): hasOptionMap() メソッドが false を返す状態で、このメソッドがコールされた場合にスローされます。 |
| 形式 | void setPermissionMap(Map<String, String> permissionMap) |
|---|---|
| 説明 | パーミッション項目の名前と値を格納するマップ（パーミッションマップ）によって, 各パーミッションの値を設定します。 パーミッションマップの型は Map<String,String> で、パーミッション項目の名前をキーにします。項目の一覧と詳細は [パーミッション項目](#permissions) のセクションを参照してください。 |
| 引数 | permissionMap: パーミッション項目の名前と値を格納するマップ（パーミッションマップ） |
| 戻り値 | なし |
| 例外 | VnanoException: パーミッションの指定内容が正しくなかった場合にスローされます。 |
| 形式 | boolean hasPermissionMap() |
|---|---|
| 説明 | 「getPermissionMap() メソッドがマップを返せるかどうか」を判定します。 |
| 引数 | なし |
| 戻り値 | getPermissionMap() メソッドがマップを返せる場合に true が返されます。 |
| 例外 | なし |
| 形式 | Map<String,String> getPermissionMap() |
|---|---|
| 説明 | パーミッション項目の名前と値を格納するマップ（パーミッションマップ）を取得します。 |
| 引数 | なし |
| 戻り値 | パーミッション項目の名前と値を格納するマップ（パーミッションマップ） |
| 例外 | VnanoFatalException (非検査例外): hasPermissionMap() メソッドが false を返す状態で、このメソッドがコールされた場合にスローされます。 |
| 形式 | boolean hasPerformanceMap() |
|---|---|
| 説明 | 「getPerformanceMap() メソッドがマップを返せるかどうか」を判定します。 内部的には、このメソッドは「 PERFORMANCE_MONITOR_ENABLED 」オプションの設定値を読んで返します。 |
| 引数 | なし |
| 戻り値 | getPerformanceMap() メソッドがマップを返せる場合に true が返されます。 |
| 例外 | なし |
| 形式 | Map<String, Object> getPerformanceMap() |
|---|---|
| 説明 |
パフォーマンスモニタの計測項目名と値を格納するマップ（パフォーマンスマップ）を取得します。 なお、スクリプトを実行していない時や, 実行開始後でも性能を有効に計測可能な段階にまだ達していない時など、一部の計測値が存在しないタイミングでは、それらの値は戻り値のパフォーマンスマップ内には格納されません。そのような「欠けた」または「空の」パフォーマンスマップが有り得る事には、計測値を取り出す際に留意する必要があります。 |
| 引数 | なし |
| 戻り値 | パフォーマンスモニタの計測項目名と値を格納するマップ（パフォーマンスマップ） |
| 例外 | VnanoFatalException (非検査例外): hasPerformanceMap() メソッドが false を返す状態で、このメソッドがコールされた場合にスローされます。 |
オプション項目
下記は、Vnano Engine で設定可能なオプション項目のリストです。なお、項目名の型は全て「 String 」です。
| 項目名 | 値の型 | デフォルト値 | 説明 |
|---|---|---|---|
| LOCALE | java.util. Locale |
環境依存 | エラーメッセージの言語を決めるロケールです。 |
| MAIN_SCRIPT_NAME | String | "main script" | 実行対象スクリプトの名前です。 |
| MAIN_SCRIPT_DIRECTORY | String | "." | 実行対象スクリプトがあるディレクトリ（フォルダ）のパスです。 |
| EVAL_INT_LITERAL_AS_FLOAT | Boolean | FALSE | 実行/評価対象の式やスクリプト（ライブラリ以外）内に出現する整数リテラルを、float型と見なして扱うオプションです。 |
| EVAL_ONLY_EXPRESSION | Boolean | FALSE | 実行対象のスクリプト（ライブラリ以外）内で使用可能な文を、式文のみに制限するオプションです。 |
| EVAL_ONLY_FLOAT | Boolean | FALSE | 実行対象のスクリプト（ライブラリ以外）内で使用可能な演算子やオペランドの型を、float 型のみに制限するオプションです。 |
| ACCELERATOR_ENABLED | Boolean | TRUE | VM内の高速な仮想プロセッサ実装である 「 Accelerator（org.vcssl.nano.vm.accelerator.Accelerator）」 の有効/無効を切り替えるためのオプションです。 |
| ACCELERATOR_OPTIMIZATION_LEVEL | Integer | 3 | Accelerator 内での、処理の最適化レベルを指定するためのオプションです。指定する値は下記の通りです： 0: 最適化を行いません。 1: データアクセスのオーバーヘッドを削減する最適化（演算値のキャッシュなど）を行います。 2: 上記に加えて、コードの構造が概ね保たれるレベルでの、局所的な命令列の最適化（複数の命令を並べ替えて1個に結合するなど）を行います。 3: 上記に加えて、コードの大きな構造変更を伴うレベルの最適化（インライン展開など）を行います。 |
| TERMINATOR_ENABLED | Boolean | FALSE | 実行中のスクリプトを終了させる機能の、有効/無効を切り替えるためのオプションです。 このオプションを有効化すると、スクリプトを「 実行途中でエンジン操作によって 」終了させる事が可能になる代わりに、処理速度が若干低下してしまう可能性があります。多くの場合は、恐らくほぼ気付かない程度の速度差しか生じませんが、高度に最適化された数値演算系スクリプトなどでは 10% 程度、場合によってはそれ以上の速度低下が見込まれます。なお、このオプションの有効/無効に関わらず、スクリプトの処理が全て終わった際や、スクリプト内でエラーが発生した際、またはスクリプト内で exit() 関数が呼ばれた際などには、スクリプト実行は(必然的に)終了する事にご注意ください。 |
| PERFORMANCE_MONITOR_ENABLED | Boolean | FALSE | 実測性能計測に用いるパフォーマンスモニタの有効/無効を切り替えるためのオプションです。 このオプションを有効化すると、エンジンの実測性能値を取得可能になる代わりに、処理速度が若干低下してしまう可能性があります。多くの場合は, 恐らくそれほど大きな速度差は生じませんが、高度に最適化された数値演算系スクリプトなどでは 25% 程度、場合によってはそれ以上の速度低下が見込まれます。 |
| DUMPER_ENABLED | Boolean | FALSE | コンパイラやVM内などでの状態や中間表現をダンプするためのオプションです。 |
| DUMPER_TARGET | String | "ALL" | ダンプ対象を指定します。値は下記の通りです： "ALL": 全ての内容をダンプします。 "INPUTTED_CODE": 入力されたままの形のスクリプトコードをダンプします。 "PREPROCESSED_CODE": コメント削除などの前処理が行われたスクリプトコードをダンプします。 "TOKEN": 字句解析結果のトークン配列をダンプします。LexicalAnalyzer の出力値検証用です。 "PARSED_AST": 構文解析結果の AST（抽象構文木）をダンプします。Parser の出力値検証用です。 "ANALYZED_AST": 意味解析結果の AST（抽象構文木）をダンプします。SemanticAnalyzer の出力値検証用です。 "ASSEMBLY_CODE": コンパイル結果の、VM用中間コードである「VRILコード」をダンプします。CodeGenerator の出力検証用です。 "OBJECT_CODE": アセンブル結果の「VMオブジェクトコード（未最適化）」をダンプします。Assembler の出力検証用です。 "ACCELERATOR_CODE": Accelerator での実行用の命令列（最適化済み）をダンプします。AcceleratorOptimizationUnit の出力検証用です。 "ACCELERATOR_STATE": Accelerator の内部状態をダンプします。各演算ユニットへのディスパッチ状況などの検証用です。 |
| DUMPER_STREAM | java.io. PrintStream |
System.out | ダンプの出力に用いるストリームを指定します。 |
| RUNNING_ENABLED | Boolean | TRUE | スクリプトを実行するかしないかを指定するためのオプションです。 このオプションは、コンパイルした結果をデバッグ用にダンプしつつ、実行はしたくない場合などに有用かもしれません。 |
| AUTOMATIC_ACTIVATION_ENABLED | Boolean | TRUE | スクリプトの実行直前と直後に、自動的にエンジンをアクティベーション/ディアクティベーションする機能（自動アクティベーション）の、有効/無効を切り替えるオプションです。 このオプションはデフォルトで有効化されているため、いつでも自由なタイミングでスクリプトを実行する事ができます。半面、エンジンのアクティベーションにはある程度のオーバーヘッドコストを伴います。特に、反復的かつ高頻度でスクリプトを実行し続けるような場合、このオプションが有効になっていると、アクティベーションのオーバーヘッドコストが頻発し、処理速度が大幅に低下してしまう可能性があります。そのような場合には、このオプションを無効化して、適切なタイミング（ある程度まとまった回数の連続実行の前後など）に手動でエンジンをアクティベーション/ディアクティベーションしてください。 |
| UI_MODE | String | "GUI" | 値の入出力などに用いるユーザーインターフェースの形式を指定します。 値は "GUI" か "CUI" を指定します。デフォルトは "GUI" ですが、コマンドラインモードでは "CUI" に自動設定されます。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| ENVIRONMENT_EOL | String | 環境依存 | 環境における、デフォルトの改行コードを指定します。 このオプションは、環境依存の値を提供するプラグインが接続されている場合に、それらによって参照されます。 |
| FILE_IO_EOL | String | 環境依存 | ファイルの入出力に用いる、デフォルトの改行コードを指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| TERMINAL_IO_EOL | String | 環境依存 | 端末との入出力に用いる、デフォルトの改行コードを指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| FILE_IO_ENCODING | String | "UTF-8" | スクリプト内でのファイルの読み書きに用いる、デフォルトの文字コード名を指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| STDIN_STREAM | Java.io. InputStream |
System.in | TERMINAL_IO_UI が "CUI" に設定されている際に、標準入力に用いるストリームを指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| STDOUT_STREAM | Java.io. PrintStream |
System.out | TERMINAL_IO_UI が "CUI" に設定されている際に、標準出力に用いるストリームを指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
| STDERR_STREAM | Java.io. PrintStream |
System.err | TERMINAL_IO_UI が "CUI" に設定されている際に、標準エラー出力に用いるストリームを指定します。 このオプションは、入出力系のプラグインが接続されている場合に、それらによって参照されます。 |
パーミッション項目
下記は、設定可能なパーミッション項目のリストです。 項目名と値の型は全て「 String 」で、値は "ALLOW"、"DENY"、"ASK" から選んで指定してください。 なお、"ASK" を指定すると、「 ユーザーに許可/拒否を訪ねて決定する 」という挙動になります。デフォルトでは、全ての項目の値は "DENY" に設定されています。
| 項目名 | 説明 |
|---|---|
| PROGRAM_EXIT | 現在実行中のプログラム（スクリプト）を終了させる事に対するパーミッションです。 |
| PROGRAM_RESET | 現在実行中のプログラム（スクリプト）をリセット/再実行する事に対するパーミッションです。 |
| PROGRAM_CHANGE | 現在実行中のプログラム（スクリプト）を変更する事に対するパーミッションです。 |
| SYSTEM_PROCESS | オペレーティングシステム等を介して、コマンドや別のプログラム等を実行する事に対するパーミッションです。 |
| DIRECTORY_CREATE | ディレクトリ（フォルダ）の新規作成に対するパーミッションです。 |
| DIRECTORY_DELETE | ディレクトリ（フォルダ）の削除に対するパーミッションです。 |
| DIRECTORY_LIST | ディレクトリ（フォルダ）内のファイル一覧取得に対するパーミッションです。 |
| FILE_CREATE | ファイルの新規作成に対するパーミッションです。 |
| FILE_DELETE | ファイルの削除に対するパーミッションです。 |
| FILE_WRITE | ファイルへの書き込みに対するパーミッションです。 |
| FILE_READ | ファイルからの読み込みに対するパーミッションです。 |
| FILE_OVERWRITE | ファイルへの上書きに対するパーミッションです。 |
| FILE_INFORMATION_CHANGE | ファイルの情報変更（更新日時など）に対するパーミッションです。 |
| ALL | 「全てのパーミッション項目」を表すメタ項目名です。 |
| NONE | 「パーミッション項目が無い事」を表すメタ項目名です。 |
| DEFAULT | 「全パーミッション項目における未設定時のデフォルト値」を保持するメタ項目名です。 明示的に設定されていないパーミッション項目には, デフォルト値（例えば "DENY" など）が自動的に設定されます。このデフォルト値は、このメタパーミッション項目「 DEFAULT 」の値を変える事で変更できます。例えばこの「 DEFAULT 」項目に値 "ASK" を設定すると、スクリプトエンジンは、未設定のパーミッションが要求された際に、ユーザーに許可/拒否を尋ねるようになります。 |
