Legacy Syntax Migration

This is the sole migration guide for genuinely old Topaz source from before v5. It is not a release-by-release upgrade path: compatible product changes do not need a separate migration process. Preserve intended behavior while rewriting old source into the current canonical grammar, then let the current checker expose every unresolved boundary.

1. Inventory before rewriting

Record entry files, module roots, inputs, expected outputs, faults, host effects, and known-good output captures. Separate actual Topaz from Rust-, JavaScript-, or framework-shaped examples. Do not infer behavior from an old page merely because a form looks familiar; consult the current manual and canonical examples.

2. Normalize the recurring forms

Rewrite mut let as let mut, [T] as Array<T>, and old function-type spellings as (T) -> U.
Use ..rest in list patterns, ...args: T for variadic parameters, lambdas for anonymous functions, and self only where current method declarations allow it.
Replace string indexing/.length with scalar APIs; use typed registry templates and {expr} interpolation.
Keep recoverable failure in Result, absence in Option/nullable shapes, runtime faults loud, and cleanup in defer or the supported using form.
Rewrite modules to the current import and export forms. Foreign tokens remain at a labeled build or conversion boundary.

3. Keep historical code historical

This is a legacy spelling and must stay in a text fence, never a canonical Topaz fence:

mut let names: [string] = ["Ada"]
let first = names[0]

The current shape makes mutation, collection type, and bounds behavior explicit:

TOPAZ

let mut names: Array<string> = ["Ada"]
let first: Option<string> = names.get(0)
print("{first}")

Output

Some(Ada)

names.get(0) returns an Option<string>, so the successful lookup is visible as Some(Ada) rather than relying on unchecked string indexing.

4. Check behavior, not just syntax

BASH

topaz check from-pre-v5.tpz
topaz run from-pre-v5.tpz

After the checker passes, compare the output with the result recorded before the rewrite. Recheck module initialization, iteration order, scalar string positions, numeric faults, resource cleanup, and host-profile boundaries.

Build only the targets you intend to ship. Compare declared outputs only for targets that support the rewritten source. A target that does not support a form must decline with a clear diagnostic instead of producing a different or partial product.

5. Know the automation boundary

topaz migrate --from <version> --to <version> recognizes only explicitly adopted adjacent v5 transitions. At those declared boundaries it can check compatible source or update supported package metadata. It does not translate source from before v5 or infer the meaning of old syntax. Long-form guides may also contain framework APIs and foreign grammar that no automatic rewrite can validate. Use Classic only as historical context, then adapt the program with the current language.

Migration exit gate