Legacy Syntax Migration

This is the single migration guide for legacy Topaz source code written prior to v5. It is not a step-by-step release upgrade path. Compatible product changes do not require a separate migration process. Record the intended observable behavior first, preserve that behavior while rewriting legacy source code into current canonical grammar, and let the current checker surface all unresolved boundaries.

1. Inventory before rewriting

Record entry files, module roots, inputs, expected outputs, runtime faults, host side effects, and verified output captures. Separate actual Topaz code from examples styled after Rust, JavaScript, or external frameworks. Do not infer behavior from legacy documentation simply because a syntax pattern looks familiar. Refer to the current manual and canonical examples instead.

2. Normalize the recurring forms

Rewrite mut let to let mut, [T] to Array<T>, and legacy function-type syntax to (T) -> U.
Use ..rest in list patterns, ...args: T for variadic parameters, lambdas for anonymous functions, and self only where current method declarations permit.
Replace string indexing and .length with scalar APIs. Use typed registry templates and {expr} string interpolation.
Express recoverable failures in Result, missing values in Option or nullable types, runtime faults explicitly, and cleanup logic in defer or supported using statements.
Update module syntax to the current import and export forms described in Modules & Visibility. Keep foreign tokens restricted to labeled build or conversion boundaries.

3. Keep historical code historical

This is legacy syntax and must remain inside a text code fence, not a canonical Topaz fence:

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

The current syntax makes mutability, collection types, 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 Option<string>, displaying a successful lookup as Some(Ada) instead of relying on unchecked string indexing.

4. Check behavior, not just syntax

BASH

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

Once the checker succeeds, compare runtime output with the results recorded prior to rewriting. Reverify module initialization, iteration order, scalar string offsets, numeric faults, resource cleanup, and host-profile boundaries.

Build only the target environments designated for deployment. Compare declared outputs exclusively on targets supporting the rewritten source code. If a target does not support a specific syntax form, it must fail with a clear diagnostic message rather than generating incorrect or incomplete build artifacts.

5. Know the automation boundary

topaz migrate --from <version> --to <version> handles only explicitly supported adjacent v5 transitions. Across those declared boundaries, the tool checks compatible source code or updates package metadata. It does not translate pre-v5 source code or infer legacy syntax semantics. Comprehensive migration guides may also include framework APIs or foreign grammar that automated tools cannot validate. Refer to Classic solely for historical context, and manually adapt code to current language standards.

Migration exit gate