IronHSP (hsp3net) 内部仕様書

HSP3 .NET Framework 統合ランタイム — コンパイラ・ランタイム拡張仕様 — 最終更新: 2026-04-18

対象: IronHSP (OpenHSP 3.8beta1 ベース) / .NET Framework 4.8 / ツールセット v143 (VS2022)

1. アーキテクチャ概要

IronHSP (hsp3net) は OpenHSP 3.8beta1 をベースに、以下のレイヤーを追加した .NET Framework 統合ランタイムです。

┌─────────────────────────────────────────────────┐
│  HSP スクリプト (.hsp)                           │
├─────────────────────────────────────────────────┤
│  hspcmp (拡張コンパイラ)                         │
│   - #defstruct / #defunion / #field             │
│   - #defcbcom / #cbmethod                       │
│   - #cfuncst / #cfuncd / #cfuncf                │
│   - intptr 型 / Allman ブレース                  │
├─────────────────────────────────────────────────┤
│  .ax (拡張中間コード)                            │
├─────────────────────────────────────────────────┤
│  hsp3net ランタイム                              │
│  ┌───────────────────────────────────────────┐  │
│  │ コア (hsp3code / hsp3int)                 │  │
│  │  - NSTRUCT / MAP / WSTR / INT64 型        │  │
│  │  - dimmap / delmap / structdim 命令        │  │
│  │  - _struct_poke / _struct_peek             │  │
│  ├───────────────────────────────────────────┤  │
│  │ Win32 GUI / DLL 拡張 (hsp3ext_win)        │  │
│  │  - callfuncst / callfuncd / callfuncf     │  │
│  │  - COM コールバック (動的 thunk 生成)      │  │
│  │  - コールバック thunk (x86/x64)            │  │
│  ├───────────────────────────────────────────┤  │
│  │ .NET 連携レイヤー (C++/CLI)               │  │
│  │  - Hsp3Net (リフレクション)               │  │
│  │  - GlobalAccess (GCHandle 管理)           │  │
│  │  - HspForms (WinForms 統合)               │  │
│  │  - NETOBJ 変数型                          │  │
│  │  - HspCallbackProxy (デリゲートブリッジ)   │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

バニラ HSP3 との主な違い

2. コンパイラ (hspcmp) 拡張

2.1 構造体定義 (#defstruct / #defunion / #field)

Win32 API や DLL とのデータ交換で必要な C 構造体互換のバイナリレイアウト を HSP スクリプトから定義できます。

構文

#defstruct [global] 構造体名 [, pack=N]
    #field 型名 メンバ名 [配列サイズ]
    ...
    #defunion                    ; ネストされた共用体開始
        #field ...
    #endunion
#endstruct

#defunion 共用体名              ; トップレベル共用体
    #field ...
#endunion

対応するフィールド型

アライメント (pack)

デフォルトは pack=8 で MSVC の C 構造体 ABI に準拠します。各メンバのオフセットは min(フィールド自然アライメント, pack値) の倍数に揃えられます。構造体全体のサイズは最大メンバアライメントの倍数に切り上げられます。

使用例

#defstruct POINT
    #field int x
    #field int y
#endstruct

#defstruct RECT
    #field int left
    #field int top
    #field int right
    #field int bottom
#endstruct

; global で宣言すると #module 内からも参照可能
#defstruct global GUID, pack=1
    #field int   Data1
    #field short Data2
    #field short Data3
    #field byte  Data4 8
#endstruct

; 使い方
stdim pt, POINT        ; NSTRUCT 変数を確保
pt->x = 100
pt->y = 200
mes "x=" + pt->x

global キーワード

#defstruct global 名前 で宣言すると、構造体名がグローバルスコープに登録され、任意の #module 内から参照できます。省略するとファイルスコープです。

2.2 アロー演算子 (->) によるメンバアクセス

#defstruct で定義した構造体の NSTRUCT 変数に対して、C 言語風の -> 演算子でメンバを読み書きできます。

stdim rc, RECT
rc->left = 10
rc->top = 20
rc->right = 640
rc->bottom = 480
mes "width = " + (rc->right - rc->left)

内部展開

プリプロセッサフェーズで以下のように展開されます:

ネストされた構造体チェーン a->b->c や配列インデックス arr(i)->member もサポートされています。

2.3 COM コールバック (#defcbcom / #cbmethod)

任意の COM インターフェースを HSP スクリプトから実装できます。IDropTarget, IBindStatusCallback 等の COM コールバックをスクリプト側で処理するために使用します。

構文

#defcbcom クラス名 インターフェース名
    #cbmethod vtableインデックス 戻り値型 [引数型, ...] *ラベル
    ...
#endcbcom

パラメータ

使用例 (IDropTarget)

#usecom IDropTarget "{00000122-0000-0000-C000-000000000046}"

#defcbcom MyDropTarget IDropTarget
    ; vtable 3: DragEnter(pDataObj, grfKeyState, pt_lo, pt_hi, pdwEffect)
    #cbmethod 3 int comobj, int, int, int, intptr, *on_drag_enter
    ; vtable 4: DragOver
    #cbmethod 4 int int, int, int, intptr, *on_drag_over
    ; vtable 5: DragLeave
    #cbmethod 5 int *on_drag_leave
    ; vtable 6: Drop
    #cbmethod 6 int comobj, int, int, int, intptr, *on_drop
#endcbcom

; インスタンス化
newcomcb myobj, "MyDropTarget"
; myobj は COM オブジェクトとして Win32 API に渡せる

*on_drag_enter
    ; comprm(N) で引数取得
    key_state = comprm(1)
    comret 0  ; S_OK
    return

*on_drop
    comret 0  ; S_OK
    return

コールバック内で使える命令・関数

2.4 DLL 関数戻り値拡張 (#cfuncst / #cfuncd / #cfuncf)

バニラ HSP の #cfunc は int 戻り値しかサポートしていません。IronHSP では構造体・double・float 戻り値に対応しています。

#cfuncst の構文

; 新形式 (構造体名指定)
#cfuncst [global] 構造体名 関数名 "エントリポイント" [パラメータ型...]

; レガシー形式 (サイズ直指定)
#cfuncst [global] 関数名 "エントリポイント" サイズ [, パラメータ型...]

動作原理

C/C++ で構造体を値で返す関数は、実際には呼び出し元が確保したバッファへのポインタを隠し第1引数 (x64: RCX, x86: スタック先頭) として渡します。#cfuncst はこの 隠し引数挿入 を自動的に行います。

; C 側: POINT GetCursorPos2(void)
; 実際の ABI: void GetCursorPos2(POINT *__retval)

#defstruct POINT
    #field int x
    #field int y
#endstruct

#uselib "mylib.dll"
#cfuncst POINT GetCursorPos2 "GetCursorPos2"

; 呼び出し (戻り値は NSTRUCT 変数に自動格納)
pt = GetCursorPos2()
mes pt->x + ", " + pt->y

2.5 新規キーワード一覧

プログラム制御命令 (TYPE_PROGCMD = 15)

拡張命令 (TYPE_EXTCMD = 8)

拡張関数 (TYPE_INTFUNC = 13)

DLL コントロール (TYPE_DLLCTRL = 17)

2.6 intptr 型

intptr はプラットフォームのポインタ幅に合わせて 32bit 環境では 4 バイト、64bit 環境では 8 バイトとなる整数型です。

#func, #cfunc, #comfunc 等のパラメータ型として intptr を指定できます。DLL の void*, HANDLE, HWND, LPARAM 等のポインタ引数に使用してください。

#uselib "user32.dll"
#cfunc FindWindowW "FindWindowW" wstr, wstr
#func SetWindowTextW "SetWindowTextW" intptr, wstr

hwnd = FindWindowW("Notepad", 0)
SetWindowTextW hwnd, "Hello"

2.7 Allman ブレーススタイル

バニラ HSP では if の後にブレースを同一行に書く必要がありましたが、IronHSP では 次の行にブレースを置く Allman スタイル もサポートしています。

; K&R スタイル (従来通り動作)
if a > 0 {
    mes "positive"
}

; Allman スタイル (IronHSP で追加)
if a > 0
{
    mes "positive"
}

実装: codegen.cpp の if 解析で、行末 { がなかった場合に次行の先頭を先読みして { を検出します。

3. ランタイム拡張

3.1 新規変数型

バニラ HSP の変数型: 0=なし, 1=label, 2=str, 3=double, 4=int, 5=struct, 6=comobj (最大 FLAG=10)

3.2 NSTRUCT (ネイティブ構造体)

目的

Win32 API や C DLL とのデータ交換で必要な バイナリレイアウトを正確に保持 する変数型です。バニラ HSP の TYPE_STRUCT (モジュール変数) とは異なり、名前付きフィールドではなくバイトオフセットで直接メモリにアクセスします。

メモリレイアウト

PVal
  ├─ flag = HSPVAR_FLAG_NSTRUCT (11)
  ├─ len[0] = 要素サイズ (バイト数)   例: POINT なら 8
  ├─ len[1] = 配列サイズ             例: 10 個なら 10
  ├─ pt → calloc(要素サイズ * 配列サイズ) で確保した生バッファ
  └─ mode = HSPVAR_MODE_MALLOC

確保方法

; #defstruct で定義した構造体名を使用
stdim var, POINT          ; POINT サイズの NSTRUCT を 1 個確保
stdim arr, RECT, 10       ; RECT サイズの配列を 10 個確保

; cfuncst の戻り値は自動的に NSTRUCT になる
pt = GetSomePoint()       ; 暗黙確保 (hsp_nstruct_pending_size で通知)

サポート操作

• Set/Get: memcpy ベースのバイナリコピー
• _struct_poke / _struct_peek: メンバ単位の読み書き (-> 演算子から呼び出し)
• サポートフラグ: FIXEDARRAY, FLEXSIZE

_struct_poke のメンバ型コード

3.3 MAP (連想配列)

内部実装

// hspvar_map.cpp
struct MapData {
    std::unordered_map<std::string, std::string> entries;
    std::string current_key;    // ArrayObject の書き込みターゲットキー
    std::string read_buf;       // ArrayObjectRead の戻りバッファ
};

特徴

• キー・値ともに 文字列型 (std::string)
• map("key") = value で代入、map("key") で読み取り
• HspVarProc の ArrayObject / ArrayObjectRead フックで配列添字アクセスを横取り
• サポートフラグ: STORAGE, ARRAYOBJ, NOCONVERT, VARUSE

API

; 確保
dimmap m

; 書き込み
m("name") = "Alice"
m("age") = "30"

; 読み取り
mes m("name")              ; "Alice"

; 存在確認
if hasmap(m, "name") { mes "found" }

; エントリ数
mes "count = " + mapcount(m)

; キー一覧
repeat mapcount(m)
    mes mapkey(m, cnt)
loop

; 削除
delmap m, "name"

; 全消去
mapclear m

3.4 WSTR (UTF-16 ワイド文字列)

Win32 W 版 API に直接渡せる UTF-16 (Little Endian) 文字列型です。

wsdim ws, 260        ; 260 wchar_t 分のバッファ確保

#func / #cfunc のパラメータ型として wstr を指定すると、HSP 文字列 (UTF-8) から自動的に UTF-16 に変換されて渡されます。var で受け取った場合は変換されず、UTF-16 バイト列がそのまま格納されます。

3.5 INT64 (64ビット整数)

dim64 v, 10          ; INT64 配列を 10 要素確保

8バイト (64ビット) 整数配列です。Win32 API の LARGE_INTEGER, FILETIME 等のデータ格納に使用します。

3.6 新規命令・関数

Section 2.5 の一覧も参照してください。ここでは使い方を解説します。

環境変数操作

; 環境変数を設定
setenv "MY_KEY", "MY_VALUE"

; 環境変数を取得 (UTF-8)
val = getenv("PATH")
val2 = getenv("MISSING", "default")   ; デフォルト値指定

; 存在確認
if hasenv("MY_KEY") { mes "exists" }

; 削除
delenv "MY_KEY"

コマンドライン引数

; 引数の数
n = getcmdargc()

; N番目の引数 (0始まり, 0=実行ファイル名)
repeat n
    mes getcmdarg(cnt)
loop

; 名前付き引数: program.exe --port 8080 --name test
port = getcmdargs("--port", "3000")     ; デフォルト "3000"
name = getcmdargs("--name", "unknown")

内部では CommandLineToArgvW() + UTF-8 変換を使用。最初の呼び出し時に 1 回だけパースしてキャッシュします。

4. .NET Framework 連携

4.1 アーキテクチャ

.NET 連携は C++/CLI で実装されています。HSP ランタイム (ネイティブ C++) と .NET マネージドコード (C#/VB.NET) の間を C++/CLI がブリッジします。

HSP スクリプト
    │ mcall / newnet / callnet
    ▼
hsp3ext_win.cpp (ネイティブ C++)
    │ Hsp3Net::InvokeMethod() 等
    ▼
Hsp3Net.h / Hsp3Net.cpp (C++/CLI マネージドラッパー)
    │ System::Reflection
    ▼
.NET Framework (System.*, System.Windows.Forms, etc.)

主要クラス

4.2 NETOBJ 変数型

NETOBJ (FLAG=9) は .NET オブジェクトへのネイティブポインタ (GCHandle) を格納する変数型です。

ライフサイクル

1. newnet var, "System.Collections.ArrayList" で .NET インスタンス作成
2. GlobalAccess::CreateNativePtr() が GCHandle.Alloc() でマネージドオブジェクトをピン留め
3. ネイティブポインタ (void*) を PVal に格納
4. delnet var で GlobalAccess::Free() → GCHandle.Free()

スコープ管理

GlobalAccess は 2 つのセットでポインタを追跡します:

• _NativePtrAllSet: 全てのアクティブな GCHandle
• _NativePtrCurrentScopeSet: 現在のスコープで作成された GCHandle (スタック式)

PushNativePtrCurrentStack() / PopNativePtrCurrentStack() で関数呼び出しスコープに連動した自動解放を行います。

型変換

4.3 .NET 操作命令

loadnet のオプション

4.4 C# ソースコンパイル

loadnet の opt=3 で C# ソースコードを動的コンパイルして即座にロードできます。

cs = {"
using System;
public class MyMath {
    public static int Add(int a, int b) { return a + b; }
    public static string Greet(string name) {
        return "Hello, " + name + "!";
    }
}
"}
loadnet cs, 3

; 静的メソッド呼び出し
newnet dummy, "MyMath"
mcall dummy, "Add", result, 10, 20
mes result    ; 30

mcall dummy, "Greet", greeting, "HSP"
mes greeting  ; "Hello, HSP!"

loadnet cs, 3, "System.Xml.dll", "System.Xml.Linq.dll"

4.5 WinForms 統合

hsp3net の GUI ランタイムは内部で System.Windows.Forms.Form をホストし、HSP のウィンドウと WinForms コントロールをハイブリッドで管理します。

HspFormsInterop が提供するネイティブ関数

上位レベルでは iron_forms.hsp が mcall 経由で DataGridView, PropertyGrid, TabControl, Anchor/Dock 等の高機能コントロールを提供します。

4.6 コールバック・デリゲート

HspCallbackProxy クラスが HSP ラベルを .NET デリゲートにブリッジします。

対応デリゲートパターン

内部では HSP の code_callback() を呼び出し、HSP スクリプト上の *label にジャンプ → stat を戻り値として回収します。

5. COM コールバック実装

動的 Thunk 生成

COM インターフェースの vtable メソッドが呼ばれた際に HSP ラベルにジャンプするために、動的にマシンコードを生成 (JIT thunk) しています。

x64 版 Thunk

; 512 バイトのコードバッファ
; RCX, RDX, R8, R9 → args[0..3] に保存
; スタック引数 → args[4+] に保存
; R10/R11 をスクラッチレジスタとして使用
; hsp_cbcom_bridge() を呼び出し

x86 版 Thunk

; 256 バイトのコードバッファ
; スタック引数をコピー
; __cdecl 呼び出し規約
; hsp_cbcom_bridge() を呼び出し

VirtualAlloc で PAGE_EXECUTE_READWRITE メモリを確保し、マシンコードを書き込みます。vtable にこの thunk のアドレスを設定することで、COM メソッド呼び出しが HSP ラベルにディスパッチされます。

IUnknown 自動実装

• QueryInterface: クラスの IID と比較。一致すれば *ppv = this、不一致は E_NOINTERFACE
• AddRef: InterlockedIncrement(&refcount)
• Release: InterlockedDecrement(&refcount)。0 でクリーンアップ

6. 64ビット対応

コンパイル時定義

.ax ファイルフォーマットの差異

.ax (オブジェクトファイル) は 32bit アラインメントで保存されるため、64bit ランタイムではポインタフィールドの変換が必要です:

DLL 関数呼び出しの差異

7. 環境変数・コマンドライン

バニラ HSP にはない環境変数・コマンドライン引数操作を追加しています。全て UTF-8 で処理されます。

環境変数

setenv "KEY", "VALUE"             ; 設定 (内部: MultiByteToWideChar + SetEnvironmentVariableW)
val = getenv("KEY")               ; 取得 (内部: GetEnvironmentVariableW + WideCharToMultiByte)
val = getenv("KEY", "default")    ; デフォルト値付き
if hasenv("KEY") { ... }          ; 存在確認
delenv "KEY"                      ; 削除

コマンドライン引数

n = getcmdargc()                  ; 引数数 (内部: CommandLineToArgvW)
arg0 = getcmdarg(0)               ; 実行ファイルパス
arg1 = getcmdarg(1)               ; 第1引数

; 名前付き引数: --key value 形式
port = getcmdargs("--port", "8080")

8. 注意事項・落とし穴

; NG: LOG_DEBUG が log_debug にもマッチする
#define LOG_DEBUG 0
log_debug "msg"    ; → 0 "msg" に展開されてエラー

; OK: プレフィックスで回避
#define LOGLV_DEBUG 0

; NG
FindWindowW "Notepad", 0

; OK
hwnd = FindWindowW("Notepad", 0)

#defcfunc my_func str s
    local ss
    ss = s          ; ローカルにコピー
    c = peek(ss, 0) ; OK
    return c

; NG: stat は直前の API 戻り値のまま
#deffunc my_read str key
    return "value"   ; refstr に入る, stat は不定

; OK: var で明示出力
#deffunc my_read str key, var out_result
    out_result = "value"
    return 0         ; stat = 0

9. ソースファイル一覧

コンパイラ (hspcmp/)

ランタイム (hsp3net/)

.NET 連携 (hsp3net/win32gui/)