------------------------------------------------------------------------------ HSPDA ver3.0 REFERENCE MANUAL HSP : Hot Soup Processor ＨＳＰ拡張DLLリファレンス copyright 1999-2005 (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の機能が拡張され、このリファレンスで説明を している命令を使用することができるようになります。 まず最初に、試しに付属のサンプルスクリプトを実行してみてください。 拡張された機能の簡単な使用例を見ることができるはずです。 ・更新履歴 2005/6/3 sortnote、sortstr命令をHSP3専用に修正。 rndf_ini、rndf_get、rndf_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ファイルを作成した場合でも、HSPDA.DLLをEXEファイルと同じディレクトリ に置かないと動作しません。また、packfileにDLLを追加することはできません。 ・著作権および連絡先 著作権および、使用の規定についてはHot Soup Processor ver3.0と同様です。 営利・非営利を問わずHSPDA.DLLを自由に配布してかまいません。 onion softwareは本プログラムによって生じた、いかなる損害についても 保証いたしません。自己の責任の範囲で使用してください。 HSPDA.DLLは、Microsoft Visual C++ 7.1でコンパイルされて います。 ・命令一覧 sortval p1,p2 配列変数を数値でソート sortstr p1,p2 配列変数を文字列でソート sortnote p1,p2 メモリノート文字列をソート sortget p1,p2 ソート元のインデックスを取得 csvstr p1,p2,p3 CSVの１行を配列に変換 csvnote p1,p2,p3 CSVの１行をメモリノート変換 xnotesel p1,p2 排他メモリノート初期化 xnoteadd p1 排他メモリノート項目追加 csvsel val,mode CSV検索の対象バッファを選択 csvres val CSV検索の結果出力バッファを指定 csvflag id,val CSV検索の項目フラグを設定 csvopt p1 CSV検索のオプションを設定 csvfind "string" CSV検索を実行 rndf_ini p1 実数乱数の初期化 rndf_get p1 実数乱数を取得 rndf_geti p1,p2 乱数を取得 ・データアクセス命令 テキストやCSVなどの各種データ形式を手軽に扱うための命令セットです。 データの並び替え(ソート)を高速に行なうことができるほか、 メモリノートパッド命令と組み合わせることで、CSV形式のファイルから データを取り出すことが可能になります。 sortval p1,p2 配列変数を数値でソート p1 = 数値型の配列変数名 p2 = 並び順(0=小さい順/1=大きい順) ・説明 数値が格納された配列変数を、指定された並び順でソート (並び替え)します。 p1で指定された配列変数を直接並べ替えます。 並び替えに関する情報は、sortget命令で得ることができます。 sortstr p1,p2 配列変数を文字列でソート p1 = 文字列型の配列変数名 p2 = 並び順(0=小さい順/1=大きい順) ・説明 文字列が格納された配列変数を、指定された並び順でソート (並び替え)します。 p1で指定された配列変数を直接並べ替えます。 ソートの並び順は、ASCIIコードの大きい小さいで比較される ので、ABC順、あいうえお順に並べ替えられます。 並び替えに関する情報は、sortget命令で得ることができます。 sortnote p1,p2 メモリノート文字列をソート p1 = メモリノート形式の文字列型の変数名 p2 = 並び順(0=小さい順/1=大きい順) ・説明 メモリノートパッド形式の文字列が格納された変数を、指定 された並び順でソート(並び替え)します。 p1で指定された変数を直接並べ替えます。 ソートの並び順は、ASCIIコードの大きい小さいで比較される ので、ABC順、あいうえお順に並べ替えられます。 並び替えに関する情報は、sortget命令で得ることができます。 メモリノートパッド形式は、notesel,noteget命令などで使用 することのできる「\n」(改行コード)で区切られたデータ列の ことです。 sortget p1,p2 ソート元のインデックスを取得 p1 = 結果が代入される変数名 p2 = インデックスNo. ・説明 sortstr,sortval,sortnote命令を実行後の配列において、 格納されているデータは、ソートする前はどのインデックスに 置かれていたものかを調べて結果を返します。 たとえば、配列変数aをソートした後、sortget n,4という命令で、 1という値が返ってきたとすると、a.4という配列変数に現在入って いる値は、ソートする前には、a.1に入っていたことを示します。 この命令は、データの一部だけをソートして、その情報をもとに ほかのデータの並び替えも行なうような時に有効です。 csvstr p1,p2,p3 CSVの１行を配列に変換 p1 = 結果が代入される文字列型の配列変数名 p2 = CSVの１行を取り出した文字列 p3 = 区切りキャラクターコード ・説明 CSV形式のデータから取り出した１行だけのデータを、 文字列型の配列変数に展開します。 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の１行をメモリノート変換 p1 = 結果が代入される文字列型の変数名 p2 = CSVの１行を取り出した文字列 p3 = 区切りキャラクターコード ・説明 CSV形式のデータから取り出した１行だけのデータを、 メモリノートパッド形式の文字列型の変数に展開します。 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つの項目を持つ長い文字列型のデータ です。ただし、排他メモリノートは、異なる項目(行)しか 追加することができません。 すでに持っている項目を追加しようとすると、参照カウント だけが更新され、実際には追加されません。これにより、 同じ文字列を重複しないで格納することや、重複の統計、 文字列サーチなどに応用することができます。 排他メモリノートは、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)により生成されます。 ・最後に 並び替え(ソート)は、データが大きくなるほどHSPで行なう場合に 時間がかかるようになってしまいます。 このDLLでは、主にその速度低下を押さえるためのものです。 数値データのソートは、クイックソートと呼ばれる方法で、 文字列データのソートは、バブルソートと呼ばれている方法で 行なっています。 どちらも、単純なデータであればすぐに並び替えを終わらせる ことができるはずです。 プラグインの不具合をご報告頂いた方々、ソースの間違いをご指摘 頂いた 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 -------------------------------------------------------------------------------