hakorune/docs/reference/language/using.md

using — Imports and Namespaces (Phase 15)

Status: Accepted (Runner‑side resolution). Selfhost parser accepts using as no‑op and attaches meta.usings for future use.

Policy

• Accept using lines at the top of the file to declare module namespaces or file imports.
• Resolution is performed by the Rust Runner when NYASH_ENABLE_USING=1.
  • Runner strips using lines from the source before parsing/execution.
  • Registers modules into an internal registry for path/namespace hints.
• Selfhost compiler (Ny→JSON v0) collects using lines and emits meta.usings when present. The bridge currently ignores this meta field.

Syntax

• Namespace: using core.std or using core.std as Std
• File path: using "apps/examples/string_p0.nyash" as Strings
• Relative path is allowed; absolute paths are discouraged.

Style

• Place all using lines at the top of the file, before any code.
• One using per line; avoid trailing semicolons. Newline separation is preferred.
• Order: sort alphabetically by target. Group namespaces before file paths.
• Prefer an explicit alias (as ...) when the target is long. Suggested alias style is PascalCase (e.g., Std, Json, UI).

Examples

using core.std as Std
using "apps/examples/string_p0.nyash" as Strings

static box Main {
  main(args) {
    local console = new ConsoleBox()
    console.println("hello")
    return 0
  }
}

Runner Configuration

• Enable using pre‑processing: NYASH_ENABLE_USING=1
• Selfhost pipeline keeps child stdout quiet and extracts JSON only: NYASH_JSON_ONLY=1 (set by Runner automatically for child)
• Selfhost emits meta.usings automatically when present; no additional flags required.

Notes

• Phase 15 keeps resolution in the Runner to minimize parser complexity. Future phases may leverage meta.usings for compiler decisions.
• Unknown fields in the top‑level JSON (like meta) are ignored by the current bridge.