Squirrel_Lang/ch4_1

Last-modified: 2011-08-09 (火) 11:22:43

第4章 APIリファレンス

仮想マシン

sq_close 

void sq_close(HSQUIRRELVM v);

SquirrelのVMとすべての関連したフレンドVMを解放する。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_getforeignptr 

SQUserPointer sq_getforeignptr(HSQUIRRELVM v);

VMインスタンスの外部(foreign)ポインタを返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

現在のVMの外部(foreign)ポインタ

sq_getprintfunc 

SQPRINTFUNCTION sq_getprintfunc(HSQUIRRELVM v);

指定されたVMにおける、現在の表示関数を返す(sq_setprintfuncも参照せよ)。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

SQPRINTFUNCTIONへのポインタ。ただし関数はセットされていないならNULL。

sq_getvmstate 

SQInteger sq_getvmstate(HSQUIRRELVM v);

VMの実行状態を返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

VMの状態を示す整数値。次の定数が定義されている。

  • SQ_VMSTATE_IDLE
  • SQ_VMSTATE_RUNNING
  • SQ_VMSTATE_SUSPENDED

sq_move 

void sq_move(HSQUIRRELVM dest, HSQUIRRELVM src, SQInteger idx);

移動元VMのスタック上のインデックス位置にあるオブジェクトを、移動先VMのスタックへpushする。

引数:

  • HSQUIRRELVM dest
    移動先のVM
  • HSQUIRRELVM src
    移動元のVM
  • SQInteger idx
    移動対象値の移動元スタック上でのインデックス

sq_newthread 

HSQUIRRELVM sq_newthread(HSQUIRRELVM friendvm, SQInteger initialstacksize);

第1引数として渡されたVMのフレンドVMを新たに作成し、それをスレッドオブジェクトとしてスタックにpushする。

引数:

  • HSQUIRRELVM friendvm
    VM
  • SQInteger initialstacksize
    スロットのスタックサイズ(オブジェクト数)

戻り値:

新規VMへのポインタ

注意:

デフォルトではルートテーブルは第1引数として渡されたVMと共有される。
新規VMの生存期間はスタックにpushされた「スレッド」オブジェクトに束縛され、
通常のSquirrelオブジェクトと同様に振る舞う。

sq_open 

HSQUIRRELVM sq_open(SQInteger initialstacksize);

新たな実行スタックを持つSquirrel VMの新しいインスタンスを作成する。

引数:

  • SQInteger initialstacksize
    スロットのスタックサイズ(オブジェクト数)

戻り値:

Squirrel VMへのハンドル

注意:

返されたVMはsq_releasevmによって解放しなければならない。

sq_pushregistrytable 

SQRESULT sq_pushregistrytable(HSQUIRRELVM v);

レジストリテーブルをスタックにpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_pushroottable 

SQRESULT sq_pushroottable(HSQUIRRELVM v);

現在のルートテーブルをスタックにpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_seterrorhandler 

void sq_seterrorhandler(HSQUIRRELVM v);

スタックからクロージャまたはネイティブクロージャをpopし、それを実行時エラーハンドラとしてセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

注意:

エラーハンドラはフレンドVMに共有される。

sq_setforeignptr 

void sq_setforeignptr(HSQUIRRELVM v, SQUserPointer p);

特定のVMインスタンスの外部(foreign)ポインタをセットする。
外部ポインタは、VMに関連付けられた任意のユーザ定義のポインタである(デフォルトでは値ID0)。
このポインタはVMによって無視される。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQUserPointer p
    セットされるべきポインタ

sq_setprintfunc 

void sq_setprintfunc(HSQUIRRELVM v, SQPRINTFUNCTION printfunc);

VMの表示関数をセットする。この関数は組み込み関数::print()で文字列を出力するのに用いられる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQPRINTFUNCTION printfunc
    表示関数へのポインタ。出力を無効するならNULL

注意:

表示関数は次のプロトタイプである: void printfunc(HSQUIRRELVM v, const SQChar *s, ...)

sq_setroottable 

void sq_setroottable(HSQUIRRELVM v);

テーブルをスタックからpopしてそれをルートテーブルとしてセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_suspendvm 

HRESULT sq_suspendvm(HSQUIRRELVM v);

指定したVMの実行を中断する。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

SQRESULT
C関数はこの戻り値を返さなければならない(例参照)

注意:

C関数の式を返す場合にのみsq_resultは呼び出すことができる。
Cの呼び出しやメタメソッドによって既に中断されているときには、この関数は失敗する。

例 

SQInteger suspend_vm_example(HSQUIRRELVM v)
{
    return sq_suspendvm(v);
}

sq_wakeupvm 

HRESULT sq_wakeupvm(HSQUIRRELVM v, SQBool resumedret, SQBool retval, SQBool raiseerror);

前回中断されたVMの実行を再開する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool resumedret
    trueなら、その関数はスタックから値をひとつpopし、それを(前回VMを中断させた)関数の戻り値として使用する。
  • SQBool retval
    trueなら、この関数の戻り値をスタックにpushする
  • SQBool raiseerror
    trueなら、呼び出し実行中に実行時エラーが発生した場合は、VMがエラーハンドラを呼び出すようにする

戻り値:

HRESULT

コンパイラ

sq_compile 

SQRESULT sq_compile(HSQUIRRELVM v, HSQLEXREADFUNC read, SQUserPointer p, const SQChar * sourcename, SQBool raiseerror);

Squirrelのプログラムをコンパイルする。
もしそれが成功したなら、コンパイルされたスクリプトを関数としてスタックにpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • HSQLEXREADFUNC read
    コンパイラにプログラムを与えるための読み込み関数へのポインタ
  • SQUserPointer p
    呼び出しごとに、コンパイラによって読み込み関数へ渡されるユーザ定義ポインタ
  • const SQChar * sourcename
    プログラムのシンボル名(実行時エラーをより意味あるものにするためのみに使用される)
  • SQBool raiseerror
    この値がtrueなら、エラー時にコンパイルエラーハンドラが呼び出される

戻り値:

SQRESULT
もしsq_compileが失敗したなら、スタックにはなにもpushされない。

注意

エラー時に、この関数はsq_setcompilererrorhandlerによってセットされた関数を呼び出す。

sq_compilebuffer 

SQRESULT sq_compilebuffer(HSQUIRRELVM v, const SQChar* s, SQInteger size, const SQChar * sourcename, SQBool raiseerror);

メモリバッファからSquirrelプログラムをコンパイルする。
もしそれが成功したなら、コンパイルされたスクリプトを関数としてスタックにpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • const SQChar* s
    コンパイルされるバッファへのポインタ
  • SQInteger size
    引数 s のバッファ文字数
  • const SQChar * sourcename
    プログラムのシンボル名(実行時エラーをより意味あるものにするためのみに使用される)
  • SQBool raiseerror
    この値がtrueなら、エラー時にコンパイルエラーハンドラが呼び出される

戻り値:

SQRESULT
もしsq_compileが失敗したなら、スタックにはなにもpushされない。

注意

エラー時に、この関数はsq_setcompilererrorhandlerによってセットされた関数を呼び出す。

sq_enabledebuginfo 

void sq_enabledebuginfo(HSQUIRRELVM v, SQBool enable);

コンパイル時のデバッグ行情報生成の有効/無効を設定する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool enable
    trueならデバッグ情報生成を有効にする。この値が0なら無効にする。

注意

この関数はすべてのスレッドに影響する

sq_notifyallexceptions 

void sq_notifyallexceptions(HSQUIRRELVM v, SQBool enable);

ハンドルされた例外のエラーコールバック通知の有効/無効を設定する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool enable
    trueならハンドルされた例外のエラーコールバック通知が有効になる。

注意

もし例外がハンドルされない(try/catchトラップがコールスタック中に存在しない)なら、デフォルトではVMはエラーコールバックのみを呼び出す。
もしnotifyallexceptionsが有効なら、たとえtry/catchブロック中であっても、どのような例外に対してVMはエラーコールバックを呼び出す。
この機能はデバッガの実装には有用である。

sq_setcompilererrorhandler 

void sq_setcompilererrorhandler(HSQUIRRELVM v, SQCOMPILERERROR f);

コンパイラエラーハンドラ関数をセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQCOMPILERERROR f
    エラーハンドラ関数へのポインタ

注意

もし引数 f がNULLなら、コンパイルエラーが発生しても関数は呼び出されない。
コンパイラエラーハンドラはフレンドVM間で共有される。

スタック操作

sq_cmp 

SQInteger sq_cmp(HSQUIRRELVM v);

スタックの2つのオブジェクトを比較する。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

> 0if obj1 > obj2
== 0if obj1 == obj2
< 0if obj1 < obj2

sq_gettop 

SQInteger sq_gettop(HSQUIRRELVM v);

スタックトップのインデックスを返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

スタックトップのインデックスを示す整数値

sq_pop 

void sq_pop(HSQUIRRELVM v, SQInteger nelementstopop);

スタックからn個の要素をpopする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger nelementstopop
    popする要素数

sq_poptop 

void sq_poptop(HSQUIRRELVM v);

スタックから1個の要素をpopする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_push 

void sq_push(HSQUIRRELVM v, SQInteger idx);

スタックのインデックス位置にある値をpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    pushする値のスタックのインデックス

sq_remove 

void sq_remove(HSQUIRRELVM v, SQInteger idx);

スタックの任意の位置にある要素を削除する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    削除する要素のインデックス

sq_reservestack 

void sq_reservestack(HSQUIRRELVM v, SQInteger nsize);

スタック領域の残りが少なくとも指定サイズはあることを保証する。
もしスタックがそれより小さければ、自動的に大きくする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger nsize
    要求スタックサイズ

sq_settop 

void sq_settop(HSQUIRRELVM v, SQInteger v);

スタックをリサイズする。
もし新しいトップが現在のトップより大きければ、関数はnullをpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger v
    新しいトップインデックス

オブジェクトの生成と操作

sq_bindenv 

SQRESULT sq_bindenv(HSQUIRRELVM v, SQInteger idx);

スタックからオブジェクト(テーブル、インスタンス、クラスのどれかでなければならない)をpopし、
スタック上の指定位置にあるクロージャを複製(クローン)し、
popしたオブジェクトをクローンクロージャの環境としてセットする。
その新しいクローンクロージャはスタックトップへpushされる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    ターゲットクロージャのインデックス

戻り値:

SQRESULT

注意:

クローンクロージャは環境オブジェクトを弱参照で保持する。

sq_createinstance 

SQRESULT sq_createinstance(HSQUIRRELVM v, SQInteger idx);

スタック上のインデックス位置にあるクラスのインスタンスを作成する。
この新しいクラスインスタンスはスタックトップにpushされる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    ターゲットクラスのインデックス

戻り値:

SQRESULT

注意:

この関数はインスタンスのコンストラクタを呼び出さない。
インスタンスを作成して自動的にコンストラクタを呼び出すには、代わりにsq_callを使用しなければならない。

sq_getbool 

SQRESULT sq_getbool(HSQUIRRELVM v, SQInteger idx, SQBool * b);

スタック上の指定位置にある真偽値を得る。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQBool * b
    値が格納される真偽値へのポインタ

戻り値:

SQRESULT

sq_getclosureinfo 

SQRESULT sq_getclosureinfo(HSQUIRRELVM v, SQInteger idx, SQUnsignedInteger * nparams, SQUnsignedInteger * nfreevars);

Squirrelのクロージャから引数の数と自由変数の数を調べる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    ターゲットクロージャのインデックス
  • SQUnsignedInteger * nparams
    引数の数が格納される非符号化整数へのポインタ
  • SQUnsignedInteger * nfreevars
    自由変数の数が格納される非符号化整数へのポインタ

戻り値:

SQRESULT

sq_getfloat 

SQRESULT sq_getfloat(HSQUIRRELVM v, SQInteger idx, SQFloat * f);

スタック上の指定位置にある浮動小数点型の値を得る。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQFloat * f
    値が格納される浮動小数点数へのポインタ

戻り値:

SQRESULT

sq_getinstanceup 

SQRESULT sq_getinstanceup(HSQUIRRELVM v, SQInteger idx, SQUserPointer * up, SQUSerPointer typetag);

クラスインスタンスのユーザポインタをスタックの指定された位置から取得する。
もし、引数'typetag'が0ではないなら、この関数はインスタンスのクラスやベースクラスが、指定されたタグでタグ付けられたものかどうかをチェックする。
もしそうでないなら、関数は失敗する。'typetag'が0ならタグチェックは行われない。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタックのインデックス
  • SQUserPointer * up
    結果が渡されるユーザポインタへのポインタ
  • SQUSerPointer typetag
    型チェックを行うべき型。これが0なら無視される

戻り値:

SQRESULT

sq_getinteger 

SQRESULT sq_getinteger(HSQUIRRELVM v, SQInteger idx, SQInteger * i);

スタックの指定位置にある整数の値を取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQInteger * i
    値を格納する整数へのポインタ

戻り値:

SQRESULT

sq_getscratchpad 

SQChar * sq_getscratchpad(HSQUIRRELVM v, SQInteger minsize);

少なくともminsizeと同じ大きさを持つメモリバッファへのポインタを返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger minsize
    スクラッチパッドバッファへの要求サイズ

注意:

バッファは次のsq_getscratchpad呼び出しがあるまで有効である。

sq_getsize 

SQInteger sq_getsize(HSQUIRRELVM v, SQInteger idx);

スタックの指定位置にある値のサイズを取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス

戻り値:

スタック上のインデックス位置の値のサイズ

注意:

この関数は文字列、配列、テーブル、ユーザデータに対してのみ動作する。
もしこれらの型でないなら、この関数は-1を返す。

sq_getstring 

SQRESULT sq_getstring(HSQUIRRELVM v, SQInteger idx, const SQChar ** c);

スタック上の指定位置にある文字列へのポインタを取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • const SQChar ** c
    文字列へのポインタを格納するポインタへのポインタ

戻り値:

SQRESULT

sq_getthread 

SQRESULT sq_getthread(HSQUIRRELVM v, SQInteger idx, HSQUIRRELVM* v);

スタック上の指定位置にあるスレッドへのポインタを取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • HSQUIRRELVM* v
    スレッドポインタを格納する変数へのポインタ

戻り値:

SQRESULT

sq_gettype 

SQObjectType sq_gettype(HSQUIRRELVM v, SQInteger idx);

スタック上の指定位置にある値の型を返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス

戻り値:

スタック上の指定位置にある値の型

sq_gettypetag 

SQRESULT sq_gettypetag(HSQUIRRELVM v, SQInteger idx, SQUserPointer * typetag);

スタック上の指定位置にあるオブジェクト(ユーザデータもしくはクラス)のタイプタグを取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQUserPointer * typetag
    タグを格納する変数へのポインタ

戻り値:

SQRESULT

注意:

この関数はインスタンスに対しても機能する。
もし、対象オブジェクトがインスタンスであるなら、ベースクラスのタイプタグがフェッチされる。

sq_getuserdata 

SQRESULT sq_getuserdata(HSQUIRRELVM v, SQInteger idx, SQUserPointer * p, SQUserPointer * typetag);

スタック上の指定位置にあるユーザデータの値へのポインタを取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQUserPointer * p
    ユーザデータのペイロードを指すユーザポインタへのポインタ
  • SQUserPointer * typetag
    ユーザデータタグを格納するSQUserPointerへのポインタ(sq_settypetagを参照せよ)。この引数はnullにできる

戻り値:

SQRESULT

sq_getuserpointer 

SQRESULT sq_getuserpointer(HSQUIRRELVM v, SQInteger idx, SQUserPointer * p);

スタック上の指定位置にあるユーザポインタの値を取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQUserPointer * p
    値を格納するユーザデータへのポインタ

戻り値:

SQRESULT

sq_newarray 

void sq_newarray(HSQUIRRELVM v, SQInteger size);

配列を作成し、それをスタック上にpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger size
    作成される配列のサイズ

sq_newclass 

SQRESULT sq_newclass(HSQUIRRELVM v, SQBool hasbase);

新しいクラスオブジェクトを作成する。
もし引数hasbaseが0でないなら、この関数はスタックからクラスをひとつpopし、新クラスをそのクラスから継承させる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool hasbase
    もし、引数がtrueなら、この関数はスタックトップにベースクラスがあるとみなす

戻り値:

SQRESULT

sq_newclosure 

void sq_newclosure(HSQUIRRELVM v, SQFUNCTION func, SQInteger nfreevars);

新しいネイティブクロージャを作成し、そのクロージャ用の自由変数としてn個分をスタックからpopする。
そして、スタックへネイティブクロージャをpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • HSQFUNCTION func
    ネイティブ関数へのポインタ
  • SQInteger nfreevars
    自由変数の数(0も可能)

sq_newtable 

void sq_newtable(HSQUIRRELVM v);

新しいテーブルを作成して、それをスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_newuserdata 

SQUserPointer sq_newuserdata(HSQUIRRELVM v, SQUnsignedInteger size);

新しいユーザデータを作成し、それをスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQUnsignedInteger size
    作成されるユーザデータのサイズ(バイト)

sq_pushbool 

void sq_pushbool(HSQUIRRELVM v, SQBool b);

真偽値をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool b
    pushされる真偽値(SQTrueまたはSQFalse)

sq_pushfloat 

void sq_pushfloat(HSQUIRRELVM v, SQFloat f);

浮動小数点数をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQFloat f
    pushされる浮動小数点数

sq_pushinteger 

void sq_pushinteger(HSQUIRRELVM v, SQInteger n);

整数をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger n
    pushされる整数

sq_pushnull 

void sq_pushnull(HSQUIRRELVM v);

nullをスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_pushstring 

void sq_pushstring(HSQUIRRELVM v, const SQChar * s, SQInteger len);

文字列をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • const SQChar * s
    pushされる文字列へのポインタ
  • SQInteger len
    文字列sの長さ

注意:

もし引数lenが0未満であるなら、VMはstrlen(s)によって文字列長を計算する。

sq_pushuserpointer 

void sq_pushuserpointer(HSQUIRRELVM v, SQUserPointer p);

ユーザポインタをスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQUserPointer p
    pushされるユーザポインタ

sq_setinstanceup 

SQRESULT sq_setinstanceup(HSQUIRRELVM v, SQInteger idx, SQUserPointer up);

クラスインスタンスのユーザポインタをスタックの指定位置にセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQUserPointer up
    任意のユーザポインタ

戻り値:

SQRESULT

sq_setnativeclosurename 

SQRESULT sq_setnativeclosurename(HSQUIRRELVM v, SQInteger idx, const SQChar * name);

スタック上のidxの位置にあるネイティブクロージャの名前を設定する。
ネイティブクロージャの名前は純粋にデバグ用である。
コールスタック上にこのクロージャがあるときは、
この名前が関数sq_stackinfosを通して検索される。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    ネイティブクロージャのスタック位置
  • const SQChar * name
    設定する関数名

戻り値:

SQRESULT

sq_setparamscheck 

SQRESULT sq_setparamscheck(HSQUIRRELVM v, SQInteger nparamscheck, const SQChar * typemask);

スタックトップにあるネイティブクロージャのための、引数の検証スキームを設定する。
関数に受け入れることが可能な引数の数と(オプションとして)その型の検証を行うことができる。
sq_setparamscheckによって設定された引数スキーマと関数呼び出しが合致しないときは例外が投げられる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger nparamscheck
    引数の数を検証するかどうかを決定する。隠れ引数であるthisを含む。
    値内容
    0引数の数について、検証を行わない
    正指定された値で、引数の数を検証
    負指定された値で、引数の数がそれ以上あるかどうかを検証
    SQ_MATCHTYPEMASKSTRINGtypemaskから自動的に値を決定する(例えば、".sn"なら3)
  • const SQChar * typemask
    関数に渡す引数の型を検証するためのマスク。NULLのときは型検証を行わない。

注意:

typemaskはゼロ終端の文字列からなり、引数の型に次のような文字を使用できる。

文字型
onull
iinteger
ffloat
ninteger, float
sstring
ttable
aarray
uuserdata
cclosure, nativeclosure
ggenerator
puserpointer
vthread
xinstance
yclass
bbool
.any

'|'は "or" を意味し、これによって複数の型が受け入れ可能な引数を作成することができる(これには使用数の制限はない)。
空白は無視するため、可読性向上のために型の間に空白を挿入することができる。

typemaskによる引数の長さが、nparamscheckで指定された数に満たないとき、残りの引数は型検証されない。

例として、次のような引数を取る関数を考える。

  • thisがテーブル
  • 第1引数が文字列
  • 第2引数が数値かuserpointer
    このときのスキーマは"tsn|p"(table, string, number or userpointer)と表現される。

例: 

SQInteger testy(HSQUIRRELVM v) {
    SQUserPointer p;
    const SQChar* s;
    SQInteger i;
    // no type checking, if the call comply to the mask
    //surely the functions will succeed.
    sq_getuserdata(v, 1, &p, NULL);
    sq_getstring(v, 2, &s);
    sq_getinteger(v, 3, &i);
    // ... do something
    return 0;
}
// the reg code
// ...stuff
sq_newclosure(v, testy, 0);
// expects exactly 3 parameters(userdata,string,number)
sq_setparamscheck(v, 3, _SC("usn"));
// ...stuff

sq_setreleasehook 

void sq_setreleasehook(HSQUIRRELVM v, SQInteger idx, SQRELEASEHOOK hook);

スタック上の指定位置にあるユーザデータのリリースフックをセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQRELEASEHOOK hook
    フック関数ポインタ(下の例を見よ)

注意:

この関数フックは、ユーザデータのメモリが削除される前にVMによって呼び出される。

例: 

/* tyedef SQInteger (*SQRELEASEHOOK)(SQUserPointer,SQInteger size); */
SQInteger my_release_hook(SQUserPointer p,SQInteger size)
{
    /* なにかする */
    return 1;
}

sq_settypetag 

SQRESULT sq_settypetag(HSQUIRRELVM v, SQInteger idx, SQUserPointer typetag);

スタック上の指定位置にあるオブジェクト(ユーザデータまたはクラス)のタイプタグをセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQUserPointer typetag
    任意のSQUserPointer

戻り値:

SQRESULT

sq_tobool 

void sq_tobool(HSQUIRRELVM v, SQInteger idx, SQBool * b);

スタック上の指定位置の値をboolとして取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス
  • SQBool * b
    値を格納するbool値へのポインタ

注意:

もしオブジェクトがbool型でないなら、この関数はSquirrelの規則に従って値をbool値に変換する。
例えば1はtrueとし、0はfalseとする。

sq_tostring 

void sq_tostring(HSQUIRRELVM v, SQInteger idx);

スタック上の指定位置のオブジェクトを文字列へ変換し、その文字列をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のインデックス

呼び出し

sq_call 

SQRESULT sq_call(HSQUIRRELVM v, SQInteger params, SQBool retval, SQBool raiseerror);

クロージャまたはネイティブクロージャを呼び出す。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger params
    関数の引数の数
  • SQBool retval
    trueなら、この関数の戻り値をスタックにpushする
  • SQBool raiseerror
    trueなら、呼び出し実行中に実行時エラーが発生した場合は、VMがエラーハンドラを呼び出すようにする

戻り値:

SQRESULT

注意:

この関数はすべての引数をpopし、スタック上にこのクロージャを置いたままにする
もしretvalがtrueであるなら、クロージャの戻り値がpushされる。
もし関数実行がsq_suspendvmによって中断されたなら、クロージャと引数はスタックから自動的にpopされない。

sq_getlasterror 

SQRESULT sq_getlasterror(HSQUIRRELVM v);

スタックに最後に発生したエラー(ラストエラー)をpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

SQRESULT

注意:

pushされたエラー記述子は、任意の正規なSquirrel型となり得る。

sq_getlocal 

const SQChar * sq_getlocal(HSQUIRRELVM v, SQUnsignedInteger level, SQUnsignedInteger nseq);

指定したスタッックフレームと番号で、スタック上のローカル変数の名前を取得し、現在の値をpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQUnsignedInteger level
    コールスタックの関数インデックス。0を現在の関数とする。
  • SQUnsignedInteger nseq
    スタックフレームにおけるローカル変数のインデックス (0はthis)

戻り値:

もし変数が指定されたレベル/番号に存在するならローカル変数の名前を、そうでないならNULLを返す。

sq_reseterror 

void sq_reseterror(HSQUIRRELVM v);

VM上のラストエラーをnullにリセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM

sq_resume 

SQRESULT sq_resume(HSQUIRRELVM v, SQBool retval, SQBool raiseerror);

スタックトップにあるジェネレータを再開する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQBool retval
    trueなら、この関数の戻り値をスタックにpushする
  • SQBool raiseerror
    trueなら、呼び出し実行中に実行時エラーが発生した場合は、VMがエラーハンドラを呼び出すようにする

戻り値:

SQRESULT

注意:

retvalが0以外なら、ジェネレータの戻り値はpushされる

sq_throwerror 

SQRESULT sq_throwerror(HSQUIRRELVM v, const SQChar * err);

VMのラストエラーをセットし、VM上で例外を起こすためにネイティブクロージャによって返されるべき値を返す。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • const SQChar * err
    投げられるべきエラーの記述

戻り値:

VM上で例外を投げるためにネイティブクロージャによって返されるべき値

オブジェクト操作

sq_arrayappend 

SQRESULT sq_arrayappend(HSQUIRRELVM v, SQInteger idx);

スタックから値をpopして、それをスタック上の指定位置にある配列の末尾に追加する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象配列のインデックス

戻り値

SQRESULT

注意:

配列に対してのみ動作する。

sq_arraypop 

SQRESULT sq_arraypop(HSQUIRRELVM v, SQInteger idx);

スタック上の指定位置にある配列の末尾から値を取り出す。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象配列のインデックス

戻り値

SQRESULT

注意:

配列に対してのみ動作する。

sq_arrayresize 

SQRESULT sq_arrayresize(HSQUIRRELVM v, SQInteger idx, SQInteger newsize);

スタック上の指定位置にある配列をリサイズする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象配列のインデックス
  • SQInteger newsize
    配列の要求サイズ

戻り値

SQRESULT

注意:

配列に対してのみ動作する。
もし、newsizeが現在のサイズよりも大きいなら、新しい配列のスロットはnullで埋められる。

sq_arrayreverse 

SQRESULT sq_arrayreverse(HSQUIRRELVM v, SQInteger idx);

指定された配列を反転する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象配列のインデックス

戻り値

SQRESULT

注意:

配列に対してのみ動作する。

sq_clone 

SQRESULT sq_clone(HSQUIRRELVM v, SQInteger idx);

指定位置にあるテーブル、配列、クラスインスタンスを複製(クローン)し、それをスタックにpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値

SQRESULT

sq_createslot 

SQRESULT sq_createslot(HSQUIRRELVM v, SQInteger idx);

スタックからキーと値をpopし、スタックの指定位置にあるテーブルやクラスに対してset操作を行う。
もしスロットが存在しないなら、作成される。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象テーブルのインデックス

戻り値

SQRESULT

注意:

テーブル委譲によってメタメソッド_newslotが呼び出される。
これはテーブルに対してのみ機能する。
[バージョン2.0.5以降、この関数は非推奨となった。代わりにsq_newslot()を使用せよ。]

sq_deleteslot 

SQRESULT sq_deleteslot(HSQUIRRELVM v, SQInteger idx, SQBool pushval);

スタックからキーをpopし、スタックの指定位置にあるテーブルからそのスロットを削除する。もし、スロットが存在しないなら、なにも起こらない。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象テーブルのインデックス
  • SQBool pushval
    trueなら、この関数は削除されたスロットの値をpushする。

戻り値

SQRESULT

注意:

テーブル委譲によってメタメソッド_delslotが呼び出される。
これはテーブルに対してのみ機能する。

sq_get 

SQRESULT sq_get(HSQUIRRELVM v, SQInteger idx);

スタックからキーをpopし、スタックの指定位置にあるオブジェクトに対してget操作を行う。
そして、その結果をスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値

SQRESULT

注意:

この呼び出しは通常の脱参照のように、委譲システムを呼び出す。
これはテーブル、配列、ユーザデータに対して動作する。
もしこの関数が失敗したら、スタック上にはなにもpushされない。

sq_getattributes 

SQRESULT sq_getattributes(HSQUIRRELVM v, SQInteger idx);

クラスメンバの属性値を取得する。
この関数はスタックからキーをpopして、スタックの指定位置にあるクラスからキーで指定したクラスメンバの属性値をpushする。
もしキーがnullなら、この関数はクラス属性を取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象クラスのインデックス

戻り値

SQRESULT

sq_getclass 

SQRESULT sq_getclass(HSQUIRRELVM v, SQInteger idx);

スタックの指定位置にあるクラスインスタンスのクラスをpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象クラスインスタンスのインデックス

戻り値

SQRESULT

sq_getdelegate 

SQRESULT sq_getdelegate(HSQUIRRELVM v, SQInteger idx);

スタックの指定位置にあるオブジェクトの現在の委譲をpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値

SQRESULT

sq_getfreevariable 

const SQChar * sq_getfreevariable(HSQUIRRELVM v, SQInteger idx, SQInteger nval);

スタックの指定位置にあるクロージャの自由変数の値を取得する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    (クロージャ)スタック上の対象オブジェクトのインデックス
  • SQInteger nval
    (クロージャに関する)自由変数の0ベースのインデックス

戻り値:

純粋Squirrelクロージャに対する自由変数名。
エラーの場合や変数インデックスが範囲外のときはnull

注意:

Cのネイティブクロージャに対しては、この関数は常に失敗する。

sq_getweakrefval 

SQRESULT sq_getweakrefval(HSQUIRRELVM v, SQInteger idx);

スタックの指定位置にある弱参照によってポイントされているオブジェクトをpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    対象弱参照のインデックス

戻り値:

SQRESULT

注意:

もしこの関数が失敗したなら、スタックにはなにもpushされない。

sq_instanceof 

SQBool sq_instanceof(HSQUIRRELVM v);

オブジェクトが特定クラスのインスタンスであるかどうかを調べる。
インスタンスとクラスをスタック上に置く必要がある。

引数:

  • HSQUIRRELVM v
    ターゲットVM

戻り値:

もしスタックの位置-2のインスタンスが、スタックの位置-1のクラスオブジェクトのインスタンスであるならSQTrue。

注意:

この関数はスタックからオブジェクトをpopしない。

sq_newslot 

SQRESULT sq_newslot(HSQUIRRELVM v, SQInteger idx, SQBool bstatic);

スタックからキーと値をpopし、スタックの指定位置にあるテーブルやクラスに対してset操作を行う。もしスロットが存在しないなら、作成される。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象テーブルのインデックス
  • SQBool bstatic
    SQTrueなら静的メンバとして作成する。この引数は対象オブジェクトがクラスであるときのみ使用される。

戻り値:

SQRESULT

注意:

テーブル委譲によってメタメソッド_newslotが呼び出される。これはテーブルに対してのみ機能する。

sq_next 

SQRESULT sq_next(HSQUIRRELVM v, SQInteger idx);

スタックに配列、テーブル、クラススロットの次のキーと値をpushする。
反復を開始するためには、スタックトップにnullがある必要がある。
各呼び出しにおいて、この関数はnullを反復子に置き換え、コンテナスロットのキーと値をpushする。
各反復で、アプリケーションは前のキーと値をpopしなければならないが、反復子は残さなければならない(つまり、これは次の反復のための参照点として用いられる)。
全スロットが反復されたとき、この関数は失敗する(テーブルと配列操作を参照せよ)。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象テーブルのインデックス

戻り値:

SQRESULT

sq_rawdeleteslot 

SQRESULT sq_rawdeleteslot(HSQUIRRELVM v, SQInteger idx, SQBool pushval);

メタメソッド_delslotqを用いずに、テーブルからスロットを削除する。
スタックからキーをpopし、スタックの指定位置にあるテーブルからそのスロットを削除する。
もし、スロットが存在しないなら、なにも起こらない。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象テーブルのインデックス
  • SQBool pushval
    trueなら、この関数は削除されたスロットの値をpushする。

戻り値:

SQRESULT

sq_rawget 

SQRESULT sq_rawget(HSQUIRRELVM v, SQInteger idx);

スタックからキーをpopし、スタックの指定位置にあるオブジェクトに対して(メタメソッドや委譲を用いずに)get操作を行う。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値:

SQRESULT

注意:

これはテーブルと配列に対してのみ機能する。

sq_rawset 

SQRESULT sq_rawset(HSQUIRRELVM v, SQInteger idx);

スタックからキーと値をpopし、スタックの指定位置にあるオブジェクトに対して(メタメソッドや委譲を用いずに)set操作を行う。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値:

SQRESULT

注意:

これはテーブルと配列に対してのみ機能する。
もしこの関数が失敗したら、スタック上にはなにもpushされない。

sq_set 

SQRESULT sq_set(HSQUIRRELVM v, SQInteger idx);

スタックからキーと値をpopし、スタックの指定位置にあるオブジェクトに対してset操作を行う。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値:

SQRESULT

注意:

この呼び出しは通常の代入のように委譲システムを呼び出す。これはテーブル、配列、ユーザデータに対して動作する。

sq_setattributes 

SQRESULT sq_setattributes(HSQUIRRELVM v, SQInteger idx);

クラスメンバの属性値をセットする。
この関数はスタックからキーと値をpopし、スタックの指定位置にあるクラスに対して(キーで指定された)属性をセットする。
もし、キーがnullなら、この関数はクラス属性をセットする。
もしこの関数が成功したなら、古い属性値はスタックへpushされる。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象クラスのインデックス

戻り値:

SQRESULT

sq_setdelegate 

SQRESULT sq_setdelegate(HSQUIRRELVM v, SQInteger idx);

スタックからテーブルをpopし、スタックの指定位置オブジェクトを委譲としてそれにセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス

戻り値:

SQRESULT

注意:

オブジェクトから委譲を削除するためには委譲としてnullを用いる必要がある。

sq_setfreevariable 

SQRESULT sq_setfreevariable(HSQUIRRELVM v, SQInteger idx, SQInteger nval);

スタックから値をpopし、スタックの指定位置にあるクロージャの自由変数としてそれをセットする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のターゲットオブジェクトのインデックス
  • SQInteger nval
    (クロージャへ関連づける)自由変数の0ベースのインデックス

戻り値:

SQRESULT

sq_weakref 

void sq_weakref(HSQUIRRELVM v, SQInteger idx);

スタックの指定位置にあるオブジェクトへの弱参照をpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上のターゲットオブジェクトへのインデックス

戻り値:

SQRESULT

注意:

もしidxの位置にあるオブジェクトが整数、浮動小数点数、真偽値、nullであるなら、
弱参照オブジェクトの代わりにそのオブジェクト自体がpushされる。

バイトコード直列化

sq_readclosure 

SQRESULT sq_readclosure(HSQUIRRELVM v, SQREADFUNC readf, SQUserPointer up);

クロージャをデシリアライズ(読み込み)し、そのクロージャをスタックトップへpushする。
その入力元は読み込みコールバック内でユーザが定義する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQREADFUNC readf
    デシリアライズ中にVMによって呼び出される読み込み関数へのポインタ
  • SQUserPointer up
    読み込み関数への呼び出しごとに渡されるポインタ

戻り値:

SQRESULT

sq_writeclosure 

SQRESULT sq_writeclosure(HSQUIRRELVM v, SQWRITEFUNC writef, SQUserPointer up);

スタックトップにあるクロージャをシリアライズ(書き込み)する。
その出力先は書き込みコールバック内でユーザが定義する。

引き数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQWRITEFUNC writef
    シリアライズ中にVMによって呼び出される書き込み関数へのポインタ
  • SQUserPointer up
    書き込み関数への呼び出しごとに渡されるポインタ

戻り値:

SQRESULT

注意:

自由変数付きのクロージャはシリアライズすることができない。

生オブジェクト操作

sq_addref 

void sq_addref(HSQUIRRELVM v, HSQOBJECT * po);

対象オブジェクトハンドラの参照カウントを1増やす。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

sq_getobjtypetag 

SQRESULT sq_getobjtypetag(HSQOBJECT * o, SQUserPointer * typetag);

生オブジェクト参照(ユーザデータもしくはクラス)のタイプタグを得る。

引数:

  • HSQOBJECT * o
    オブジェクトハンドラへのポインタ
  • SQUserPointer * typetag
    タグが格納される変数へのポインタ

戻り値:

SQRESULT

注意:

この関数はインスタンスに対しても機能する。もし対象オブジェクトがインスタンスなら、そのベースクラスのタイプタグがフェッチされる。

sq_getstackobj 

SQRESULT sq_getstackobj(HSQUIRRELVM v, SQInteger idx, HSQOBJECT * po);

スタックからオブジェクトを得て、それをオブジェクトハンドラに格納する。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • SQInteger idx
    スタック上の対象オブジェクトのインデックス
  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

戻り値:

SQRESULT

sq_objtobool 

SQBool sq_objtobool(HSQOBJECT * po);

生オブジェクト参照の真偽値を返す。

引数:

  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

注意:

もしオブジェクトがboolでないなら、常にfalseが返される。

sq_objtofloat 

SQFloat sq_objtofloat(HSQOBJECT * po);

生オブジェクト参照の浮動小数点数を返す。

引数:

  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

注意:

もしオブジェクトが整数ならfloatへ変換される。
もしオブジェクトが数値でないなら、常に0が返される。

sq_objtointeger 

SQInteger sq_objtointeger(HSQOBJECT * po);

生オブジェクト参照の整数値を返す。

引数:

  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

注意:

もしオブジェクトがfloatならそれは整数に変換される。
もしオブジェクトが数値でないなら、常に0が返される。

sq_objtostring 

const SQChar * sq_objtostring(HSQOBJECT * po);

生オブジェクト参照の文字列を返す。

引数:

  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

注意:

もしオブジェクトが文字列を参照しないなら、常にNULLが返される。

sq_pushobject 

void sq_pushobject(HSQUIRRELVM v, HSQOBJECT obj);

オブジェクトハンドラによって参照されたオブジェクトをスタックへpushする。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • HSQOBJECT obj
    オブジェクトハンドラ

sq_release 

SQBool sq_release(HSQUIRRELVM v, HSQOBJECT * po);

オブジェクトハンドラの参照カウントを1減らす。

引数:

  • HSQUIRRELVM v
    ターゲットVM
  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

戻り値:

  • SQTrue オブジェクトハンドラが全ての参照を失なったとき
    (sq_addrefで追加されたものも含む)
  • SQFalse それ以外

注意:

もし、全ての参照を失なった場合、この関数はオブジェクトハンドラをnullにリセットさせる。
訳注: sq_addrefと対となる関数。

sq_resetobject 

void sq_resetobject(HSQOBJECT * po);

オブジェクトハンドラをリセット(初期化)する。

引数:

  • HSQOBJECT * po
    オブジェクトハンドラへのポインタ

注意:

すべてのオブジェクトハンドラはこの関数によって初期化されなければならない。

デバッグインタフェース

Squirrel_Lang/ch4_2