Строки и шаблоны

Строковые литералы — самый сложный вид литеральных выражений в OpenTofu, а также самый часто используемый.

OpenTofu поддерживает для строк синтаксис в кавычках и синтаксис «heredoc». Оба синтаксиса поддерживают шаблонные последовательности для подстановки значений и обработки текста.

Строки в кавычках​

Строка в кавычках — это последовательность символов, ограниченная прямыми двойными кавычками (").

"hello"

Последовательности экранирования​

В строках в кавычках символ обратной косой черты служит для обозначения последовательности экранирования, а следующие за ним символы определяют способ экранирования:

Есть также две специальные последовательности экранирования, в которых не используется обратная косая черта:

Строки heredoc​

OpenTofu также поддерживает литералы строк в стиле «heredoc», вдохновлённые языками командной оболочки Unix. Они позволяют нагляднее задавать многострочные строки.

<<EOT
hello
world
EOT

Строка heredoc состоит из следующих элементов:

• Начальная последовательность, состоящая из:
  • Маркера heredoc (<< или <<- — двух знаков «меньше», с необязательным дефисом для heredoc с отступом)
  • Выбранного вами слова-разделителя
  • Перевода строки
• Содержимого строки, которое может занимать любое количество строк
• Выбранного вами слова-разделителя, указанного отдельно в собственной строке (для heredoc с отступом допускается отступ)

Маркер <<, за которым в конце строки следует любой идентификатор, вводит эту последовательность. Затем OpenTofu обрабатывает следующие строки, пока не найдёт строку, состоящую только из идентификатора, указанного во вводной части.

В приведённом выше примере выбран идентификатор EOT. Допускается любой идентификатор, но по соглашению его записывают заглавными буквами и начинают с EO, что означает «конец чего-либо». В данном случае EOT означает «конец текста».

Создание JSON или YAML​

Не используйте строки «heredoc» для создания JSON или YAML. Вместо этого используйте функцию jsonencode или функцию yamlencode, чтобы OpenTofu мог гарантировать корректный синтаксис JSON или YAML.

  example = jsonencode({
    a = 1
    b = "hello"
  })

Heredoc с отступом​

В стандартной форме heredoc (показанной выше) все пробельные символы считаются обычными пробелами. Если вы не хотите, чтобы каждая строка начиналась с пробелов, строки нужно выравнивать по левому краю, что может быть неудобно для выражений внутри блока с отступом:

block {
  value = <<EOT
hello
world
EOT
}

Для решения этой проблемы OpenTofu также поддерживает вариант строки heredoc с отступом, вводимый последовательностью <<-:

block {
  value = <<-EOT
  hello
    world
  EOT
}

В этом случае OpenTofu анализирует строки последовательности, чтобы найти строку с наименьшим количеством начальных пробелов, а затем удаляет такое же количество пробелов в начале всех строк. В результате получается следующее:

hello
  world

Последовательности экранирования​

Последовательности с обратной косой чертой не интерпретируются как управляющие последовательности в строковом выражении heredoc. Вместо этого символ обратной косой черты интерпретируется буквально.

В heredoc поддерживаются две специальные последовательности экранирования, в которых не используется обратная косая черта:

Шаблоны строк​

В строковых выражениях в кавычках и heredoc последовательности ${ и %{ начинают шаблонные последовательности. Шаблоны позволяют напрямую встраивать выражения в строковый литерал и динамически формировать строки из других значений.

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

Последовательность ${ ... } представляет собой интерполяцию: она вычисляет выражение между маркерами, при необходимости преобразует результат в строку и вставляет его в итоговую строку:

"Hello, ${var.name}!"

В приведённом выше примере выполняется обращение к именованному объекту var.name, и его значение вставляется в строку, в результате чего получается строка вида «Hello, Juan!».

Директивы​

Последовательность %{ ... } представляет собой директиву, которая позволяет получать условные результаты и выполнять итерации по коллекциям, подобно условным выражениям и выражениям for.

Поддерживаются следующие директивы:

• Директива %{if <BOOL>}/%{else}/%{endif} выбирает один из двух шаблонов в зависимости от значения логического выражения:

  "Hello, %{ if var.name != "" }${var.name}%{ else }unnamed%{ endif }!"

  Часть else можно опустить; в этом случае, если условное выражение возвращает false, результатом будет пустая строка.

• Директива %{for <NAME> in <COLLECTION>} / %{endfor} перебирает элементы заданной коллекции или структурного значения, вычисляет заданный шаблон для каждого элемента и объединяет результаты:

  <<EOT
  %{ for ip in aws_instance.example[*].private_ip }
  server ${ip}
  %{ endfor }
  EOT

  Имя, указанное сразу после ключевого слова for, используется как имя временной переменной, на которую затем можно ссылаться во вложенном шаблоне.

Удаление пробельных символов​

Чтобы форматировать директивы шаблона для удобства чтения, не добавляя в результат нежелательные пробелы и символы новой строки, во всех шаблонных последовательностях можно использовать необязательные маркеры удаления пробелов (~). Их размещают сразу после открывающих символов или непосредственно перед закрывающими. Если маркер удаления пробелов присутствует, шаблонная последовательность поглощает все буквальные пробельные символы (пробелы и символы новой строки) перед последовательностью (если маркер стоит в начале) или после неё (если маркер стоит в конце):

<<EOT
%{ for ip in aws_instance.example[*].private_ip ~}
server ${ip}
%{ endfor ~}
EOT

В приведённом выше примере символ новой строки после каждой директивы не включается в вывод, а символ новой строки после последовательности server ${ip} сохраняется. Благодаря этому для каждого элемента создаётся только одна строка:

server 10.1.16.154
server 10.1.16.1
server 10.1.16.34

При использовании директив шаблонов рекомендуется всегда применять строковый литерал в форме «heredoc», форматируя шаблон в несколько строк для удобства чтения. Строковые литералы в кавычках обычно должны содержать только последовательности интерполяции.