Для текста, который программа выводит или сравнивает, используйте обычную строку. Зарегистрированный тег требуется, когда значение должно сохранять структуру пути, регулярного выражения, команды оболочки или SQL. Значение шаблона передаёт структурированное намерение тега вместе с содержимым.
Начните с наблюдаемого текста Unicode
Сохраните код в strings-templates.tpz:
let название = "Topaz 💎"
let числоСкалярных = название.scalars().length
let путьКонфигурации = p"config/topaz.toml"
let запрос = sql"SELECT name FROM projects WHERE title = {название}"
print("{название}: {числоСкалярных}")Проверьте и запустите файл:
topaz check strings-templates.tpz
topaz run strings-templates.tpzРезультат:
Topaz 💎: 7В title семь скаляров Unicode: пять букв, пробел и эмодзи. Метод scalars() возвращает Array<string>, где каждый элемент — строка из одного скаляра. Позиция в тексте не совпадает с позицией байта в памяти, а неявная нормализация Unicode в Топазе отсутствует.
configPath — шаблон p, сохраняющий намерение нормализовать путь. query — шаблон sql. {title} становится границей параметра, а не прямой вставкой в текст SQL. Программа не выводит эти значения, поскольку структурированные шаблоны не являются обычными отображаемыми строками.
Выберите форму по требуемому значению
| Задача | Форма | Граница |
|---|---|---|
| Показать или сравнить текст | "Hello, {name}" | Интерполяция использует стандартное отображение значения |
| Записать многострочный текст | """...""" | Отступ закрывающих кавычек определяет точное удаление отступа |
| Представить путь | p"config/app.toml" | Сохраняется намерение нормализации пути для платформы |
| Представить регулярное выражение | r"^[a-z]+$" | Переносится только заданный минимум правил экранирования |
| Представить команду оболочки | sh"tool {argument}" | Создание значения не запускает процесс |
| Представить параметризованный SQL | sql"WHERE id = {id}" | Интерполяция становится метаданными параметра |
Все четыре тега p, r, sh и sql сочетаются как с обычными, так и с тройными кавычками. Между тегом и открывающей кавычкой нельзя ставить пробел. Запись p "file" разбирается как имя и отдельная строка, а не как вызов, поэтому она приводит к синтаксической ошибке.
Обычные и многострочные строки используют интерполяцию {expression} и единый фиксированный набор управляющих последовательностей. Если сразу после первых тройных кавычек следует перенос строки, он не входит в содержимое. Префикс из пробелов и табуляций перед закрывающими кавычками должен присутствовать у каждой непустой строки и затем удаляется.
Все тегированные шаблоны (p, r, sh и sql) создают значение встроенного непрозрачного типа template. При явном указании типа привязки или возвращаемого значения используйте template, например let query: template = sql"..." или function query() -> template { ... }. Тип template отличен от string. Аксессор .tag возвращает имя создавшего тега в виде string, а .parts — литеральные сегменты между интерполяциями в виде Array<string>.
Частая ошибка
Не применяйте к строке text[0], text.length или срез. Сначала получите text.scalars(), а затем используйте обычные операции Array. Это доступ по скалярам, а не обещание сегментации на кластеры графем.
Обратные кавычки, ${expression}, одинарные кавычки, html"...", незарегистрированные соседние теги и пользовательские теги не являются каноническими. Шаблон sh ничего не запускает, а интерполяция SQL не допускает прямой вставки исходного текста. HTML-шаблоны, регистрация пользовательских тегов, API кластеров графем, прямые срезы строк, единый диалект регулярных выражений для всех платформ и выполнение команд оболочки находятся за пределами этой языковой поверхности.
Значение template нельзя использовать вместо обычной строки string. Поскольку template является именем встроенного типа, объявления record template, enum template и newtype template отклоняются.
Кавычки и переносы объясняет раздел Лексика и структура исходного кода, отображение значений — Поведение среды выполнения, а намеренно недоступные записи — Запрещённые и отложенные формы.