hspda.txt

doclib\hspda.txt » Plain Format

------------------------------------------------------------------------------
HSPDA ver3.5 REFERENCE MANUAL                       HSP : Hot Soup Processor  
HSP拡張DLLリファレンス             copyright 1999-2017 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	このDLLは、Hot Soup Processor ver3.0以降とともに使用することで、様々な
	機能拡張を行なうことのできるプラグインモジュールです。
	この拡張DLLを使用することにより、新規命令が追加され、各種データへの
	アクセス機能がHSPからコントロールできるようになります。


・インストール

	拡張プラグインのファイル、HSPDA.DLLは、HSED3.EXEおよび、HSP3.EXEのある
	ディレクトリと同じ場所に置いてください。
	(実行に使われているHSP3.EXEと同じディレクトリに、HSPDA.DLLがない場合は
	エラーになります)
	また、スクリプトを作成する場合には、HSPDA.ASをスクリプトと同じディレク
	トリに置き、スクリプトの先頭に必ず「#include "hspda.as"」という行を追加
	してください。以上で、HSPの機能が拡張され、このリファレンスで説明を
	している命令を使用することができるようになります。
	まず最初に、試しに付属のサンプルスクリプトを実行してみてください。
	拡張された機能の簡単な使用例を見ることができるはずです。


・変数データアクセス命令について

	変数データアクセス命令は、スクリプト実行時に変数データの一部または
	全部をファイルに保存及び読み込みするための機能を持っています。
	これにより、配列変数やモジュール変数など管理が複雑になってしまう
	データの入出力を手軽に行なうことができるようになります。
	HSPでは、変数単体の入出力はbloadbsave命令を使うことができますが、
	文字列型の配列や、複数の変数を1つのファイルに収めることが
	できませんでした。
	変数データアクセス命令は、できる限り手軽で安全な変数データの保存と
	読み込みをサポートするために作成されています。
	(テキストファイルの入出力は、これまでと同様にnoteloadnotesave命令を
	ご使用下さい。変数データアクセス命令は、変数バッファそのものを独自の
	ファイル形式で読み書きする用途に向いています。)

	難しいことは、何も考えずにすべての変数データを保存したい場合には、

		vsave "ファイル名"

	を実行してください。これだけで"ファイル名"のファイルにすべての
	変数情報が保存されます。
	逆に、すべての変数データをファイルから読み込む場合には、

		vload "ファイル名"

	を実行してください。
	自作のスクリプトやツールにセーブ・ロード等の機能を手軽に付けたい
	時などには便利な命令です。
	もし、個別に変数を指定してファイルにデータを保存したい場合には、

		vsave_start
		vsave_put 変数名
		vsave_put 変数名
		vsave_end "ファイル名"

	のように、「vsave_start」と「vsave_end」の間に、保存したい変数名を
	vsave_put命令に続けて記述してください。
	これを読み込む場合は、以下のようになります。

		vload_start "ファイル名"
		vload_get 変数名
		vload_get 変数名
		vload_end

	ただし、読み込みに関しては特に変数名を指定しなくても、
	ファイルに保存されている変数だけしか読み込まれないので、

		vload "ファイル名"

	としても問題はありません。

	このように、変数が持っているデータとファイルを相互にやりとりする
	ことができます。それぞれの命令の詳細については、レファレンスや
	ヘルプを参照してください。

	通常は、これだけ知っていれば問題ありませんが、変数データ保存と
	読み込みの仕組みについて、いくつか注意点があるので覚えておくと
	いいでしょう。

	変数の保存は、変数の内容を配列やモジュール変数も含めて保存しますが、
	クローンされた変数、comobj型、variant型の変数は対象となりません。
	また、label型の変数の保存が可能ですが、読み込み時に正常なラベル情報に
	ならない可能性があるので注意してください。

	変数の保存データは、独自形式のバイナリファイルとして生成されます。
	拡張子も含めてファイル名は任意につけることができます。
	(プラグインが推奨する拡張子は、「.VAR」または「.HVF」です。)

	保存データに記録されるのは、「変数名」と「変数が管理するメモリ内容」
	となっています。HSPDAプラグインは、HSPの中間コードに常に変数名を
	出力するためにヘッダで「#cmpopt varname 1」の指定を行なっています。
	これにより、EXEファイルやオブジェクトファイル出力時にも変数名が
	データとして内部に保存されます。ですから、変数名が同じであれば、
	まったく異なるスクリプトから保存された変数データからも読み込むことが
	できます。あくまでも、変数名とその内容だけが記録されていると
	覚えておいてください。
	「変数が管理するメモリ内容」というのは、変数の配列に関する情報も
	含んでいます。配列は確保されている内容すべてが保存の対象となります。
	また、文字列型はバッファの内容すべてが保存の対象となります。
	文字列データとしてバッファの一部しか使用していない場合でも、確保された
	メモリすべてを保存します。(文字の終了コードに左右されません。)

	読み込み時には、指定された変数名とファイルに記録された変数名が
	一致した場合にのみデータが取り出されます。
	ファイルに記録されている変数名が読み込みの時点で定義されるわけでは
	ないので注意してください。あくまでも、スクリプトの中で一度でも定義
	されて存在する変数に、ファイルからの内容を代入することになります。
	(変数を読み出す側でも、あらかじめ読み出すための変数は定義して
	おく必要があるということです。保存と読み込みを同じスクリプトで
	行なっている場合は、問題ありません。)
	また、モジュール型の変数は、保存した時点とモジュール名、
	モジュール変数定義数が同じでなければ読み込まれません。

	変数データアクセス命令は、今後もアップデートを行なっていく予定です。
	ファイルをアプリケーションごとに識別するためのコード導入や、暗号化
	などのオプションを提供していく予定です。
	また、将来的にはXML形式でのシリアライズも検討しています。


・更新履歴

	2015/02/13

		sortval,sortstr,sortnote,sortget命令は標準命令として実装されたため、HSPDAプラグインから削除しました

	2011/01/17

		sortval命令でフリーズすることがある不具合を修正(BT#233)

	2010/10/18

		sortvalでエラーが出ることがある不具合を修正。

	2009/7/30

		sortvalの昇順・降順が正しく反映されない不具合を修正。

	2009/6/9

		xnoteadd でバッファオーバーフローするのを修正。
		sortnote,sortstrで一部の文字列がASCIIコード順にソートされない不具合を修正
		sortnote で空行が増えてしまう不具合を修正

	2009/5/14

		label型の変更に対応。

	2007/4/4

		変数データアクセス命令を追加。

	2005/6/3

		sortnotesortstr命令をHSP3専用に修正。
		rndf_inirndf_getrndf_geti命令を追加。

	2002/4/16

		検索で関係ない全角文字がヒットする不具合を修正。
		csvflagが正常に動作するように修正。
		csvstr,csvnote命令で全角文字判定に失敗する不具合を修正。

	2002/3/30

		csvstr,csvnote命令に区切りキャラクター指定を追加。
		csvsel,csvres,csvflag,csvopt,csvfind命令を追加。

	2000/5/1

		ソート結果が一部おかしくなる不具合を修正。
		sortnote命令で、文字列バッファの末尾が壊される不具合を修正。

	1999/12/2

		ver2.5に同梱。


・注意点

	HSPDA.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。
	使用するHSPは、ver3.2以上をお使い下さい。ver2.61やそれ以前のHSPには
	対応していませんのでご注意下さい。
	EXEファイルを作成した場合でも、HSPDA.DLLをEXEファイルと同じディレクトリ
	に置かないと動作しません。また、packfileにDLLを追加することはできません。


・著作権(ライセンス)および連絡先

	ユーザーがHSPを使って作成したオリジナルのソフトウェア(実行ファイル)の
	権利は、それを作成したユーザーに属します。
	有償・無償を問わずHSPDA.DLLを自由に配布することができ、onion softwareの
	著作権表示義務もありません。
	ユーザーが作成したオリジナルのソフトウェアに対してonion softwareが著作権を
	主張することはありません。

	HSPDAプラグインは、onion softwareの著作物です。
	onion softwareは本プログラムによって生じた、いかなる損害についても
	保証いたしません。自己の責任の範囲で使用してください。
	HSPDA.DLLは、Microsoft Visual C++ 2005でコンパイルされて います。 


・命令一覧

	csvstr					CSVの1行を配列に変換
	csvnote					CSVの1行をメモリノート変換

	xnotesel				排他メモリノート初期化
	xnoteadd				排他メモリノート項目追加

	csvsel					CSV検索の対象バッファを選択
	csvres					CSV検索の結果出力バッファを指定
	csvflag					CSV検索の項目フラグを設定
	csvopt					CSV検索のオプションを設定
	csvfind					CSV検索を実行

	rndf_ini				実数乱数の初期化
	rndf_get				実数乱数を取得
	rndf_geti				乱数を取得

	getvarid				変数IDを取得
	getvarname				変数名を取得
	getmaxvar				変数IDの最大数を取得
	vsave					すべての変数を保存
	vload					すべての変数を読み込み
	vsave_start				変数保存の開始
	vsave_put				保存する変数の指定
	vsave_end				変数保存の終了
	vload_start				変数読み込みの開始
	vload_get				読み込む変数の指定
	vload_end				変数読み込みの終了


・データアクセス命令

	テキストやCSVなどの各種データ形式を手軽に扱うための命令セットです。
	メモリノートパッド命令と組み合わせることで、CSV形式のファイルから
	データを取り出すことが可能になります。

	csvstr p1,p2,p3				CSVの1行を配列に変換

	p1 = 結果が代入される文字列型の配列変数名
	p2 = CSVの1行を取り出した文字列
	p3 = 区切りキャラクターコード

	・説明

		CSV形式のデータから取り出した1行だけのデータを、
		文字列型の配列変数に展開します。
		CSV形式は、「,」で区切られたテキストのデータです。
		たとえば、「a,b,c,d」のような「,」で区切られた4つの
		文字列があったとすると、csvstr命令を使うことで
		「a.0="a"」「a.1="b"」「a.2="c"」「a.3="d"」のように
		配列変数にそれぞれの要素を分けて代入することができます。
		p1で指定される配列変数は、必ず文字列型の配列変数である
		必要があります。

		配列変数に確保されている文字数や、配列の限界を越えた
		部分は無視されます。(エラーになったり、データが破壊
		されることはありません)

		p3で区切りキャラクターを指定することができます。
		p3を省略または0にした場合は「,」が使用されます。
		9を指定することでタブ区切りのcsvファイルに対応することができます。

		命令の実行中にエラーが起こった場合には、システム変数
		statが1になります。正常に変換された場合は、システム変数
		statは、0になります。


	csvnote p1,p2,p3			CSVの1行をメモリノート変換

	p1 = 結果が代入される文字列型の変数名
	p2 = CSVの1行を取り出した文字列
	p3 = 区切りキャラクターコード

	・説明

		CSV形式のデータから取り出した1行だけのデータを、
		メモリノートパッド形式の文字列型の変数に展開します。
		CSV形式は、「,」で区切られたテキストのデータです。
		たとえば、「a,b,c,d」のような「,」で区切られた4つの
		文字列があったとすると、csvstr命令を使うことで
		「"a\nb\nc\nd\n"」のようにメモリノートパッド命令で
		扱うデータ("\n"で区切られたデータ)として代入する
		ことができます。

		p3で区切りキャラクターを指定することができます。
		p3を省略または0にした場合は「,」が使用されます。
		9を指定することでタブ区切りのcsvファイルに対応することができます。

		命令の実行中にエラーが起こった場合には、システム変数
		statが1になります。正常に変換された場合は、システム変数
		statは、0になります。


	xnotesel p1,p2				排他メモリノート初期化

	p1 = 対象となる文字列型の変数名
	p2 = 項目の最大数(省略時は256)

	・説明

		排他メモリノートの初期化を行ないます。
		対象となる変数と、参照カウントのリセットが行なわれます。

		排他メモリノートは、メモリノートパッド命令で使用する
		ものと同じく、1行に1つの項目を持つ長い文字列型のデータ
		です。ただし、排他メモリノートは、異なる項目(行)しか
		追加することができません。
		すでに持っている項目を追加しようとすると、参照カウント
		だけが更新され、実際には追加されません。これにより、
		同じ文字列を重複しないで格納することや、重複の統計、
		文字列サーチなどに応用することができます。

		排他メモリノートは、xnoteselで対象となる変数を指定して、
		必要な場合は、最大項目数も設定します。
		以降は、xnoteadd命令を実行するごとに、排他メモリノート
		の変数に項目が追加されていきます。


	xnoteadd p1				排他メモリノート項目追加

	p1 = 排他メモリノートに追加される文字列

	・説明

		排他メモリノートに項目を追加します。
		項目は、改行を含まない文字列でなければいけません。
		実行すると、項目が追加されたインデックスが、システム
		変数statに代入されます。

		すでに排他メモリノートに含まれる項目は、追加されません。
		その場合は、システム変数statにすでに含まれる項目の
		インデックスが代入され、項目の参照カウントが1つ増やされます。
		項目の参照カウントは、sortget命令で取得することが可能です。


	csvsel val,mode			CSV検索の対象バッファを選択

		val  : CSV検索の対象となる文字列を格納した変数名
		mode : 区切りキャラクタコード

		・説明

		CSV検索の対象となるバッファを選択します。
		CSV形式またはノートパッド形式の文字列が格納されている変数を指定
		することができます。
		modeで区切りキャラクターを指定することができます。
		modeを省略または0にした場合は「,」が使用されます。
		9を指定することでタブ区切りのcsvファイルに対応することができます。


	csvres val				CSV検索の結果出力バッファを指定

		val  : CSV検索結果を出力する変数名

		・説明

		CSV検索の結果出力バッファを指定します。
		必ずある程度のサイズを確保した文字列型の変数にする必要があります。
		想定される出力結果に応じてsdim命令などでサイズをあらかじめ確保
		しておいてください。通常は32000バイト程度あれば十分です。
		出力結果のサイズがバッファを溢れてしまうような場合は、
		指定したバッファのサイズに収まる範囲で検索を中断しますので、
		バッファオーバーフローは起こりません。


	csvflag id,val			CSV検索の項目フラグを設定

		id  : 項目ID
		val : 設定値(0〜255)

		・説明

		CSV検索の対象となる項目単位でのフラグ設定を行ないます。
		項目idは、最も左にある項目を0として以降区切り記号ごとに右に1づつ
		増加していきます。


	csvopt p1				CSV検索のオプションを設定

		p1 : オプション値

		・説明

		CSV検索のオプション設定を行ないます。
		以下の値を指定することができます。複数指定する場合は、「+」か「|」
		の演算子でつなげることができます。

		CCSV_OPT_ANDMATCH		AND検索
		CCSV_OPT_NOCASE			半角大文字小文字を同一視
		CCSV_OPT_ZENKAKU		全角半角を同一視
		CCSV_OPT_ADDLINE		行番号を先頭に付加
		CCSV_OPT_EXPRESSION		正規表現を指定(未実装)


	csvfind "string",p1,p2		CSV検索を実行

		"string" : 検索キーワード
		p1       : 結果出力の最大数(0=無制限)
		p2       : 結果出力の開始インデックス(0=先頭)

		CSV検索を行ないます。
		必ず検索対象のバッファ(csvsel)と出力先(csvres)を指定しておく
		必要があります。
		"string"で指定されたキーワードを含むCSV行を結果バッファに抽出して
		いきます。キーワードは、複数行に渡って(メモリノートパッド形式)指定する
		ことができます。
		csvopt命令でAND検索のオプションを入れた場合は、複数キーワードすべてに
		一致する行だけを取り出します。そうでない場合は、複数キーワードの
		いずれかに一致する行を取り出すOR検索となります。


	rndf_ini p1				実数乱数の初期化

		p1(-1) : 初期化のシード値

		・説明

		実数乱数の初期化を行ないます。
		p1で初期化に使用される種(シード値)を指定することができます。
		p1を省略するか、-1を指定するとクロックから得られたランダムな
		シード値が設定されます。
		プラグインの初期化時に、実数乱数の初期化は行なわれるため、
		必ずしもrndf_ini命令を入れておく必要はありません。


	rndf_get p1				実数乱数を取得

		p1  : 実数乱数を代入する変数名

		・説明

		実数乱数を取得してp1で指定した変数に代入します。
		実数乱数は、0以上で1未満の実数となるもので、
		Mersenne Twisterアルゴリズムにより生成されます。


	rndf_geti p1,p2				乱数を取得

		p1       : 実数乱数を代入する変数名
		p2(100)  : 生成する乱数の範囲値

		・説明

		整数乱数を取得してp1で指定した変数に代入します。
		乱数は、0以上でp2で指定した数値未満の整数となります。
		ここで取得される乱数は、rndf_getで取得される実数乱数
		と同様のアルゴリズム(Mersenne Twister)により生成されます。


・変数データアクセス命令

	getvarid p1,"name"			変数IDを取得

		p1 : 結果が代入される変数名
		"name" : 変数名

		・説明

		変数名から、変数IDに変換を行ないます。
		変数IDは、HSPシステム内部で管理されている番号で、
		0から始まる値が割り当てられています。
		結果は、p1で指定された変数に代入されます。
		該当する変数名が存在しなかった場合には、-1が代入されます。


	getvarname p1,p2			変数名を取得

		p1 : 結果が代入される変数名
		p2 : 変数ID

		・説明

		変数IDから変数名を取得します。
		変数IDは、HSPシステム内部で管理されている番号で、
		0から始まる値が割り当てられています。
		結果は、p1で指定された変数に代入されます。
		該当する変数IDが存在しなかった場合には、空の文字列("")が
		代入されます。


	getmaxvar p1				変数IDの最大数を取得

		p1 : 結果が代入される変数名

		・説明

		現在利用可能な変数IDの最大数を取得します。
		結果は、p1で指定された変数に代入されます。
		変数IDは、HSPシステム内部で管理されている番号で、
		0から始まる値が割り当てられています。
		最大数が10の場合、利用可能な変数IDは、0から9となります。


	vsave "filename"			すべての変数を保存

		"filename" : ファイル名

		・説明

		定義されているすべての変数データをファイルに保存します。
		"filename"で指定されたファイルが作成されます。
		保存されたファイルは、vload命令またはvload_start命令による
		変数データ読み込みに使用することができます。
		vsave命令は、すべての変数の内容を配列やモジュール変数も
		含めて保存しますが、クローンされた変数、comobj型、variant型の
		変数は対象となりません。
		また、label型の変数の保存が可能ですが、読み込み時に正常な
		ラベル情報にならない可能性があるので注意してください。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vload "filename"			すべての変数を読み込み

		"filename" : ファイル名

		・説明

		定義されているすべての変数をファイルから読み込みます。
		"filename"で指定されるファイルは、vsave命令または
		vsave_start命令により変数データ保存されている必要があります。
		vload命令は、現在定義されているすべての変数名をファイルに
		保存されているデータから検索して、名前が一致したものを
		読み込みます。
		ファイルに保存されていない変数は、そのままの内容を保持します。
		また、モジュール型の変数は、保存した時点とモジュール名、
		モジュール変数定義数が同じでなければ読み込まれません。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vsave_start				変数保存の開始

		・説明

		個別指定による変数保存を開始します。
		必ず、vsave_start命令により開始した後、vsave_put命令によって
		必要な変数を指定した後、最後にvsave_end命令を実行する必要が
		あります。
		個別指定による変数保存は、任意の変数データをファイルに保存する
		ことができる以外は、vsave命令と同様です。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vsave_put p1				保存する変数の指定

		p1 : 保存する変数

		・説明

		個別指定による保存される変数を指定します。
		必ず、vsave_start命令を先に実行しておく必要があります。
		個別指定による変数保存は、任意の変数データをファイルに保存する
		ことができる以外は、vsave命令と同様です。
		すべての変数の内容を配列やモジュール変数も含めて保存しますが、
		クローンされた変数、comobj型、variant型の変数は対象となりま
		せん。
		また、label型の変数の保存が可能ですが、読み込み時に正常な
		ラベル情報にならない可能性があるので注意してください。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vsave_end "filename"			変数保存の終了

		"filename" : ファイル名

		・説明

		個別指定による変数保存を終了します。
		必ず、vsave_start命令を先に実行しておく必要があります。
		実行されると、"filename"で指定されたファイルが作成されます。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vload_start "filename"			変数読み込みの開始

		"filename" : ファイル名

		・説明

		個別指定による変数読み込みを開始します。
		必ず、vload_start命令により開始した後、vload_get命令によって
		必要な変数を指定した後、最後にvload_end命令を実行する必要が
		あります。
		個別指定による変数読み込みは、任意の変数データをファイルから
		読み込むことができる以外は、vload命令と同様です。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vload_get p1				読み込む変数の指定

		p1 : 読み込みを行なう変数

		・説明

		個別指定によりファイルから読み込まれる変数を指定します。
		必ず、vload_start命令を先に実行しておく必要があります。
		個別指定による変数読み込みは、任意の変数データをファイルから
		読み込むことができる以外は、vload命令と同様です。
		vload_get命令は、指定された変数名をファイルに保存されている
		データから検索して、名前が一致するデータがあった場合に
		読み込みます。
		ファイルに保存されていない場合は、変数の内容は保持されます。
		また、モジュール型の変数は、保存した時点とモジュール名、
		モジュール変数定義数が同じでなければ読み込まれません。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


	vload_end				変数読み込みの終了

		・説明

		個別指定による変数読み込みを終了します。
		必ず、vload_start命令を先に実行しておく必要があります。
		正常に終了した場合は、システム変数statに0が代入されます。
		正しく処理が完了していない場合、システム変数statは0以外の
		値になります。


・最後に

	プラグインの不具合をご報告頂いた方々、ソースの間違いをご指摘
	頂いた Ma_Ts さんに感謝いたします。


・実数乱数について

	実数の乱数取得には、Mersenne Twisterによる生成を使用しています。
	実装にあたり、松本眞氏、西村拓士氏によるソースコードを利用させて頂きました。
	また、HSPでの実装を提案頂いたmuuさんのソースも参考にさせて頂きました。

	http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/mt.html

	Coded by Takuji Nishimura and Makoto Matsumoto.
	Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
	All rights reserved.                          

	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
	CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
	LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
	NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


-------------------------------------------------------------------------------
                                                HSP users manual / end of file 
-------------------------------------------------------------------------------