From 56b76f68f127e438880bbd1a6178c67bd7d59cab Mon Sep 17 00:00:00 2001 From: Li Jin Date: Wed, 22 Apr 2026 16:41:46 +0800 Subject: Updated docs. --- doc/docs/de/doc/advanced/macro.md | 56 +++++++++++++++++++++++++++++++++++ doc/docs/doc/advanced/macro.md | 56 +++++++++++++++++++++++++++++++++++ doc/docs/id-id/doc/advanced/macro.md | 56 +++++++++++++++++++++++++++++++++++ doc/docs/pt-br/doc/advanced/macro.md | 56 +++++++++++++++++++++++++++++++++++ doc/docs/zh/doc/advanced/macro.md | 56 +++++++++++++++++++++++++++++++++++ doc/yue-de.md | 27 +++++++++++++++++ doc/yue-en.md | 27 +++++++++++++++++ doc/yue-id-id.md | 27 +++++++++++++++++ doc/yue-pt-br.md | 27 +++++++++++++++++ doc/yue-zh.md | 27 +++++++++++++++++ spec/outputs/codes_from_doc_de.lua | 24 +++++++++++++++ spec/outputs/codes_from_doc_en.lua | 24 +++++++++++++++ spec/outputs/codes_from_doc_id-id.lua | 24 +++++++++++++++ spec/outputs/codes_from_doc_pt-br.lua | 24 +++++++++++++++ spec/outputs/codes_from_doc_zh.lua | 24 +++++++++++++++ 15 files changed, 535 insertions(+) diff --git a/doc/docs/de/doc/advanced/macro.md b/doc/docs/de/doc/advanced/macro.md index a030aea..d0760b5 100644 --- a/doc/docs/de/doc/advanced/macro.md +++ b/doc/docs/de/doc/advanced/macro.md @@ -229,6 +229,62 @@ print "Gültiger Enum-Typ:", $BodyType Static +## Mehrzeiligen Yue-Code erzeugen + +Wenn ein Makro mehrzeiligen Yue-Code zurückgibt, ist eine mehrzeilige Zeichenkette in Anführungszeichen nicht zu empfehlen. Verwende stattdessen bevorzugt `-> |`. + +Eine Zeichenkette in Anführungszeichen behält den Text wörtlich bei, während ein YAML-Mehrzeilen-String die gemeinsame führende Einrückung entfernt. Dadurch bleiben erzeugte Yue-Blöcke in der Regel stabiler, besonders wenn der erzeugte Code Kommentare oder verschachtelte Blöcke enthält. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + ## Argument-Validierung Du kannst erwartete AST-Knotentypen in der Argumentliste deklarieren und zur Compile-Zeit prüfen, ob die übergebenen Makroargumente den Erwartungen entsprechen. diff --git a/doc/docs/doc/advanced/macro.md b/doc/docs/doc/advanced/macro.md index c057f40..935017e 100644 --- a/doc/docs/doc/advanced/macro.md +++ b/doc/docs/doc/advanced/macro.md @@ -229,6 +229,62 @@ print "Valid enum type:", $BodyType Static +## Generating Multi-line Yue Code + +When a macro returns multi-line Yue code, using a quoted multi-line string is not recommended. Prefer `-> |` instead. + +A quoted string keeps the literal text as-is, while a YAML multiline string removes the common leading indentation. This usually makes generated Yue blocks more stable, especially when the generated code contains comments or nested blocks. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + ## Argument Validation You can declare the expected AST node types in the argument list, and check whether the incoming macro arguments meet the expectations at compile time. diff --git a/doc/docs/id-id/doc/advanced/macro.md b/doc/docs/id-id/doc/advanced/macro.md index d33ec5b..5f0021b 100644 --- a/doc/docs/id-id/doc/advanced/macro.md +++ b/doc/docs/id-id/doc/advanced/macro.md @@ -229,6 +229,62 @@ print "Valid enum type:", $BodyType Static +## Menghasilkan kode Yue multi-baris + +Saat macro mengembalikan kode Yue multi-baris, penggunaan string multi-baris di dalam tanda kutip tidak direkomendasikan. Sebaiknya gunakan `-> |`. + +String bertanda kutip mempertahankan teks apa adanya, sedangkan string multi-baris YAML menghapus indentasi awal yang sama. Ini biasanya membuat blok Yue yang dihasilkan lebih stabil, terutama ketika kode yang dihasilkan berisi komentar atau blok bertingkat. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + ## Validasi Argumen Anda dapat mendeklarasikan tipe node AST yang diharapkan dalam daftar argumen, dan memeriksa apakah argumen macro yang masuk memenuhi harapan pada waktu kompilasi. diff --git a/doc/docs/pt-br/doc/advanced/macro.md b/doc/docs/pt-br/doc/advanced/macro.md index 18d33e0..d1025d1 100644 --- a/doc/docs/pt-br/doc/advanced/macro.md +++ b/doc/docs/pt-br/doc/advanced/macro.md @@ -228,6 +228,62 @@ print "Valid enum type:", $BodyType Static +## Gerando código Yue em múltiplas linhas + +Quando uma macro retorna código Yue em múltiplas linhas, não é recomendado usar uma string multilinha entre aspas. Prefira `-> |`. + +Uma string entre aspas preserva o texto literal, enquanto uma string multilinha estilo YAML remove a indentação inicial comum. Isso normalmente deixa os blocos Yue gerados mais estáveis, especialmente quando o código gerado contém comentários ou blocos aninhados. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + ## Validação de argumentos Você pode declarar os tipos de nós AST esperados na lista de argumentos e verificar se os argumentos da macro recebidos atendem às expectativas em tempo de compilação. diff --git a/doc/docs/zh/doc/advanced/macro.md b/doc/docs/zh/doc/advanced/macro.md index 64cfa6d..7027f62 100644 --- a/doc/docs/zh/doc/advanced/macro.md +++ b/doc/docs/zh/doc/advanced/macro.md @@ -229,6 +229,62 @@ print "有效的枚举类型:", $BodyType Static +## 生成多行 Yue 代码 + +  当宏返回多行 Yue 代码时，不推荐使用带引号的多行字符串，建议优先使用 `-> |`。 + +  带引号的字符串会按字面保留文本；而 YAML 风格多行字符串会移除公共前导缩进。对宏生成的 Yue 代码来说，这通常能让代码块结构更稳定，尤其是在生成代码里包含注释或嵌套块时。 + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + + + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + +```yue +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + + + ## 宏参数检查   可以直接在参数列表中声明期望的 AST 节点类型，并在编译时检查传入的宏参数是否符合预期。 diff --git a/doc/yue-de.md b/doc/yue-de.md index 97063f4..0d4fa7a 100644 --- a/doc/yue-de.md +++ b/doc/yue-de.md @@ -183,6 +183,33 @@ print "Gültiger Enum-Typ:", $BodyType Static -- print "Kompilierungsfehler bei Enum-Typ:", $BodyType Unknown ``` +## Mehrzeiligen Yue-Code erzeugen + +Wenn ein Makro mehrzeiligen Yue-Code zurückgibt, ist eine mehrzeilige Zeichenkette in Anführungszeichen nicht zu empfehlen. Verwende stattdessen bevorzugt `-> |`. + +Eine Zeichenkette in Anführungszeichen behält den Text wörtlich bei, während ein YAML-Mehrzeilen-String die gemeinsame führende Einrückung entfernt. Dadurch bleiben erzeugte Yue-Blöcke in der Regel stabiler, besonders wenn der erzeugte Code Kommentare oder verschachtelte Blöcke enthält. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + ## Argument-Validierung Du kannst erwartete AST-Knotentypen in der Argumentliste deklarieren und zur Compile-Zeit prüfen, ob die übergebenen Makroargumente den Erwartungen entsprechen. diff --git a/doc/yue-en.md b/doc/yue-en.md index 8f8370d..2c97b28 100644 --- a/doc/yue-en.md +++ b/doc/yue-en.md @@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static -- print "Compilation error with enum type:", $BodyType Unknown ``` +## Generating Multi-line Yue Code + +When a macro returns multi-line Yue code, using a quoted multi-line string is not recommended. Prefer `-> |` instead. + +A quoted string keeps the literal text as-is, while a YAML multiline string removes the common leading indentation. This usually makes generated Yue blocks more stable, especially when the generated code contains comments or nested blocks. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + ## Argument Validation You can declare the expected AST node types in the argument list, and check whether the incoming macro arguments meet the expectations at compile time. diff --git a/doc/yue-id-id.md b/doc/yue-id-id.md index 39ba24d..8661ecf 100644 --- a/doc/yue-id-id.md +++ b/doc/yue-id-id.md @@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static -- print "Compilation error with enum type:", $BodyType Unknown ``` +## Menghasilkan kode Yue multi-baris + +Saat macro mengembalikan kode Yue multi-baris, penggunaan string multi-baris di dalam tanda kutip tidak direkomendasikan. Sebaiknya gunakan `-> |`. + +String bertanda kutip mempertahankan teks apa adanya, sedangkan string multi-baris YAML menghapus indentasi awal yang sama. Ini biasanya membuat blok Yue yang dihasilkan lebih stabil, terutama ketika kode yang dihasilkan berisi komentar atau blok bertingkat. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + ## Validasi Argumen Anda dapat mendeklarasikan tipe node AST yang diharapkan dalam daftar argumen, dan memeriksa apakah argumen macro yang masuk memenuhi harapan pada waktu kompilasi. diff --git a/doc/yue-pt-br.md b/doc/yue-pt-br.md index a0e3268..7bf5ab6 100644 --- a/doc/yue-pt-br.md +++ b/doc/yue-pt-br.md @@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static -- print "Compilation error with enum type:", $BodyType Unknown ``` +## Gerando código Yue em múltiplas linhas + +Quando uma macro retorna código Yue em múltiplas linhas, não é recomendado usar uma string multilinha entre aspas. Prefira `-> |`. + +Uma string entre aspas preserva o texto literal, enquanto uma string multilinha estilo YAML remove a indentação inicial comum. Isso normalmente deixa os blocos Yue gerados mais estáveis, especialmente quando o código gerado contém comentários ou blocos aninhados. + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + ## Validação de argumentos Você pode declarar os tipos de nós AST esperados na lista de argumentos e verificar se os argumentos da macro recebidos atendem às expectativas em tempo de compilação. diff --git a/doc/yue-zh.md b/doc/yue-zh.md index cb44d22..b69fcf6 100644 --- a/doc/yue-zh.md +++ b/doc/yue-zh.md @@ -183,6 +183,33 @@ print "有效的枚举类型:", $BodyType Static -- print "编译报错的枚举类型:", $BodyType Unknown ``` +## 生成多行 Yue 代码 + +  当宏返回多行 Yue 代码时，不推荐使用带引号的多行字符串，建议优先使用 `-> |`。 + +  带引号的字符串会按字面保留文本；而 YAML 风格多行字符串会移除公共前导缩进。对宏生成的 Yue 代码来说，这通常能让代码块结构更稳定，尤其是在生成代码里包含注释或嵌套块时。 + +```yuescript +macro default_conf = (conf) -> " + -- useful; only set once +#{conf}.identity = 'LOVE' +#{conf}.version = \"11.5\" + " + +love.conf = (t) -> + $default_conf t +``` + +```yuescript +macro default_conf = (conf) -> | + -- useful; only set once + #{conf}.identity = 'LOVE' + #{conf}.version = "11.5" + +love.conf = (t) -> + $default_conf t +``` + ## 宏参数检查   可以直接在参数列表中声明期望的 AST 节点类型，并在编译时检查传入的宏参数是否符合预期。 diff --git a/spec/outputs/codes_from_doc_de.lua b/spec/outputs/codes_from_doc_de.lua index 28ed4e7..2530977 100644 --- a/spec/outputs/codes_from_doc_de.lua +++ b/spec/outputs/codes_from_doc_de.lua @@ -125,6 +125,18 @@ end print("yuescript") print(2) print("Gültiger Enum-Typ:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hallo") end @@ -164,6 +176,18 @@ end print("yuescript") print(2) print("Gültiger Enum-Typ:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hallo") end diff --git a/spec/outputs/codes_from_doc_en.lua b/spec/outputs/codes_from_doc_en.lua index 1fdc56d..18f0227 100644 --- a/spec/outputs/codes_from_doc_en.lua +++ b/spec/outputs/codes_from_doc_en.lua @@ -125,6 +125,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end @@ -164,6 +176,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end diff --git a/spec/outputs/codes_from_doc_id-id.lua b/spec/outputs/codes_from_doc_id-id.lua index 2201dee..452d88d 100644 --- a/spec/outputs/codes_from_doc_id-id.lua +++ b/spec/outputs/codes_from_doc_id-id.lua @@ -125,6 +125,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end @@ -164,6 +176,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end diff --git a/spec/outputs/codes_from_doc_pt-br.lua b/spec/outputs/codes_from_doc_pt-br.lua index b3bf0b3..f9784d7 100644 --- a/spec/outputs/codes_from_doc_pt-br.lua +++ b/spec/outputs/codes_from_doc_pt-br.lua @@ -125,6 +125,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end @@ -164,6 +176,18 @@ end print("yuescript") print(2) print("Valid enum type:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end diff --git a/spec/outputs/codes_from_doc_zh.lua b/spec/outputs/codes_from_doc_zh.lua index 5756793..4c254a2 100644 --- a/spec/outputs/codes_from_doc_zh.lua +++ b/spec/outputs/codes_from_doc_zh.lua @@ -125,6 +125,18 @@ end print("yuescript") print(2) print("有效的枚举类型:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end @@ -164,6 +176,18 @@ end print("yuescript") print(2) print("有效的枚举类型:", "Static") +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end +love.conf = function(t) + do + t.identity = 'LOVE' + t.version = "11.5" + end +end do print(123, "hello") end -- cgit v1.2.3-55-g6feb