yaklang-syntax

SKILL: Yaklang DSL の構文例

AI LOAD INSTRUCTION: Yaklang はセキュリティ研究向けに設計された DSL で、構文は Go に近いものの、より動的です。このページでは、そのまま実行できる構文例と、実際に存在するいくつかの「落とし穴」（第 5 節を参照）を紹介します。2 つのサンプル examples/syntax-tour.yak / examples/error-handling.yak は、どちらも yak <file> で実行してテストできます。Yaklang を記述するときは、構文を推測するのではなく、まずここを参考にしてください。

0. 関連ルート

• 入口：yak
• データベース操作の構文：yaklang-database
• 実践で構文を使用する（ホットリロード hook）：mitm-hotpatch / webfuzzer-hotpatch

1. 変数、型、コレクション

a = 10              // int, 整数除法截断: 10/3 == 3
name = "yaklang"    // string
ok = true           // bool
pi = 3.14           // float

nums = [1, 2, 3]            // 切片 (动态数组)
nums = append(nums, 4, 5)   // append 可追加多个
sub = nums[1:3]            // 切片表达式 -> [2, 3]

m = {"host": "a.com", "port": 443}  // map
v = m["port"]                        // 取值
exist = "host" in m                  // in 判断 key 是否存在
delete(m, "port")                    // 删除 key

2. 制御フロー

for i := 0; i < 5; i++ { sum += i }   // 经典三段式 for

for v in [10, 20, 30] { total += v }  // for-in: 单变量 = 元素值 (推荐)

if score >= 90 {
    grade = "A"
} else if score >= 60 {
    grade = "B"
} else {
    grade = "C"
}

3. 関数（重要。ホットリロードはすべて関数に依存します）

Yaklang では、関数は「値」です。リテラルを変数に代入する方法を推奨します。

add = func(a, b) { return a + b }     // func 字面量
add = fn(a, b) { return a + b }       // fn / def 等价于 func
func named(a, b) { return a + b }     // 命名函数

twice = (x) => { return x * 2 }       // 箭头函数 (热加载 hook 常用写法)

addsub = func(a, b) { return a + b, a - b }   // 多返回值
s, d = addsub(7, 3)                            // 多重赋值

makeCounter = func() {                 // 闭包: 捕获并保持状态
    n = 0
    return func() { n++; return n }
}

sumAll = func(args...) {               // 可变参数
    t = 0
    for v in args { t += v }
    return t
}

ホットリロード hook は、まさに「関数を規定の名前の変数に代入する」ことです。例：

beforeRequest = func(https, originReq, req) { return req }
hijackHTTPRequest = (isHttps, url, req, forward, drop) => { forward(req) }

完全に実行できるサンプル：examples/syntax-tour.yak

4. 文字列テンプレートとエラー処理

f-string の補間

line = f"user=${user} port=${port}"   // -> "user=admin port=8080"
msg = sprintf("%d-%s", 7, "x")        // -> "7-x"

エラー処理の三つの基本技（重要）

Yaklang のライブラリ関数は、最後の戻り値を error とするのが一般的です。次の 3 つの処理方法は同等です。

// 1) 手动判断 (最显式, 可自定义降级)
ret, err = codec.DecodeBase64(s)
if err != nil { /* 降级或 return */ }

// 2) die: err 非 nil 才 panic
ret, err = codec.DecodeBase64(s)
die(err)

// 3) ~ 波浪号 (WavyCall): 出错即自动 panic, "出错就该终止"时最简洁
ret = codec.DecodeBase64(s)~

クラッシュの捕捉には defer + recover を使います。

defer func {
    e = recover()
    if e != nil { log.error("caught: %v", e) }
}

完全に実行できるサンプル：examples/error-handling.yak

5. 実際に存在する「落とし穴」（Yaklang を記述する前に必読）

以下は実際に試して見つかった問題で、AI が Yaklang を記述する際に間違えやすいものです。

落とし穴	誤った書き方	正しい書き方
for-range で _ をプレースホルダーに使うと、値が undefined になる	for _, v in slice { total += v }	for v in slice { ... }（単一変数の場合は要素の値になります）、または for i, v in slice のように実際のインデックス名を使います
アロー関数の式本体は解析されない	f = (x) => x * 2	f = (x) => { return x * 2 }
double などは組み込み識別子の可能性があります	double = ... は compile error を引き起こします	twice / dbl など、別の名前にします
組み込みのランダムバイト関数の名前は RandomBytes ではありません	codec.RandomBytes(n)	codec.Md5(sprintf("%d", time.Now().UnixNano())) などで代用するか、自分で構築します
recover 後に値を返そうとしても、panic によって return はすでにスキップされています	外側の defer recover で return result を実行する（実行されません）	クラッシュしやすいロジックを内側の run() に入れ、内側で recover して捕捉し、外側では通常どおり return します

API や構文が不確かな場合は、スクリプト内で desc(オブジェクト) を使ってメソッドを確認するか、go run common/yak/cmd/yak.go xxx.yak で直接試してください。入念に調べることを誇りとし、インターフェースを憶測することを恥としましょう。

6. 検証

cd /Users/v1ll4n/Projects/yaklang
go run common/yak/cmd/yak.go skills/yaklang-syntax/examples/syntax-tour.yak
go run common/yak/cmd/yak.go skills/yaklang-syntax/examples/error-handling.yak

各サンプルでは、assert がすべて成功し、log がすべて英語で、... self test passed が表示されることを確認してください。

参考資料

• yaklang-ai-training-materials/basic-syntax: cap3 変数と式 / cap4 制御フロー / cap5 関数 / cap6-2 エラー処理 / cap6-5 fuzztag
• yaklang.github.io 公式構文ドキュメント