Миграция старого синтаксиса

Это единственное руководство по миграции исходного кода Топаза, написанного до v5. Оно не определяет последовательность обновлений между релизами. Обратно совместимые изменения продукта не требуют отдельной процедуры миграции. Сначала зафиксируйте целевое поведение, затем перепишите программу согласно текущей грамматике с сохранением этого поведения и позвольте инструменту проверки явно показать оставшиеся несовместимости.

1. Инвентаризация до переписывания

Зафиксируйте входные файлы, корни модулей, входные данные, ожидаемый вывод, ошибки, побочные эффекты и эталонные образцы вывода. Отделите код Топаза от примеров на Rust, JavaScript или кода фреймворка. Не восстанавливайте поведение, опираясь лишь на похожие записи со старой страницы. Используйте текущее руководство и канонические примеры.

2. Нормализация повторяющихся форм

mut let → let mut, [T] → Array<T>, устаревший синтаксис типа функции → (T) -> U.
Остаток шаблона списка — ..rest, вариативный параметр — ...args: T, анонимная функция — лямбда, а self используется только там, где это допускает текущее объявление метода.
Индексация строк и .length заменяются скалярными API. Шаблоны используют зарегистрированные теги и {expr}.
Обрабатываемая ошибка представляется через Result, отсутствие значения — через Option или допускающий null тип, ошибка выполнения остаётся явной, а очистка ресурсов выполняется через defer или разрешённый using.
Модули переписываются в текущие формы import и export, как описано в разделе Модули и видимость. Синтаксис других языков остаётся на явно отмеченной границе сборки или конвертации.

3. Исторический код остаётся историческим

Устаревший синтаксис помещается в блок text, а не в канонический блок Топаза:

mut let имена: [string] = ["Ada"]
let первое = имена[0]

Текущая форма явно показывает изменяемость, тип коллекции и безопасную проверку границ:

TOPAZ

let mut имена: Array<string> = ["Ada"]
let первое: Option<string> = имена.get(0)
print("{первое}")

Вывод

Some(Ada)

имена.get(0) возвращает Option<string>, поэтому результат успешного поиска представлен как Some(Ada), а не зависит от индексации строки без проверки.

4. Проверка поведения, а не только синтаксиса

BASH

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

После успешной проверки сравните вывод с результатом, зафиксированным до переписывания. Повторно проверьте инициализацию модулей, порядок обхода, скалярные позиции строк, числовые ошибки, очистку ресурсов и границы профиля среды.

Собирайте только те цели, которые планируете поставлять. Сравнивайте объявленные результаты лишь для целей, поддерживающих переписанный исходный код. Неподдерживаемая форма должна завершиться понятной диагностикой, не создавая артефакт с изменённым или неполным поведением.

5. Граница автоматизации

topaz migrate --from <version> --to <version> распознаёт только явно поддерживаемые соседние переходы внутри v5. На этих объявленных границах команда может проверить совместимый исходный код или обновить поддерживаемые метаданные пакета. Она не конвертирует синтаксис до v5 и не интерпретирует логику старой программы. Подробные руководства также могут содержать API фреймворков и синтаксис других языков, которые нельзя проверить автоматической заменой. Используйте Классику только как исторический контекст, а программу адаптируйте к текущей версии языка.

Условие завершения