Проектные решения
Правила Топаза 6.0 выросли из отдельных решений. Для каждого решения здесь записано, какую проблему оно решало, какое поведение выбрано и какие варианты рассмотрели и отклонили. Для каждого примера решения указан ожидаемый результат.
Лексика и литералы
- Формат конца строки сохраняет границы операторов
LF, CRLF и одиночный CR означают один перевод строки в исходнике.
- Бывшее начало блочного комментария подчиняется правилам операторов
Анализатор читает
/как* /и*. - Комментарии пишутся по одной строке
Комментарий начинается с
/и заканчивается в конце строки./ - Перевод строки разделяет операторы, а значение отбрасывается явно
Разделяйте операторы переводом строки.
- Идентификаторы записываются в NFC
Записывайте идентификаторы в NFC по Unicode 16.
- Префиксы и шестнадцатеричные цифры пишутся строчными
Для двоичных чисел пишите
0b, для шестнадцатеричных0x. - Длительности выводятся в миллисекундах и сообщают о переполнении
У
Durationесть сложение, вычитание, умножение на целое в любом порядке, сравнение, вывод иto.Millis() - У всех тегов шаблонов одинаковое экранирование
Во всех тегах шаблонов используется одно правило экранирования.
- Формат конца строки в исходнике сохраняет значение литерала
Реальные LF, CRLF и одиночный CR внутри строкового литерала читаются как один перевод строки.
- Path.from создаёт путь из строки
Тег
pудалён. - Строка исходника из одних пробелов становится пустой строкой
Удаляйте пробелы и табуляцию в строках исходника, где есть только эти символы.
- Интерполяция строк и производный
Showзаписывают конечные числа без экспонентыПри интерполяции строк и в производном
Showдля конечного ненулевого числа выбирается десятичная запись с наименьшим числом значащих цифр, которая округляется в то же значение binary64. - Path.from служит единственным конструктором пути
Создавайте путь из текста через
Path..from
Связывания и типы
- У привязки не более одной аннотации типа
Объявление отклоняется, если для одной привязки одновременно указаны аннотация привязки и аннотация шаблона.
- Привязка не может занять имя видимого конструктора
Вариант без данных пишется как
Choice..Empty() - Диагностика изменения указывает на конкретную причину
При изменении неизменяемой исходной привязки проверка выдаёт TPZ5003 и указывает на её использование.
- Для изменения через необязательный доступ нужна изменяемая исходная привязка
Поля, индексы, скобки и
?.прослеживаются до исходной привязки. - Имя локальной функции указывает на одно объявление во всём блоке
Объявление
functionскрывает одноимённое внешнее значение во всём блоке. - Диагностика раннего чтения зависит от границы вычисления
Чтение до инициализации в немедленно вычисляемом выражении, например в условии или аргументе
match, даёт TPZ3018 при разрешении имён. - Выражение в шаблоне вычисляется, когда до него доходит сопоставление
Выражение, дающее проверяемое значение, наследует порядок вычисления окружающего кода.
- Имя указывает на одно и то же объявление при проверке и выполнении
У каждого места, где используется имя, есть одна цель для его роли, и проверка с выполнением используют одну и ту же цель.
- Скобки вокруг вызываемого значения сохраняют допустимость в константе
Допустимость вызова в инициализаторе
constне меняется из-за скобок вокруг вызываемого значения. - Присваивание и передача коллекций дают независимые значения
Массивы, отображения и множества ведут себя как значения.
- Отложенный вызов изменяющего метода записывается лямбдой
Попытка отделить изменяющий метод, например
let add = xs., отклоняется при проверке.push - Результат изменения временного значения нужно использовать
Проверка отклоняет изменяющий вызов без исходной привязки, если результат отбрасывается.
- Условие без else всегда возвращает единичное значение
Выражение
ifбезelseвозвращает()даже в позиции значения. - Значение по умолчанию для отображения задаётся через get и оператор подстановки
Пишите
m..get(k) ?? fallback
Выражения, образцы и поток управления
- Положительные значения пишутся без унарного плюса
Унарный
+удалён. - In проверяет принадлежность массиву, множеству и диапазону
Используйте
inдля проверки элемента массива, множества или диапазона. - Если получателя нет, аргументы необязательного вызова пропускаются
Получатель вычисляется один раз.
- Поток данных выражается обычными вызовами и привязками
Операторы
|>и>>, а также_в позиции выражения удаляются. - Управляющие выражения заключаются в скобки
Заключайте управляющие выражения и условия в скобки, как в
if (test),match (value)иwhile (test). - Операнды вычисляются слева направо
Операнды двоичных и вложенных выражений вычисляются слева направо.
- Запись использует значение привязки после вычисления правой части
Индексное присваивание и изменяющий метод записывают в текущее значение привязки после вычисления правой части или аргументов.
- Числовые шаблоны принимают отрицательные литералы
Перед числовым литералом в шаблоне допустим один
-. - Шаблон записи явно указывает поле и его подшаблон
Каждое поле шаблона записывается как
field: pattern. - Пропущенное двоеточие в шаблоне записи является ошибкой разбора
TPZ5611 зарезервирован для защитной проверки.
- Для возврата из функции ветвь сопоставления использует блок
Помещайте
returnв блок внутри ветви сопоставления. - Сопоставление выбирает первую подходящую ветвь и отклоняет перекрытые
matchпробует ветви в порядке записи и выбирает первую, где подошли и шаблон, и условие. - Диапазон с двумя литеральными концами, которому не соответствует ни одно значение, отклоняется при проверке
Если обе границы заданы целыми литералами, сначала выполняется обычная проверка литералов.
- Вычисляемые границы выполняются при каждой проверке диапазона
Дойдя до диапазона, сопоставление вычисляет нижнюю границу, затем верхнюю.
- Хвост списка получает явный подшаблон
После
.всегда пишется шаблон.. - Даже конструкторы без аргументов пишутся со скобками
В значениях и шаблонах пишите скобки у конструкторов, как в
None(),Empty()иSome(x). - Выражение match охватывает все возможные значения
Проверка требует, чтобы каждое выражение
matchохватывало все возможные значения. - For выполняет действия, а генератор собирает значения
Цикл
forвыполняет действия и возвращает()в любом контексте. - Диагностика defer предлагает записать блок
При разборе TPZ2004 сообщает, что
deferтребует блока, и указывает на начало выражения тела. - Отложенный код помещается в блок defer
После
deferукажите блок. - Управление не может перейти через границу defer
Если
return,break,continueили?пересекает границуdefer, проверка сообщает TPZ5001 на самом выражении, даже в недостижимом коде. - Возврат значения ошибки тоже выполняет зарегистрированную очистку
При возврате
Errчерез?блокиdeferвыполняются в обратном порядке регистрации для покидаемых областей. - Невосстановимая ошибка выполнения пропускает оставшуюся очистку
Обычная ошибка выполнения завершает исполнение без возможности продолжения.
Функции и обобщения
- Даже один параметр лямбды заключён в скобки
Заключайте в скобки список параметров любой лямбды.
- У параметра переменной длины нет значения по умолчанию
Объявление значения по умолчанию для параметра переменной длины отклоняется.
- Возможности параметра типа задаются ограничением протокола
У параметра типа или непрозрачной проекции без статического контракта нельзя читать поле или вызвать метод через точку.
- Вызовы используют позиционные аргументы, а именованные параметры передаются записью
Передавайте аргументы по позиции.
- Явные аргументы типа следуют за именем или доступом к члену
Явные аргументы типа пишутся после имени или доступа к члену.
- Пробел перед скобками вызова не меняет разбор аргументов типа
После имени или члена читаются аргументы типа, если между
<и>находится синтаксическая форма списка типов, а следующий токен это(. - Аргумент вызова через объединение имеет один тип для всех ветвей
Сначала по независимым аргументам подставляются параметры сигнатур каждой ветви.
- Имя параметра встречается в списке один раз
Повтор имени в одном списке параметров функции или лямбды отклоняется.
Структуры
- Режимы десятичного округления образуют обычное перечисление
Roundingявляется обычным перечислением из шести вариантов.Mode - Данные варианта могут иметь тип объединения с перечислением
Объединение с перечислением допустимо в качестве типа данных варианта.
- Варианты перечислений могут использовать имена стандартных конструкторов
В вариантах перечислений допустимы
None,Some,OkиErr. - При структурном обновлении каждое поле записывается один раз
Повтор имени поля в одном структурном обновлении отклоняется.
- Конструктору нужен список аргументов и в позиции значения
В позиции значения пишите
Name(arguments). - Self обозначает тип, реализующий протокол
Собственных параметров типа у объявления протокола нет.
- Сигнатуры протокола следуют правилам обычных функций
Действуют обычные правила обобщённых, переменных и необязательных параметров.
- Реализации протокола используют значения по умолчанию и видимость из контракта
Методы реализации могут быть обобщёнными, принимать переменные аргументы и опускать аннотацию результата.
- Видимость импортированной реализации не зависит от способа объявления
У явных и выведенных реализаций одинаковая видимость при импорте.
- Ручная реализация JSON использует encode и decode
При ручной реализации объявляются обычные методы
encodeиdecode. - Using закрывает ресурс при обычном и структурированном досрочном выходе
Очистка
usingвыполняется при обычном и структурированном досрочном выходе. - Выведенная реализация вызывает реализацию вложенного типа
Вызывается явная или выведенная реализация внутреннего типа.
- Для newtype реализации выводятся явно
Указывайте протоколы в
derivesуnewtypeтак же, как у записей и перечислений. - Равенство, порядок и JSON имеют разные требования к типам
Равенство Map и Set определяется составом элементов.
- Протоколы следуют общим правилам имён модулей
К протоколам применяются обычные правила экспорта, импорта и разрешения имён.
- Ограничения обобщённой реализации пишутся в начальном списке параметров
Помещайте ограничения в начальный список параметров, как в
impl<T: Eq> Eq<Box<T>>. - Обобщённые реализации протоколов используют синтаксис ограничений функций
Реализация протокола может объявлять явные параметры типа и ограничения, быть условной или выводиться при выполнении условий.
- Коллекции получают ожидаемые типы из контекста
Ожидаемые типы одинаково передаются массивам, множествам, отображениям и генераторам.
- Обратные вызовы объединяют преобразования, а генераторы строят коллекции
Сохраняются методы вроде
arr.для цепочек преобразований и генераторы для сборки коллекции из источников с фильтрами.map(f) - Массивы, множества и диапазоны используют общие методы обратного вызова
Массивы, множества и диапазоны предоставляют немедленные
map,filterиreduce. - Отображения и множества сохраняют порядок вставки
Ключи, значения, пары, обход и представление отображения следуют порядку вставки.
Ошибки, конкурентность и модули
- Для невыводимого типа ошибки Result требуется аннотация
Если тип ошибки вывести невозможно, проверка выдаёт TPZ5022 и требует аннотацию типа.
- Обратный вызов возвращает собственную переданную ошибку
При распространении значения через
?лямбда или обратный вызов возвращаетResultлибоOptionиз собственного вызова. - Пустая параллельная группа возвращает пустую запись
Группа
concurrentбез ветвей возвращает пустую запись. - Ограничение времени вычисляет выражение Duration один раз
Допускается обычное выражение
Duration. - При одновременном завершении и истечении срока побеждает срок
Если завершение совпадает с истечением ограничения, срабатывает тайм-аут.
- Ветвь параллельного выполнения не передаёт управление наружу
Возврат, переход цикла и распространение ошибки отклоняются статически, если цель находится вне ветви.
- Группа с тайм-аутом завершится даже при бесконечной ветви
По истечении тайм-аута группа
concurrentпереходит к запасному результату. - Ветвь, прерванная по тайм-ауту, пропускает пользовательскую очистку
Прерванная ветвь
concurrentпропускает оставшиеся действияdeferиusing. - Входные файлы и импортируемые модули используют одинаковые операторы
Для верхнего уровня входных и импортируемых файлов действуют одинаковые правила.
- Пользовательский код не может обращаться по имени к объявлениям, созданным компилятором
Пользовательский код не может обращаться по имени к объявлению, созданному компилятором.
- Export let связывает имена обычным шаблоном
В
export letиспользуется обычный шаблон неизменяемогоlet. - Публичные объявления проверяются после разрешения типов
Проверяются разрешённые типы публичных объявлений.
- Значения по умолчанию в записях соблюдают видимость экспорта
Для ссылок в значениях по умолчанию действуют обычные правила видимости модулей.
- As задаёт новое имя при импорте
Пишите
asтолько при переименовании. - Импортированные значения имеют неизменяемые привязки
Импортированная привязка неизменяема.
Стандартная библиотека
- Чтение, закрытие и запись хоста имеют разные ошибки выполнения
При выполнении ввод даёт TPZ4008, закрытие TPZ4009, а вывод TPZ4010.
- WriteLine возвращает единичное значение, а сбой записи даёт ошибку выполнения
std.сохраняет единичный результат.io. write Line - Ошибка вывода хоста указывает на неудачный вызов записи
Для сбоя записи в
writeиспользуется отдельная ошибка выполнения с позицией этого вызова.Line - Длина, ключи и значения коллекций читаются как свойства
Для
length,keysиvaluesиспользуются свойства. - Длина пустой коллекции равна нулю
Проверяйте пустоту через
length == 0. - Выход среза байтов за границы вызывает ошибку выполнения
Срез не включает конец и требует
0 <= start <= end <= length. - Шестнадцатеричные байты записываются парами строчных цифр
Каждый байт читается как две строчные шестнадцатеричные цифры.
- Распаковка читает один поток целиком
Целиком читается один поток, кадр или элемент согласно формату.
- Для распаковки можно задать предел размера
Функция распаковки принимает необязательный
maxи возвращаетBytes Errпри превышении этого числа байтов. - Операции с путями работают с нормализованными компонентами
Используются нормализованные компоненты пути.
- Имена экранирования в регулярных выражениях используют ASCII
После обратной косой черты для имён зарезервированы только буквы и цифры ASCII.
- Именованные группы регулярных выражений имеют одну форму записи
Применяется синтаксис Unicode 16.0 с простым приведением регистра.
- Слишком большие регулярные выражения отклоняются при компиляции
При компиляции пределы составляют 65536 инструкций,
2^22для произведения размера программы на число ячеек групп и 128 для вложенности. - Повтор регулярного выражения не добавляет ещё одну пустую итерацию
Пустая итерация без продвижения не добавляется.
- Поиск, разбиение и замена используют одну последовательность совпадений
Совпадения выбираются слева направо по первому подходящему варианту без перекрытий.
- Позиции совпадения задаются байтами UTF-8
Match.иstart Match.являются смещениями в байтах UTF-8.end - Подстановки регулярных выражений используют фигурные скобки для групп
Нулевая группа содержит совпадение целиком.
- Операции с URL следуют правилам WHATWG
Абсолютные URL разбираются и сериализуются по WHATWG без базового адреса.
- Доменные имена на разных языках обрабатываются по Unicode 16.0.0
Обработка по UTS 46 использует таблицы Unicode 16.0.0.
- Календарные даты лежат между первым и 9999 годом
Действует продолженный григорианский календарь от
0001-до01- 01 9999-.12- 31 - Для больших целых задаётся основание и используются строчные цифры
Используйте основание от 2 до 36 и строчные цифры ASCII.
- При десятичном умножении проверяется масштаб нормализованного результата
Используются целый коэффициент произвольной точности и нормализованный масштаб от 0 до 4294967295.
- При разборе десятичного числа проверяется весь ввод ASCII
Разбирается полная десятичная запись ASCII.
- Десятичное округление задаёт направление и правило для середины
Доступны шесть режимов.
- Десятичное деление округляет точное частное один раз
Точное частное один раз округляется до запрошенного масштаба.
- Преобразование десятичного числа в целое успешно только при точном результате
int.преобразует точно.to Decimal - Десятичные числа сравниваются по точному значению
Равенство и порядок определяются точным числовым значением.
- Файловые функции сохраняют байты и сортируют содержимое каталога
Байтовые операции сохраняют исходные байты.
- Ввод для явно объявленной main потребляется один раз
Для
main(args, stdin)стандартный ввод считывается до конца и передаётся какstdin. - Поток открывает существующий файл и сохраняет общую позицию
Существующий обычный файл открывается для чтения и записи без создания и усечения.
- JSON null проверяется через kind
Используйте
value..kind() == "null" - Числа JSON сохраняют исходную запись
Исходная запись числа JSON сохраняется в точности.
- Разбор JSON охватывает весь документ и отклоняет повторные ключи
Разбирается один документ целиком.
- Запись JSON сортирует ключи объектов
К протоколу JSON обращаются один раз.
- Чтение CSV по именам отклоняет повторяющиеся заголовки
Чтение CSV по именам возвращает ошибку при повторении заголовка.
- Запись CSV с заданным заголовком отклоняет повторяющиеся столбцы
stringifyвозвращаетWith Header Result<string, string>и отклоняет повторяющиеся имена запрошенных столбцов. - TOML принимает дополнительную секунду и ограничивает вложенность 128 уровнями
Значение секунд 60 принимается по RFC 3339.
- TOML следует версии 1.0 и сообщает об ошибках преобразования в JSON
Чтение поддерживает формы TOML 1.0.
- Тестовые циклы используют обычный for
Вместо удалённых
forиAll Int forиспользуетсяAll Bool for. - Поиск в парсере использует позиции скалярных значений Юникода
Предикаты ASCII дают результат для любого целого числа.
- Перевод в масштабированные пункты выполняет toScaledPoints
Вместо
scaledиспользуйтеPoints to.Scaled Points - Публичные расстояния вёрстки задаются Length в пунктах
Публичные расстояния в
std.задаются черезtypeset Length<Pt>. - Класс китайских, японских и корейских кластеров называется CjkCluster
Koreanпереименовывается вCluster Cjkв соответствии с областью классификации.Cluster - Для пустой последней строки применяется порог 52 процента
Правило для ширины меньше 52 процентов действует и при нуле символов.
- Функция стоимости строки называется lineBadness
lineпереименовывается вBadness Mpt line.Badness - Предел межбуквенного интервала задаётся относительно шрифта
maxпринимаетLetter Spacing Em Length<Em>. - При одинаковых условиях вёрстка выбирает те же разрывы
При одинаковом порядке входа, политике, сетке и версии совпадают разрывы, их виды, ширина, стоимость и варианты ошибок.
- Классификация разрывов отделена от выбора строк абзаца
classifyсравнивает сохранённые деления пункта.Breaks - Пустой вход вёрстки успешно даёт пустой результат
При остальных допустимых условиях пустой массив кластеров или абзац успешно даёт пустой результат.
- Непустому абзацу нужна допустимая граница в конце формирования
Для непустого входа последний разрыв должен быть разрешён всеми наборами правил.
- Планирование абзаца задаёт область поиска и возвращает два результата
FixedPoint начинает с 80 предыдущих кандидатов и расширяет поиск.
- Вёрстка отклоняет отрицательные размеры и допускает отрицательный трекинг
Отрицательные физические размеры, ширина штрафа и отступ буквицы отклоняются.
- Ширина выбранного штрафа входит в ширину строки
Ширина выбранного штрафа учитывается для всех видов в обоих способах оценки и в естественной ширине для выключки.
- Минимум последней строки применяется только к последней строке FixedPoint
minприменяется только при расчёте последней строки FixedPoint.Final Line Width Ratio M - Артефакты потребителя проверяются через inspectConsumerArtifact
Остаётся
inspect.Consumer Artifact - Вычисление Lispex отделено от допуска и проверки доказательств
Интерфейс 6.0 различает каноническое вычисление, допуск, прерывание хостом и работу с дополнительными доказательствами.
- Идентифицированный запрос Lispex является неизменяемым снимком
Канонический обмен байтами и создание Datum на стороне хоста сохраняют точные значения в явных пределах преобразования.
- Пакет Lispex становится доступен после проверки допуска
До возврата пригодного дескриптора пакета проверяются все переданные компоненты и условия ресурсов.
- Переданный код Lispex повторно проходит допуск
Подготовка в собственном конечном бюджете даёт проверенное неизменяемое правило.
- Lispex отличает завершённое вычисление от ошибки попытки
Завершённое вычисление возвращает канонический итог.
- Lispex различает идентификаторы запроса, источника и выполнения
Смысловой запрос, происхождение исходника, байты движка и работа хоста имеют отдельные типизированные идентификаторы.
- Повтор Lispex сверяет новый итог с записанным
freshпроверяет сохранённый запрос до выполнения и успешно завершается, если новый итог совпал с записанным.Replay - Результат вычисления Lispex сохраняется при последующей проверке
Канонический результат сохраняется.
- У этапов Lispex отдельные конечные ограничения ресурсов
У подготовки, вычисления и работы хоста отдельные полные записи конечных ограничений.
- Фабрики Lispex создают обычные неизменяемые правила
Фабрика использует проверенные записи файла блокировки и явные пределы подготовки, создавая стандартное неизменяемое правило.
- Строку можно разделить на графемные кластеры
string.возвращает массив сегментов по границам графем в Unicode 16.graphemes() - Встроенные методы строк и массивов сохраняют сигнатуры
Сигнатуры 5.21 сохраняются для методов, которые не были отдельно удалены или переименованы.
- Преобразование строки в целое принимает цифры ASCII и необязательный минус
string.принимает десятичные цифры ASCII с необязательным знакомto Int() -в начале.
Инструменты
- Ошибка отложенной работы приводит к сбою всей команды
Ошибка выполнения или хоста в отложенной работе завершает всю команду неудачей.
- Проверки в тестах вычисляют аргументы один раз и точно сравнивают эталон
Аргументы вычисляются один раз слева направо.
- Очистка хранилища сохраняет рабочие области, которые могут использоваться
Область сохраняется независимо от возраста, если владелец активен или его состояние неизвестно.
- Параметры команд без эффекта удаляются
Параметры без эффекта, включая
-, удаляются.- types - Версия выводится командой topaz version
Запускайте
topaz versionдля вывода версии. - Значение параметра передаётся отдельным аргументом
Значение передаётся следующим аргументом.
- Параметр команды указывается не более одного раза
Повтор параметра отклоняется даже при совпадающих значениях.
- Команды выбирают вывод JSON одним параметром
Для команд с выводом JSON используйте
-.- format json - В диагностике JSON стабильны код и смысл основной позиции
Контракт
-задаёт структурированную идентичность, обязательные поля и типы, единицы координат, серьёзность и причину, указанную основной позицией.- format json - Topaz help открывает справку по командам
Запрашивайте справку через
topaz help. - Vendor помещает исходники зависимостей в проект
Используйте
vendor. - Зависимости объявляются таблицами
Объявляйте зависимости таблицами.
Диагностика
- Код TPZ0002 выведен из употребления и зарезервирован
В 6.0.0 TPZ0002 выведен из употребления.
- Глубина вызовов считает активные пользовательские вызовы
Для TPZ5009 учитываются именованные функции, лямбды, пользовательские обратные вызовы, методы протокола и получателя.
Решения, у которых ещё нет правила
- Проверка типов откладывает только выводы, зависящие от неизвестных фактов
При проверке о каждом нарушенном обязательстве сообщается один раз.
- Полиморфизм обобщённых функций сохраняется в привязках
Подходящая привязка без аннотации сохраняет обобщённую сигнатуру.
- Ошибки конструкторов и расчёта стоимости стандартной библиотеки указывают на публичный вызов
Основная позиция ошибки конструктора или расчёта стоимости указывает на публичный вызов.