hakorune/docs/reference/language/quick-reference.md

# Nyash Quick Reference (MVP)

Purpose
- One‑page practical summary for writing and implementing Nyash.
- Keep grammar minimal; clarify rules that often cause confusion.

Keywords (reserved)
- control: `if`, `else`, `loop`, `match`, `case`, `break`, `continue`, `return`
- decl: `static`, `box`, `local`, `using`, `as`
- lit: `true`, `false`, `null`, `void`

Expressions and Calls
- Function call: `f(a, b)`
- Method call: `obj.m(a, b)` — internally normalized to function form: `Class.m(me: obj, a, b)`
  - Default‑ON（P4）: Known 受信者かつ関数が一意に存在する場合に正規化（userbox 限定）。
  - それ以外（Unknown/core/user‑instance）は安全に BoxCall へフォールバック（挙動不変）。
  - 環境で無効化: `NYASH_REWRITE_KNOWN_DEFAULT=0`（開発時の切替用）。
  - バックエンド（VM/LLVM/Ny）は統一形状の呼び出しを受け取る。
- Member: `obj.field` or `obj.m`

Display & Conversion
- Human‑readable display: `str(x)`（推奨）/ `x.str()`
  - 既存の `toString()` は `str()` に正規化（Builder早期リライト）。
  - 互換: 既存の `stringify()` は当面エイリアス（内部で `str()` 相当へ誘導）。
- Debug表示（構造的・安定）: `repr(x)`（将来導入、devのみ）
- JSONシリアライズ: `toJson(x)`（文字列）/ `toJsonNode(x)`（構造）

Operators (precedence high→low)
- Unary: `! ~ -`
- Multiplicative: `* / %`
- Additive: `+ -`
- Compare: `== != < <= > >=`
- Logical: `&& ||` (short‑circuit, side‑effect aware)

Semicolons and ASI (Automatic Semicolon Insertion)
- Allowed to omit semicolon at:
  - End of line, before `}` or at EOF, when the statement is syntactically complete.
- Not allowed:
  - Line break immediately after a binary operator (e.g., `1 +\n2`)
  - Ambiguous continuations; parser must Fail‑Fast with a clear message.

Truthiness (boolean context)
- SSOT: `reference/language/types.md`（runtime truthiness）
- 実行上は `Bool/Integer/Float/String/Void` が中心。`BoxRef` は一部のコアBoxのみ許可され、その他は `TypeError`（Fail-Fast）。

Equality and Comparison
- SSOT: `reference/language/types.md`（`==`/`!=` と `< <= > >=` の runtime 仕様）
- `==` は一部の cross-kind（`Integer↔Bool`, `Integer↔Float`）を best-effort で扱う。その他は `false`。
- `< <= > >=` は `Integer/Float/String` の **同型同士**のみ（異型は `TypeError`）。

String and Numeric `+`
- SSOT: `reference/language/types.md`（runtime `+` 仕様）
- `Integer+Integer`, `Float+Float` は加算。片側が `String` なら文字列連結（相手は文字列化）。
- それ以外（例: `Integer+Bool`, `Integer+Float`）は `TypeError`（Fail-Fast）。

Blocks and Control
- `if (cond) { ... } [else { ... }]`
- `loop (cond) { ... }` — minimal loop form
- `match (expr) { case ... }` — MVP (literals and simple type patterns)

Using / SSOT
- Dev/CI: file‑based `using` allowed for convenience.
- Prod: `nyash.toml` only. Duplicate imports or alias rebinding is an error.

Errors (format)
- Always: `Error at line X, column Y: <message>`
- For tokenizer errors, add the reason and show one nearby line if possible.

Dev/Prod toggles (indicative)
- `NYASH_DEV=1` — developer defaults (diagnostics, tracing; behavior unchanged)
- `NYASH_ENABLE_USING=1` — enable using resolver
- `NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN=1` — allow `main` as top‑level entry

Notes
- Keep the language small. Prefer explicit conversions (`int(x)`, `str(x)`, `bool(x)`) in standard helpers over implicit coercions.
- Builder rewrites method calls to keep runtime dispatch simple and consistent across backends.