More ...
HSP3:ガイドライン
マニュアルを補うためのガイドライン（指針）です。
プログラムを組んだり、モジュールやプラグインを作る際の参考にしてください。
ユーザにより提案・採用されたもので、公式に採用されているものではありません。
ガイドラインの追加提案はHSP3:ガイドライン:提案の方でお願いします。
文法
HSPでの標準命令/標準関数の区別
まず、命令/関数を分類するのに、「値を返すか」と「プログラムの状態を変えるか」に着目します。 これを表にすると、次の様に分類できます。
| 値を返す | 返さない | |
| 状態を変える | 1-1 | 1-2 |
| 状態を変えない | 2-1 | 2-2 |
1-2と2-1に関しては、それぞれ命令、関数になるのは明らかです。 また、2-2に関しては、実際このような機能を提供するものは無いと思われます。 これを表に当てはめるとこうなります。
| 値を返す | 返さない | |
| 状態を変える | ？ | 命令 |
| 状態を変えない | 関数 | × |
問題は、ここで？になっている部分です。 ここは命令とも関数とも考えられます。
これがHSP3ではどうなっているかは、幾つかのタイプがあります。 まず、返り値が重要でない場合、システム変数を介して返しています。 これはexecやdialogなどが相当します。 返り値とすれば重要だけど、返り値でなくても良いものは、先に引数で指定します。 これはscreenなどが相当します。 最後に、返り値として重要で、返り値でなければならないものは、引数に返します。 これはnewcomなどが相当します。 （結局の所は全て命令。）
まとめると、こんな感じです。（上から順番にチェック）
- 状態を変えず、値を返さない
--(YES)--> 見直し - 状態を変えず、値を返す
--(YES)--> 関数 - 値を返すが、それは重要ではない
--(YES)--> 命令（システム変数経由） - 返り値とすれば重要だが、先に指定可能
--(YES)--> 命令（IDとして引数に指定） - 返り値として重要で、先に指定不可能
---------> 命令（引数経由）
「関数になる（すべき）かどうか」だけに注目すれば、「状態を変えるかどうか」という事になります。
プラグイン・モジュールでの命令/関数の区別
プラグイン・モジュール提供者は、なるべくHSP標準の仕様に合わせるのが望ましいですが、「関数では引数の内容を変えない」という程度のルールさえ守ればどちらでもよいでしょう。ただし、同じプラグイン・モジュール内では同じ基準を使いましょう。
以下は標準以外の基準例です。
- 返された値(戻り値)を直接他のことに利用する可能性が高いもの
globalの付け方
モジュール内で定義した定数が別モジュールでglobalとして定義されていると、モジュールが上手く動きません。モジュールが使える人なら一時的に書き換えて対応できますが、分からない人にはどうしようもない問題です。また、もっと長い目で見ると、モジュールがバージョンアップするとまた書き換えなければならず、場合によっては再配布も不可能になります。
なので、モジュール開発者の方は、可能な限りglobalは付けないようにしましょう。
また、モジュール利用者は、自前じゃないモジュールを全てインクルードした後からglobalを使いましょう。
暗黙のglobal
#defineなどは明示的にglobalを指定しなければglobalになりませんが、以下のプリプロセッサ命令ではglobalを付けなくてもglobalになります。
- #func（モジュール外のみ）
- #cmd
- #deffunc, #defcfunc
これらをglobalにしたくない場合は、名前空間の指定を必ず行ってください。
; 指定例
#module "foo"
#deffunc bar@foo
return
#deffunc baz@
return
#global
名前空間
モジュール外でも用いる定義にglobalを付けない方が良い理由は前記の通りですが、 globalを付けない場合の対応方法としては2つ考えられます。
- モジュール内で使う定義は必ず@モジュール名を付ける。
- モジュール外でも使う定義はモジュール外でglobalを付けずに定義する。モジュール内では@で参照。
どちらでもいいですが、歴史的経緯で後者が使われる事が多いです。
命令
#define
文の区切りには、 : と%cが使えます。しかし、%cを命令文の区切りに使うと、以下のようなエラーが出る場合があります。
#define maco(%1,%2) mes %1 %c mes %2
if 1 : macro "A","B" : else : macro "C","D"
実行結果
???(3) : error 4 : パラメーター式の記述が無効です (3行目)
--> mes@hsp "B" : else@hsp : mes@hsp "C"
これは、プリプロセッサによって、次のように展開されるためです。
if 1 : mes "A" mes "B" : else : mes "C" "D"
元々、%cは一部のプリプロセス文のために用意されたものなので、特別な理由が無い限りは : を使いましょう。