Для текста, который программа выводит или сравнивает, используйте обычную строку. Зарегистрированный тег нужен, когда значение должно сохранять структуру пути, регулярного выражения, команды оболочки или SQL. Шаблон — не строка с декоративным префиксом, а значение с другой границей применения.
Начните с наблюдаемого текста Unicode
Сохраните код в strings-templates.tpz:
let title = "Topaz 💎"
let scalarCount = title.scalars().length
let configPath = p"config/topaz.toml"
let query = sql"SELECT name FROM projects WHERE title = {title}"
print("{title}: {scalarCount}")Проверьте и запустите файл:
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 кластеров графем, прямые срезы строк, единый диалект регулярных
выражений для всех платформ и выполнение команд оболочки лежат вне этой
языковой поверхности.
Кавычки и переносы объясняет раздел Лексика и структура исходного кода, отображение значений — Поведение среды выполнения, а намеренно недоступные записи — Запрещённые и отложенные формы.