Move Topaz source written before v5 to the current syntax by editing it directly. Preserve the original behavior and compare the results after each change.
Install Topaz and keep a copy of the original source, inputs, and outputs. Compatible product updates need no separate source migration.
Rewrite one file
This historical example uses old declaration and array-type syntax.
mut let names: [string] = ["Ada"]
let first = names[0]Save the current form below as from-pre-v5.tpz in a working folder.
let mut names: Array<string> = ["Ada"]
let first: Option<string> = names.get(0)
print("{first}")Run these commands from that folder.
topaz check from-pre-v5.tpz
topaz run from-pre-v5.tpzThe check exits with code 0. The run exits with code 0 and prints this result.
Some(Ada)names.get(0) returns an Option<string>. The first element exists, so the result is Some(Ada). An index outside the array returns None. Direct array indexing remains supported and raises a runtime fault for an out-of-range index. Choose the behavior your program needs.
When documenting old code, use a text block. Use a topaz block for current syntax.
Record behavior before editing a project
Record the entry files, module roots, inputs, expected outputs, runtime faults, and file or network effects. Keep captured results for comparison. Identify examples written in Rust, JavaScript, or framework syntax separately from Topaz source.
Adapt source and package metadata to the current language mode. Use Packages & Distribution for package settings. Consult Classic for historical syntax and the current manual for the form to write now.
Replace recurring forms
| Old form | Current form | What to preserve |
|---|---|---|
mut let x | let mut x | Whether the binding can be reassigned |
[T] | Array<T> | Element type |
function(T) -> U | (T) -> U | Parameter and return types |
[head, ...tail] | [head, ..tail] | Remaining elements in a list pattern |
args: ...T | ...args: T | Variadic argument type |
Anonymous function | (x: T) => expr | Parameters, result, and captured bindings |
s[i], s.length | s.scalars() and explicit string APIs | Unicode scalar positions and counts |
Backticks, ${expr} | Double quotes, {expr} | String contents and interpolation |
A Unicode scalar is one Unicode value, which can differ from a byte or a visible character. See Strings & Templates for indexing and registered template tags. Use self where the current method declaration permits it.
Use Result for recoverable failures and Option or a nullable type for missing values. Keep runtime faults distinct from returned errors. Move cleanup to defer or supported using statements. Update import, export, visibility, and initialization according to Modules & Visibility.
Keep foreign-language code in explicitly labeled build or conversion steps. It cannot be pasted into a Topaz module as Topaz syntax.
Compare the rewritten program
Run topaz check on the rewritten source, then run the project's tests. For the file above, compare the output with Some(Ada). For a project, compare the recorded inputs and results.
Check module initialization, iteration order, Unicode scalar positions, numeric faults, cleanup, and permitted host operations. If a diagnostic appears, fix its source location using the linked current syntax. If output differs after the check passes, inspect the changed logic with the same input.
Build for the native, Web, or Worker environments you deploy to, following Artifacts & Deployment. Unsupported forms must produce a diagnostic before product output. Finish when checks and tests pass and each selected build produces the expected behavior.