Для текста, который программа выводит или сравнивает, используйте обычную строку. Зарегистрированный тег требуется, когда значение должно сохранять структуру пути, регулярного выражения, команды оболочки или 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} и единый фиксированный набор управляющих последовательностей. Если сразу после первых тройных кавычек следует перенос строки, он не входит в содержимое. Префикс из пробелов и табуляций перед закрывающими кавычками должен присутствовать у каждой непустой строки и затем удаляется.
Частая ошибка
Не применяйте к строке text[0], text.length или срез. Сначала получите text.scalars(), а затем используйте обычные операции Array. Это доступ по скалярам, а не обещание сегментации на кластеры графем.
Обратные кавычки, ${expression}, одинарные кавычки, html"...", незарегистрированные соседние теги и пользовательские теги не являются каноническими. Шаблон sh ничего не запускает, а интерполяция SQL не допускает прямой вставки исходного текста. HTML-шаблоны, регистрация пользовательских тегов, API кластеров графем, прямые срезы строк, единый диалект регулярных выражений для всех платформ и выполнение команд оболочки находятся за пределами этой языковой поверхности.
Кавычки и переносы объясняет раздел Лексика и структура исходного кода, отображение значений — Поведение среды выполнения, а намеренно недоступные записи — Запрещённые и отложенные формы.