Строковый литерал

Строковый литерал - это запись значения строкового встроенного класса (STRING[N] или TEXT) — в простом случае константы.

Синтаксис

'content'
r'rawContent'

Где content — последовательность обычных символов, экранирующих последовательностей, блоков интерполяции ${...} и встраиваемых последовательностей ($I{...}, $R{...}, $M{...}), а rawContent — последовательность символов, взятая как есть. Префикс r можно записывать и в верхнем регистре (R).

Содержимое и экранирование

Обычный литерал 'content' — последовательность символов между одинарными кавычками. Специальные символы задаются экранирующими последовательностями:

Последовательность	Значение
\n	перевод строки
\r	возврат каретки
\t	табуляция
\'	одинарная кавычка
\\	обратная косая черта
\$	символ $

Символ $ является специальным только перед {, I{, R{ или M{ (начало интерполяции или встраиваемой последовательности), в остальных случаях это обычный символ. Чтобы получить обычный $ даже перед {, его необходимо экранировать: \$.

Символы { и } без экранирования выделяют идентификатор локализации, поэтому для вставки самих скобок применяется экранирование \{ и \}. В строках, где локализация не поддерживается (технические аргументы — формулы, кодировки, сочетания клавиш и т. п.), фигурные скобки являются обычными символами, а их экранирование недопустимо.

Любая другая экранирующая последовательность (\ с другим символом), а также одиночный символ \ в конце литерала считаются ошибкой.

Примеры

line (Order o) = 'Заказ №' + number(o) + '\tот ' + date(o);
tpl = 'Итого: \$\{sum\}';                    // текст "Итого: ${sum}" без интерполяции и локализации

Многострочность

Литерал может занимать несколько физических строк — реальные переносы строк внутри кавычек сохраняются в значении (вместе с отступами строк-продолжения). Последовательность \r\n нормализуется в \n.

Примеры

note = 'первая строка
вторая строка';          // то же, что 'первая строка\nвторая строка'

query = 'SELECT *
         FROM orders';   // отступ входит в значение: 'SELECT *\n         FROM orders'

Локализация

Внутри строкового литерала идентификаторы строковых данных в фигурных скобках (например, '{form.title}') заменяются при отправке значения на клиент переводом, соответствующим текущей локали. Если перевода для идентификатора нет ни в одном ResourceBundle, на его место подставляется сам идентификатор без фигурных скобок.

Если сервер запущен с параметром logics.lsfStrLiteralsLanguage (обратный перевод литералов), который задаёт язык строковых литералов в коде, обычный (не локализуемый) литерал может автоматически стать локализуемым. Если его значение (без начальных и конечных пробелов) совпадает со значением записи ResourceBundle на этом языке, литерал при разборе кода заменяется идентификатором этой записи и далее ведёт себя как локализуемый литерал '{id}'. Начальные и конечные пробелы при этом сохраняются, а пустой или состоящий только из пробелов литерал не заменяется.

Фигурные скобки, которые должны быть просто частью строки, необходимо экранировать: \{ и \}.

Примеры

formTitle = '{orders.title}';                // один идентификатор — подставится перевод
header = '{period.from} — {period.to}';      // несколько идентификаторов в одном литерале
json = '\{"status": {order.status}\}';       // \{ \} — часть строки, {order.status} — идентификатор

Интерполяция

Интерполяция позволяет вставлять значения выражений прямо в строковый литерал, не собирая строку вручную через +. Блок ${expr} подставляет значение выражения, приводя его к строке: литерал превращается в конкатенацию ('a${x}b' эквивалентно 'a' + STRING(x) + 'b'). Таких блоков в литерале может быть несколько, а текст между ними подчиняется обычным правилам литерала (экранирование, локализация).

Поскольку результат — конкатенация, литерал с интерполяцией является выражением, а не константой, и допустим только там, где допустимо выражение. Выражению доступны все параметры окружающей конструкции.

Внутри ${...} можно использовать вложенные строковые литералы — их кавычки записываются экранированными (\'), а при разборе это экранирование снимается.

Примеры

greeting (Customer c) = 'Здравствуйте, ${name(c)}!';
likePattern (STRING s) = '%${s}%';           // например, для оператора LIKE
status (Order o) = 'Статус: ${IF paid(o) THEN \'оплачен\' ELSE \'нет\'}';   // вложенный литерал: кавычки экранируются

Встраиваемые последовательности (inline)

Встраиваемые последовательности вставляют в строку внешнее содержимое. Как и интерполяция, они начинаются с символа $:

• $I{resourceName} — включает содержимое текстового файла resourceName в строковый литерал. Файл читается на этапе разбора кода, а его содержимое становится частью литерала. Блоки интерполяции ${...} при этом обрабатываются как обычная интерполяция с параметрами текущей конструкции. Поэтому в файле нельзя использовать буквальную последовательность ${ (например, в JavaScript или CSS). Все остальные символы вроде кавычек, обратных слэшей и фигурных скобок экранировать в файле не требуется — платформа делает это автоматически. Может быть использована для хранения больших параметризуемых шаблонов: HTML-писем, страниц, фрагментов и т. п.
• $R{resourceName} — встраивает содержимое файла resourceName в строку не при разборе кода, а в момент отправки значения на клиент. Файл при этом может быть произвольным, в том числе двоичным (изображение, PDF), и его содержимое как код не обрабатывается. Может быть использована внутри HTML.
• $M{imageName} — встраивает изображение по имени imageName. В отличие от $R{} (файл по пути), это имя интерпретируется так же, как имена иконок свойств и действий.

Примеры

letterBody (Order o) = HTML('$I{orders/letterBody.html}');

Файл orders/letterBody.html:

<h3>Заказ №${number(o)}</h3>
<p>Клиент: ${nameCustomer(o)}</p>

Если у заказа номер 100, а имя клиента — Иванов, значение letterBody будет:

<h3>Заказ №100</h3>
<p>Клиент: Иванов</p>

$R встраивает в строку (обычно HTML) сам файл:

banner () = HTML('<img src="$R{images/banner.png}">');   // файл images/banner.png встраивается в HTML

Сырой (raw) литерал

Литерал с префиксом r (или R) записывает содержимое как есть: экранирующие последовательности не интерпретируются, обратная косая черта и фигурные скобки — обычные символы, локализация и обратный перевод не выполняются (нормализуется только \r\n в \n). Класс значения такого литерала — STRING[N]. Его использование удобно для строк, в которых много обратных косых или фигурных скобок и сплошное экранирование мешало бы читаемости: путей Windows, регулярных выражений, форматов, фрагментов JSON.

Форма r'...' не допускает одинарную кавычку внутри. Чтобы использовать кавычку внутри, применяется форма с символом-разделителем: один и тот же символ ставится между r и открывающей кавычкой и сразу после закрывающей (например, r!'...'!). Такой литерал заканчивается на кавычке, за которой сразу идёт этот символ-разделитель. Поэтому разделитель нужно выбирать так, чтобы сочетание одинарной кавычки и этого символа не встречалось внутри строки, иначе литерал завершится на нём раньше времени. Разделителем может быть любой символ, кроме латинских букв, цифр, подчёркивания, пробела, перевода строки, табуляции, одинарной кавычки и символов + * , = < > ( ) [ ] { } #.

Примеры

filePath = r'C:\reports\sales.xlsx';         // обратные косые — обычные символы
quoted = r!'don't stop'!;                    // кавычка внутри — форма с разделителем

Класс значения

Класс литерала-константы — STRING[N], где N — число символов. Если литерал использует локализацию, его класс — TEXT (см. встроенные классы). Например, 'abc' имеет класс STRING[3], а '{orders.title}' — класс TEXT. Литерал с интерполяцией или встраиваемой последовательностью (${...}, $I{...}, $R{...}, $M{...}) — это выражение, поэтому класс его значения — строковый класс (STRING[N] или TEXT), выводимый из составляющих его частей (постоянных фрагментов и вставляемых значений).