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

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

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

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

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

"hello"

Управляющие последовательности​

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

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

Строки heredoc​

OpenTofu также поддерживает строковые литералы в формате heredoc, вдохновлённом языками Unix shell. Этот формат позволяет нагляднее записывать многострочные строки.

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