HSP : Hot Soup Processor ver3.6 / onion software 1997-2021(c)

HSP3 モジュール機能ガイド

HSPモジュール機能について
ユーザー定義命令について
モジュールの使い方(基本)
モジュールの使い方(応用)
モジュール定義命令
モジュールのクリーンアップ機能について
標準キーワードと「@hsp」モジュール名について

このテキストには、Hot Soup Processor ver3.0以降でサポートされているモジュール機能についての説明が含まれています。

モジュール機能は、HSPをより深く高度に使いたいという方のための拡張機能です。しかし、この機能はすべての人に必要なものではありません。初心者の方や、これからHSPを使う方は、まだモジュールについての習得はしなくても大丈夫です。しかし、中級者以上の方はより効率的にソースの再利用が可能になる重要な要素ですので、是非マスターしてください。

また、上級者は、さらに高度なモジュール変数機能を利用することが可能です。モジュール変数についての詳細は、このガイドでは説明していませんので、詳しくは、プログラミングガイドを参照してください。

HSPモジュール機能について

モジュール機能は、複数のスクリプトをラベル名や変数名の衝突を気にせず結合するための仕組みです。

この機能は、大きなサイズのスクリプトを作る時や、多量の変数名を管理する場合に有効です。モジュール機能を活用することにより、より汎用性の高いスクリプトを組むことができるようになります。

また、モジュール機能を使わない人であっても、他の人がモジュール機能を使って追加した新しい命令を使うことが可能です。これは、DLLによる拡張プラグインの仕組みと変わりません。

まず、モジュールについて説明してみましょう。たとえば、「test1.as」というソーススクリプトがあったとしましょう。このソーススクリプトには、変数aと変数bを使っているとします。別な人が、「test2.as」というソーススクリプトを作ったとして、そこにとても便利なサブルーチンがあったとしたら、どうなるでしょう。「test2.as」で変数aと変数bという名前を使っていなければ問題なく、そのままサブルーチンだけを持ってくることができるかもしれません。しかし、もし「test2.as」でも変数aと変数bを別な用途で使っていたとしたらとてもやっかいです。

HSPモジュール機能を使うと、「test1.as」から「test2.as」のスクリプトを呼び出すことが可能になりますが、「test1.as」と「test2.as」で使われている変数は(たとえ名前が同じであっても)独立したものとして扱われます。また、この独立したスクリプト内のサブルーチンを、新規命令として登録することができ、パラメータを渡したり、受け取ったりすることが可能です。

過去に作ったモジュールを再利用したり、人に使ってもらうために公開したり、誰か他の人が作ったモジュールを使うなど、HSPスクリプトをより広く応用することが可能になります。

HSPモジュールを使いこなすためには、ユーザー拡張命令、モジュールインポート命令などを使う必要があります。これらは、単体でも便利な機能を提供する命令です。一度に覚えようとしないで、わかるところから1つ 1つマスターしていきましょう。

ユーザー定義命令について

ユーザー定義命令は、HSPモジュール機能とともに追加された命令の1つで、新しい名前の命令をユーザーが任意に追加できるというものです。これは、HSPモジュール機能とは別に単体で使っても非常に強力なものとなるでしょう。

ユーザー定義命令は、以下のように使います。

    goto *main

#deffunc routine
    mes "sub-routine"
    return

*main
    routine
    stop

HSPの命令には「routine」はありませんから、いままでならエラーになってしまうところですが、実際にこのスクリプトを実行すると、「sub-routine」という表示がされて、「routine」という命令が実行されます。

ユーザー定義命令は、「#deffunc」という命令によって定義できます。 #deffunc 命令の名前 で、新しい名前の命令が追加されます。これ以降、新しい命令が出てきた場合には、「#deffunc」のある場所にサブルーチンジャンプします。つまり、

    goto *main

*routine
    mes "sub-routine"
    return

*main
    gosub *routine

のようなスクリプトでも、

    goto *main

#deffunc routine
    mes "sub-routine"
    return

*main
    routine

でも同じということです。

またユーザー定義命令は、サブルーチンにパラメータを渡すことを可能にしています。

    goto *main

#deffunc routine int prm1, int prm2
    mes "パラメータ1は、"+prm1+"です。"
    mes "パラメータ2は、"+prm2+"です。"
    return

*main
    routine 10,20

いままでのgosub命令では、値をサブルーチンに渡す時には、あらかじめ決められた変数に値を入れて、呼び出すしかありませんでした。ユーザー定義命令では、それに代わってスマートな方法で値を渡すことを可能にしています。

また、渡すパラメータは数値だけでなく、文字列、変数(配列)などいくつものバリエーションがあります。また、サブルーチンから戻る際にシステム変数statに値を代入したり、パラメータとして指定した変数に値を書き戻すことも可能です。

このパラメーターは、エイリアスとも呼ばれていて、#deffunc命令により新規命令を定義する際に設定することができます。

#deffunc 命令名 パラメーター型 エイリアス名,…

のように記述することで、指定されたパラメーター型を取得して、エイリアス名で参照することができるようになります。詳しくは、「#deffunc命令詳細」を参照してください。

また、HSP3.0からは、#defcfunc命令によりユーザーが関数を定義することが可能になっています。これも、#deffunc命令と同様の指定で、簡単に関数を追加することができます。

モジュールの使い方(基本)

モジュールは、変数名やラベル名が独立して扱えるソースの単位を指します。推奨される最も簡単なモジュールの使い方は、モジュール部分を1つのソーススクリプトファイル(asファイル)にしておき、別なファイルからモジュールとして呼び出すことです。たとえば、test1.asというファイルにモジュールとなるソースを書きます。

// test1.asの内容

#module
#deffunc test1
    mes "test1.asで表示しています。"
    return
#global

モジュールは、必ず「#module」で始まり「#global」を最後に書くのがお約束だと思って下さい。

このように記述すると、モジュール内に「test1」という命令で呼び出すことのできるサブルーチンができあがります。次に、これを呼び出すためのソースを「test2.as」というファイルに書いてみましょう。

// test2.asの内容

#include "test1.as"
    mes "test2.asです。"
    test1
    stop

「#include」命令でモジュールを登録するためのソース「test1.as」を読み込んでいます。

この後、「test1」という命令が書かれた行が出てきます。これはユーザー定義命令なので(詳しくは「ユーザー定義命令について」を参照)、「test1.as」のサブルーチンが呼び出されます。実際にこのスクリプトを実行すると、

test2.asです。
test1.asで表示しています。

という2つの行が現われ、test2.asからtest1.asのモジュールが呼び出されたことがわかります。

この基本的な例では、メッセージを表示しているだけなので、gosub命令によるサブルーチン呼び出しと、あまり変わっておらず、モジュールとしての威力は発揮されていません。では、次の例ではどうでしょうか。

// test1.asの内容

#module
#deffunc test1
    a=456
    mes "test1では、"
    mes "A="+a+"です。"
    return
#global

// test2.asの内容

#include "test1.as"
    a=123
    test1
    mes "test2では、"
    mes "A="+a+"です。"
    stop

これで「test2.as」を実行してみると、

test1では、
A=456です。
test2では、
A=123です。

となります。普通ならば、先に「test1.as」側で変数aに456が代入されているので、「test2.as」でも同じ値になるところですが、モジュールの中と外では名前が独立しているので、同じ変数aでも、「test1.as」と、「test2.as」では別々の内容を保持しています。

このように、変数やラベルの名前が重複していても、まったく問題なくそれぞれのスクリプトが動作するという点が、モジュールの基本的な概念です。

しかし、変数が独立していると困る部分もあります。モジュールを呼び出して何らかの結果を得たい場合や、モジュールに値を渡したいこともあります。

実は、このための機能がユーザー定義命令に用意されていて、別なモジュールとのパラメータのやり取りに使うことができます。

// test1.asの内容

#module
#deffunc test1 int prm1
    mes "パラメータは、"+prm1+"です。"
    return 1
#global

// test2.asの内容

#include "test1.as"
    a=543
    test1 a
    mes "STATは、"+stat+"です。"
    stop

上の例では、ユーザー定義命令test1の呼び出しで、「test1 a」というパラメータ付きの記述で、変数aの内容、543という値を渡しています。「test1.as」では、この渡された値を、prm1というエイリアス名によって取り出し、さらに、システム変数statに値1を代入して終了します。

重要なことは、「test2.as」では「test1.as」で使われている変数名などは気にする必要がないことです。同様に、「test1.as」からも呼び出す側との変数名が重なることを気にする必要がありません。独立した機能を持ったサブルーチンを、完全に分離してしまうことが HSPモジュール機能なのです。

以上が基本的なモジュールの使い方です。さらなる応用については、次の項を見てください。

モジュールの使い方(応用)

基本の説明では、1つのモジュールに1つの命令だけを定義していましたが、 1つのモジュールの中に、複数のユーザー定義命令を作ることもできます。

// test1.asの内容

#module
#deffunc test1
    mes "test1で表示しています。"
    return

#deffunc test2
    mes "test2で表示しています。"
    return
#global

上の例では、「test1」と「test2」という命令が新たに追加されます。この場合、「test1」と「test2」の間では変数名やラベル名は同じものになります。

「test1」と「test2」でやはり独立した変数名やラベル名を使いたい場合は、

#module
#deffunc test1
    mes "test1で表示しています。"
    return
#global

#module
#deffunc test2
    mes "test2で表示しています。"
    return
#global

このように記述することで実現できます。つまりモジュールとは、「#module」～「#global」で区切られた区間とそれ以外の区間をまったく別な世界と考えるように指示を出していることなのです。

基本の説明では、「test1.as」と「test2.as」という2つのファイルにモジュールと、そうでない部分(グローバル領域)を分けて説明していました。実際のところ「test1.as」をインクルードすることなく 1つのファイル内でもモジュールをどんどん作っていくことも可能ですが、なるべく1つのファイルには1つのモジュールのみにして、1つのソーススクリプトでは変数名とラベル名を統一した方がいいでしょう。特にラベル名は、1つのソーススクリプト内に同じラベルがいくつもあると混乱を招きます。

モジュール内の変数は、基本的にすべて静的(static)に共有されています。つまり一度設定された変数は、他の値が代入されない限り、内容を失うことはありません。このため、再帰呼び出し(自分自身を呼び出すこと) を行なう場合には注意が必要です。

それぞれの定義命令内では、local宣言により明示的にローカルな変数を作成することができます。再帰呼び出しを行なう場合には、必ず内部で使用する変数をローカルにするようにしてください。 (ローカル宣言を行なうと、変数の生成と破棄のために通常よりも実行コストがかかることも留意しておいてください。)

モジュール定義命令

HSP3ではモジュール定義命令として、以下のプリプロセッサ命令が用意されています。

#module
#global
#deffunc
#defcfunc

各命令の使い方はヘルプブラウザから確認してください。

モジュールのクリーンアップ機能について

クリーンアップ機能は、HSPプログラムが終了する直前にモジュール内のスクリプトが自動的に呼び出されるもので、モジュールによって機能を拡張した場合などにその後始末、システムやメモリの解放などが行なえるようにしたものです。これをクリーンアップ機能と呼んでいます。この機能を使うには、モジュール内でのユーザー定義命令宣言時に、

#deffunc 名前 onexit

のように、引数を記述する部分に「onexit」を入れておいてください。 HSPのプログラムが終了した場合に、その命令が自動的に実行されます。ただし、この命令内では以下の点に注意してください。

end、stop、wait、await、dialogなど時間待ちが起こる命令は使用できません
mesなど画面に出力する命令は機能しません

つまり最低限のメモリ解放や外部DLLの呼び出しなど最終的に行なわれる作業だけを記述するものと考えて下さい。同様の動作をするものにonexit命令がありますが、システムの処理としては

[HSPのプログラムを中断]
[onexit命令の飛び先を実行]
[モジュールのクリーンアップ先を実行]
[HSPリソースの完全な破棄]

という順番になっています。 onexit命令の飛び先では、プログラムを中断すること自体を中止することも可能ですが、クリーンアップ機能の場合は中断はできません。また、複数のモジュールや、複数のクリーンアップ命令が登録された場合には、登録された順番とは逆順に辿って次々に実行されていきます。

標準キーワードと「@hsp」モジュール名について

標準キーワードは「@hsp」というモジュール名の空間に割り当てられています。これは、たとえばmes命令であれば、「mes@hsp」という名前が正式な名称であることを意味します。ただし、通常のグローバルな空間でも使用できるように「@hsp」がない名称も別名として登録されているので、いままで通りの命令名でそのまま使用することができます。

たとえば、mes命令であれば「#define global mes mes@hsp」が最初から定義されているのと同じです。 (プリプロセッサ処理後に、標準キーワードは「@hsp」が付けられた正規の名称に展開されます。設定によってコンパイル時に出力できる「hsptmp.i」を開いてみるとわかると思います。)

これにより、標準キーワードとして登録されている名称そのものを別名にしたり、ユーザーが定義し直すことが可能になります。以下は、mes命令をマクロにより置き換えている例です。

#undef mes
#define mes(%1) mes@hsp "MES->"+%1
    mes "メッセージです。"  // 「MES->メッセージです。」と表示
    stop

「mes」というキーワードを、#undef命令により取り消した後、再定義しています。 HSPで使用される標準キーワードすべては、同様に取り消し、再定義することが可能です。

以下は、mes命令をユーザー定義命令に置き換えている例です。

#undef mes
#module
#deffunc mes str _p1
    _y = ginfo_cy

    color 0, 0, 0
    pos ginfo_cx+1, _y+1
    mes@hsp _p1

    color 0, 192, 255
    pos ginfo_cx, _y
    mes@hsp _p1
    return
#global
    mes "mes命令を影文字にしてみました。"

標準キーワードの再定義は、それ以降のキーワードすべてに影響があるため注意して使用してください。