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

Строковые литералы — самый сложный вид литеральных выражений в 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», а затем для удобства чтения форматировать шаблон в несколько строк. Строковые литералы в кавычках обычно должны содержать только последовательности интерполяции.