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

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