Загрузка spiff - Загрузка исходного кода spiff

                                              _  __  __             
                                    ___ _ __ (_)/ _|/ _|  _     _   
                                   / __| '_ | | |_| |_ _| |_ _| |_ 
                                   __  |_) | |  _|  _|_   _|_   _|
                                   |___/ .__/|_|_| |_|   |_|   |_|  
                                       |_|

ПРИМЕЧАНИЕ . Активная разработка spiff в настоящее время приостановлена, включая запросы на извлечение. `spiff++` — это форк spiff, который предоставляет совместимое расширение spiff на основе последней версии, предлагающее богатый набор новых функций, еще не доступных в spiff. Все исправления, внесенные в исходный проект spiff, также будут включены в spiff++. Поскольку пути назад к исходной базе spiff не будет, был создан новый независимый репозиторий spiff++ для продолжения разработки spiff++.

spiff — это инструмент командной строки и декларативная внутридоменная гибридная система шаблонов YAML. В то время как обычные системы шаблонов обрабатывают файл шаблона, заменяя выражения шаблона значениями, взятыми из внешних источников данных, внутридоменная система означает, что механизм шаблонов знает о синтаксисе и структуре обрабатываемого шаблона. Таким образом, он может принимать значения для выражений шаблона непосредственно из обрабатываемого документа, включая те части, которые обозначены самими выражениями шаблона.

Например:

 resource :
  name : bosh deployment
  version : 25
  url : (( "http://resource.location/bosh?version=" version ))
  description : (( "This document describes a " name " located at " url ))

Вместо использования только внешних источников значений spiff предоставляет механизм слияния для объединения шаблона с любым количеством заглушек слияния для создания окончательного документа.

Это инструмент командной строки и декларативная система шаблонов YAML, специально разработанная для создания манифестов развертывания (например, манифестов BOSH, Kubernetes или Landscaper).

Помимо CLI существует библиотека golang, позволяющая использовать обработку шаблонов spiff в любой программе GO (например, Landscaper).

Механизм шаблонов обеспечивает доступ к файловой системе на основе настраиваемой виртуальной файловой системы или системы процессов для выполнения команд и включения вывода в обработку шаблона.

Содержание:

Установка
Использование
Флаги функций
Библиотеки
Язык шаблонов dynaml
- (( фу ))
- (( foo.bar.[1].baz ))
- (( foo.[bar].baz ))
- (( список.[1..3] ))
- (( тег::foo ))
- (( 1.2e4 ))
- (( "фу" ))
- (( [ 1, 2, 3 ] ))
- (( { "Алиса" = 25 } ))
- (( ( "алиса" = 25 ) Алиса ))
- ((фу бар))
  - (( "фу" бар ))
  - (( [1,2] бар ))
  - (( карта1 карта2 ))
- (( авто ))
- (( объединить ))
  - <<: (( объединить ))
    - объединение карт
    - объединение списков
  - - <<: ((объединить по ключу))
  - <<: ((объединить замену))
    - объединение карт
    - объединение списков
  - <<: (( фу ))
    - объединение карт
    - объединение списков
  - <<: (( объединить foo ))
    - объединение карт
    - объединение списков
  - <<: ((объединить нет))
- (( а || б ))
- (( 1 + 2 * фу))
- (( "10.10.10.10" - 11 ))
- (( а > 1 ? foo :bar ))
- (( 5 - или 6 ))
- Функции
  - (( format( "%s %d", Алиса, 25)) ))
  - (( присоединиться( ", ", список)) ))
  - (( разделить( ",", строка)) ))
  - (( обрезка(строка) ))
  - (( элемент(список, индекс) ))
  - (( элемент(карта, ключ)))
  - (( компактный(список))
  - ((уник(список) ))
  - (( содержит(список, "foobar") ))
  - (( index(list, "foobar") ))
  - ((lastindex(list, "foobar") ))
  - (( базовое имя(путь) ))
  - ((имя_каталога(путь) ))
  - (( parseurl("http://github.com"))
  - (( сортировка(список))
  - (( replace(string, "foo", "bar") ))
  - (( substr(строка, 1, 2) ))
  - (( match("(f. )(b. )", "xxxfoobar") ))
  - (( ключи(карта))
  - (( длина(список))
  - (( base64(строка) ))
  - (( хэш(строка) ))
  - (( bcrypt("пароль", 10)) ))
  - (( bcrypt_check("пароль", хэш) ))
  - (( md5crypt("пароль") ))
  - (( md5crypt_check("пароль", хеш)))
  - (( расшифровать («секрет») ))
  - (( rand("[:alnum:]", 10)) ))
  - (( тип(фубар) ))
  - (( определено(foobar) ))
  - ((действительно(фубар) ))
  - (( требуется(фубар) ))
  - (( заглушка(foo.bar) ))
  - (( tagdef("тег", значение))
  - (( eval(foo "." bar )))
  - (( окр( ГЛАВНАЯ" ) ))
  - (( static_ips(0, 1, 3) ))
  - (( ipset(диапазоны, 3, 3,4,5,6) ))
  - (( list_to_map(список, "ключ") ))
  - (( makemap(список полей) ))
  - (( makemap(ключ, значение) ))
  - (( объединить(карта1, карта2) ))
  - ((пересечение(список1, список2) ))
  - (( обратный(список) ))
  - (( анализ(ямлорджсон) ))
  - (( asjson(выражение) ))
  - (( асямл(выражение) ))
  - (( улов(выражение) ))
  - (( проверить (значение, «dnsdomain») ))
  - (( проверка(значение,"dnsdomain") ))
  - (( ошибка("сообщение") ))
  - Математика
  - Конверсии
  - Доступ к внешнему контенту
    - ((прочитать("file.yml") ))
    - (( exec("команда", arg1, arg2)) ))
    - (( канал(данные, "команда", arg1, arg2)) ))
    - (( write("file.yml", данные)) ))
    - (( tempfile("file.yml", данные)) ))
    - (( Lookup_file("file.yml", данные)))
    - (( mkdir("дир", 0755)) ))
    - (( list_files(".") ))
    - (( архив(файлы, "tar") ))
  - Функции семантического управления версиями
    - (( semver("v1.2-beta.1") ))
    - (( semverrelease("v1.2.3-beta.1") ))
    - (( semvermajor("1.2.3-бета.1") ))
    - (( semverminor("1.2.3-бета.1") ))
    - (( semverpatch("1.2.3-beta.1") ))
    - (( semverprerelease("1.2.3-beta.1") ))
    - (( semvermetadata("1.2.3+демо") ))
    - (( semvercmp("1.2.3", "1.2.3-бета.1") ))
    - (( semvermatch("1.2.3", "~1.2") ))
    - (( semversort("1.2.3", "1.2.1") ))
  - X509 Функции
    - (( x509genkey(спецификация) ))
    - (( x509publickey(ключ) ))
    - (( x509cert(спецификация) ))
  - Функции защиты проводов
    - (( wggenkey() ))
    - (( wgpublickey(ключ) ))
- (( лямбда |x|->x ":" порт))
  - Позиционные и именованные аргументы
  - Области видимости и лямбда-выражения
  - Необязательные параметры (( |x,y=2|-> x * y ))
  - Списки переменных аргументов (( |x,y...|-> xy ))
  - Каррирование (( функция*(1) ))
- (( catch[expr|v,e|->v] ))
- (( sync[выражение|v,e|->определено(v.field),v.field|10] ))
- Встроенное расширение списка (( [a, list..., b] ))
- Сопоставления
  - ((map[list|elem|->dynaml-expr] ))
  - (( карта[список|idx,elem|->dynaml-выражение] ))
  - (( карта[карта|ключ,значение|->dynaml-выражение] ))
  - ((map{map|elem|->dynaml-expr})
  - ((map{list|elem|->dynaml-expr})
  - (( select[expr|elem|->dynaml-expr] ))
  - (( select{map|elem|->dynaml-expr} ))
- Агрегации
  - (( sum[list|initial|sum,elem|->dynaml-expr] ))
  - (( sum[list|initial|sum,idx,elem|->dynaml-expr] ))
  - (( sum[map|initial|sum,key,value|->dynaml-expr] ))
- Прогнозы
  - (( выражение[*].значение ))
  - (( список.[1..2].значение ))
- Маркеры
  - (( &временный ))
  - (( &местный ))
  - (( &динамический ))
  - (( &внедрить))
  - (( &по умолчанию ))
  - (( &состояние ))
  - (( &тег:имя ))
- Теги
  - (( &тег:имя(значение) ))
  - (( тег::foo ))
  - (( ярлык::. ))
  - (( foo.bar::алиса ))
  - Разрешение пути для тегов
  - Теги в потоках нескольких документов
- Шаблоны
  - <<: (( &шаблон ))
  - (( *foo.bar ))
- Ссылки на область применения
  - _
  - __
  - ___
  - __ctx.OUTER
- Специальные литералы
- Доступ к контексту оценки
- Приоритеты операций
- Строковая интерполяция
- Структуры управления на основе YAML
  - в Картах
  - в списках
  - <<if:
  - <<switch:
  - <<type:
  - <<for:
    - Списки как результат итерации
    - Карты как результат итерации
  - <<merge:
Структурное автоматическое слияние
Собираем все это вместе
Полезно знать
Отчеты об ошибках
Использование spiff в качестве библиотеки Go

Установка

Официальные исполняемые файлы можно загрузить через выпуски Github для компьютеров Darwin, Linux и PowerPC (и виртуальных машин).

Некоторые зависимости spiff изменились со времени последнего официального выпуска, и spiff не будет обновляться, чтобы соответствовать этим зависимостям. Эти зависимости либо фиксируются, либо копируются в локальную базу кода.

Использование

`spiff merge template.yml [template2.yml ...]`

Объедините кучу файлов шаблонов в один манифест и распечатайте его.

Подробную информацию о файле шаблона см. в разделе «Язык шаблонов Dynaml» или в подкаталоге «examples/subdir» для более сложных примеров.

Пример:

 spiff merge cf-release/templates/cf-deployment.yml my-cloud-stub.yml

Можно прочитать один файл со стандартного ввода, используя имя файла - . Его можно использовать только один раз. Это позволяет использовать spiff как часть конвейера для обработки одного потока или обработки потока на основе нескольких шаблонов/заглушек.

Файл шаблона (первый аргумент) может представлять собой поток из нескольких документов, содержащий несколько документов YAML, разделенных строкой, содержащей только --- . Каждый документ YAML будет обрабатываться независимо с заданными файлами-заглушками. Результатом является поток обработанных документов в том же порядке. Если корневой узел документа помечен как временный, документ исключается из выходного потока. Например, это можно использовать для создания манифестов Kubernetes , которые будут использоваться kubectl .

Команда merge предлагает несколько вариантов:

Опция --partial . Если указана эта опция, spiff обрабатывает неполную оценку выражения. Все ошибки игнорируются, а неразрешимые части документа yaml возвращаются в виде строк.
С опцией --json выходные данные будут в формате JSON вместо YAML.
Опцию --path <path> можно использовать для вывода вложенного пути вместо всего обработанного документа.
Если вывод представляет собой список, опция --split выводит каждый элемент списка как отдельный документ. В формате yaml в качестве разделительной строки используется, как обычно --- . Формат json выводит последовательность документов json , по одному в строке.
С помощью --select <field path> можно выбрать выделенное поле обрабатываемого документа для вывода.
С помощью --evaluate <dynaml expression> можно оценить данное выражение dynaml в обработанном документе для вывода. Выражение оценивается перед применением пути выбора, который затем будет работать с результатом оценки.
Опция --state <path> включает поддержку состояния spiff . Если данный файл существует, он помещается поверх настроенного списка заглушек, поскольку данный файл существует, он помещается поверх настроенного списка заглушек для обработки слияния. Помимо вывода обработанного документа он фильтруется по узлам, отмеченным маркером &state . Этот отфильтрованный документ затем сохраняется в указанном файле, сохраняя старый файл состояния с суффиксом .bak . Это можно использовать вместе с ручным объединением, предлагаемым государственной служебной библиотекой.
С опцией --bindings <path> можно указать файл yaml, содержимое которого используется для создания дополнительных привязок для обработки. Документ yaml должен состоять из карты. Каждый ключ используется как дополнительная привязка. Документ привязок не обрабатывается, значения используются как определено.
С опцией --tag <tag>:<path> можно указать файл yaml, содержимое которого используется в качестве значения для предопределенного глобального тега (см. Теги). Доступ к тегам можно получить с помощью ссылочных выражений формы <tag>::<ref> . В отличие от привязок помеченный контент не конкурирует с узлами документа, он использует другое ссылочное пространство имен.
С помощью опции --define <key>=<value> (сокращение -D ) дополнительные значения привязки можно указать в командной строке, переопределяя значения привязки из файла привязки. Опция может встречаться несколько раз.
Если ключ содержит точки ( . ), он будет интерпретироваться как выражение пути для описания полей в значениях глубокой карты. Точку (и перед точкой) можно экранировать символом чтобы сохранить ее в имени поля.
Опция --preserve-escapes сохранит экранирование для динамических выражений и директив слияния списка/карты. Эту опцию можно использовать, если предполагается дальнейшая обработка результата обработки с помощью spiff .
Опция --preserve-temporary сохранит поля, помеченные как временные в конечном документе.
Опция --features=<featurelist> включит данную функцию. Новые функции, несовместимые со старым поведением, должны быть явно включены. Обычно эти функции не нарушают общепринятое поведение, а вводят специальную интерпретацию значений yaml, которые раньше использовались как обычные значения.

Библиотеки папок содержат несколько полезных служебных библиотек. Их также можно использовать в качестве примера мощности этого шаблонизатора.

`spiff diff manifest.yml other-manifest.yml`

Покажите структурные различия между двумя манифестами развертывания. Здесь также поддерживаются потоки с несколькими документами. Чтобы указать отсутствие разницы, количество документов в обоих потоках должно быть идентичным, и каждый документ в первом потоке не должен иметь различий по сравнению с документом с тем же индексом во втором потоке. Найденные различия показаны для каждого документа отдельно.

В отличие от базовых инструментов сравнения и даже bosh diff , эта команда обладает семантическим знанием манифеста развертывания, а не просто текстовым. Например, если два манифеста одинаковы, за исключением того, что некоторые задания перечислены в разном порядке, spiff diff обнаружит это, поскольку порядок заданий имеет значение в манифесте. С другой стороны, если два манифеста различаются, например, только порядком пулов ресурсов, то результат будет пустым, поскольку порядок пулов ресурсов на самом деле не имеет значения для развертывания.

Кроме того, в отличие от bosh diff , эта команда не изменяет ни один файл.

Он предназначен для проверки различий между одним развертыванием и следующим.

Типичный поток:

$ spiff merge template.yml [templates...] > deployment.yml
$ bosh download manifest [deployment] current.yml
$ spiff diff deployment.yml current.yml
$ bosh deployment deployment.yml
$ bosh deploy

`spiff convert --json manifest.yml`

Подкоманду convert можно использовать для преобразования входных файлов в формат JSON или просто для нормализации порядка полей. Доступные параметры: --json , --path , --split или --select в соответствии с их значениями для подкоманды merge .

`spiff encrypt secret.yaml`

Подкоманда encrypt может использоваться для шифрования или дешифрования данных в соответствии с функцией encrypt dynaml. Пароль можно указать в качестве второго аргумента или взять из переменной среды SPIFF_ENCRYPTION_KEY . Последний аргумент можно использовать для передачи метода шифрования (см. функцию encrypt ).

Данные берутся из указанного файла. Если задано - , оно считывается со стандартного ввода.

Если указана опция -d , данные расшифровываются, в противном случае данные читаются как документ yaml и печатается зашифрованный результат.

Флаги функций

Новые функции, несовместимые со старым поведением, должны быть явно включены. Обычно эти функции не нарушают общепринятое поведение, но вводят специальную интерпретацию значений yaml, которые раньше использовались как обычные значения, и поэтому могут нарушить существующие варианты использования.

В настоящее время поддерживаются следующие флаги функций:

Особенность	С	Состояние	Значение
`interpolation`	1.7.0-бета-1	альфа	dynaml как часть строк yaml
`control`	1.7.0-бета-4	альфа	Структуры управления на основе yaml

Флаги активных функций можно запросить с помощью функции dynaml features() в виде списка строк. Если эта функция вызывается со строковым аргументом, она возвращает, включена ли данная функция в данный момент.

Функции можно включить из командной строки с помощью параметра --features , с помощью библиотеки go с помощью функции WithFeatures или вообще путем установки переменной среды SPIFF_FEATURES в список функций. Этот параметр всегда использовался по умолчанию. При использовании настроек spiff Plain() из библиотеки go все переменные среды игнорируются.

Функция может быть указана по имени или к имени, к которому добавлен префикс no , чтобы отключить ее.

Библиотеки

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

Язык шаблонов dynaml

Spiff использует декларативный, свободный от логики язык шаблонов, называемый dynaml (динамический yaml).

Каждый узел Dynaml гарантированно преобразуется в узел YAML. Это не интерполяция строк. Это избавляет разработчиков от необходимости думать о том, как значение будет отображаться в результирующем шаблоне.

Узел dynaml отображается в файле .yml в виде строки, обозначающей выражение, заключенное в две круглые скобки (( <dynaml> )) . Их можно использовать как значение карты или записи в списке. Выражение может занимать несколько строк. В любом случае строковое значение yaml не должно заканчиваться новой строкой (например, с помощью |- ).

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

Например, ((! .field )) сопоставляется со строковым значением (( .field )) и ((!! .field )) сопоставляется со строковым значением ((! .field )) .

Ниже приведен полный список динамических выражений:

`(( foo ))`

Найдите ближайший ключ «foo» (т. е. лексическую область видимости) в текущем шаблоне и введите его.

например:

 fizz :
  buzz :
    foo : 1
    bar : (( foo ))
  bar : (( foo ))
foo : 3
bar : (( foo ))

Этот пример разрешит:

 fizz :
  buzz :
    foo : 1
    bar : 1
  bar : 3
foo : 3
bar : 3

Следующее не будет разрешено, поскольку имя ключа совпадает со значением, которое нужно объединить:

 foo : 1

hi :
  foo : (( foo ))

`(( foo.bar.[1].baz ))`

Найдите ближайший ключ «foo» и оттуда перейдите к .bar.[1].baz .

Путь — это последовательность шагов, разделенных точками. Шаг — это либо слово для карт, либо цифры, заключенные в скобки для индексации списка. Индекс может быть отрицательным (минус, за которым следуют цифры). Отрицательные индексы берутся с конца списка (эффективный индекс = индекс + длина (список)).

Путь, который не может быть разрешен, приводит к ошибке оценки. Если ожидается, что ссылка иногда не будет предоставлена, ее следует использовать в сочетании с '||' (см. ниже), чтобы гарантировать разрешение.

Примечание . Программа Dynaml Grammer была переработана и теперь поддерживает обычный синтаксис индекса. Вместо foo.bar.[1] теперь можно использовать foo.bar[1] .

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

например:

 properties :
  foo : (( something.from.the.stub ))
  something : (( merge ))

Это разрешится до тех пор, пока «что-то» разрешимо, и пока это приведет к чему-то вроде этого:

 from :
  the :
    stub : foo

Если путь начинается с точки ( . ), путь всегда вычисляется от корня документа. Если корень документа представляет собой список, первый уровень карты используется для разрешения выражения пути, если оно начинается с .__map . Это можно использовать, чтобы избежать необходимости использования собственного индекса списка (например .[1].path ), который может измениться при добавлении записей списка.

К записям списка, состоящим из карты с полем name , можно напрямую обращаться по значению имени в качестве компонента пути.

Примечание . Это также работает для абсолютных путей к документам списка.

например:

Возраст Алисы в

 list :
 - name : alice
   age : 25

на него можно ссылаться, используя путь list.alice.age вместо list[0].age .

По умолчанию в качестве ключевого поля используется поле с name name. Если в качестве ключевого поля необходимо использовать другое поле, его можно пометить в одной записи списка как ключевое, добавив к имени поля префикс ключевого слова key: . Это ключевое слово удаляется при обработке и не будет частью окончательного результата обработки.

например:

 list :
 - key:person : alice
   age : 25

alice : (( list.alice ))

будет решено

 list :
 - person : alice
   age : 25

alice :
  person : alice
  age : 25

Это новое ключевое поле также будет учитываться при объединении списков.

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

Если значения ключевого поля не являются уникальными, оно также отключается.

`(( foo.[bar].baz ))`

Найдите ближайший ключ «foo» и оттуда перейдите к полям, описанным в bar выражения, а затем к .baz.

Индекс может быть целочисленной константой (без пробелов), как описано в последнем разделе. Но это также может быть произвольное динамическое выражение (даже целое число, но с пробелами). Если выражение оценивается как строка, оно ищет выделенное поле. Если выражение оценивается как целое число, адресуется элемент массива с этим индексом. Точка ( . ) перед оператором индекса необязательна.

например:

 properties :
  name : alice
  foo : (( values.[name].bar ))
  values :
    alice :
      bar : 42

Это преобразует foo в значение 42 . Динамический индекс также может находиться в конце выражения (без .bar ).

По сути, это более простой способ выразить что-то вроде eval("values." name ".bar").

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

например:

 properties :
  name :
   - foo
   - bar
  foo : (( values.[name] ))
  values :
    foo :
      bar : 42

снова преобразует foo в значение 42 .

Примечание . Оператор индекса также можно использовать для корневого элемента ( .[index] ).

Можно указать несколько индексов, разделенных запятыми, для последовательных списков ( foo[0][1] эквивалентно `foo[0,1]). В таком случае индексы снова не могут быть списками.

`(( list.[1..3] ))`

Выражение среза можно использовать для извлечения выделенного подсписка из выражения списка. Диапазон start..end извлекает список .. end-start+1 с элементами от индекса start до end . Если начальный индекс отрицателен, срез берется из конца списка от length+start до length+end . Если конечный индекс ниже начального, результатом будет пустой массив.

например:

 list :
  - a
  - b
  - c
foo : (( list.[1..length(list) - 1] ))

Начальный или конечный индекс может быть опущен. Затем он выбирается в соответствии с фактическим размером списка. Поэтому list.[1..length(list)] эквивалентен list.[1..] .

оценивает foo в списке [b,c] .

`(( 1.2e4 ))`

Числовые буквы поддерживаются для целых чисел и значений с плавающей запятой.

`(( "foo" ))`

Строковый литерал. Поддерживаются все кодировки строк json (например, n , " или uxxxx ).

`(( [ 1, 2, 3 ] ))`

Список буквальных. Элементы списка снова могут быть выражениями. Существует специальный литерал списка [1 .. -1] , который можно использовать для преобразования возрастающего или уменьшающегося диапазона чисел в список.

например:

 list : (( [ 1 .. -1 ] ))

урожайность

 list :
  - 1
  - 0
  - -1

`(( { "alice" = 25 } ))`

Литерал карты можно использовать для описания карт как части динамического выражения. И ключ, и значение снова могут быть выражениями, при этом ключевое выражение должно оцениваться как строка. Таким образом можно создавать карты с нестатическими ключами. Вместо обычного символа двоеточие : , используемого в yaml, был выбран оператор присваивания = , поскольку это может привести к конфликтам с синтаксисом yaml.

Литерал карты может состоять из любого количества назначений полей, разделенных запятой ,

например:

 name : peter
age : 23
map : (( { "alice" = {}, name = age } ))

урожайность

 name : peter
age : 23
map :
  alice : {}
  peter : 23

Другим способом составления списков на основе выражений являются функции makemap и list_to_map .

`(( ( "alice" = 25 ) alice ))`

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

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

например:

 scoped : (( ( "alice" = 25, "bob" = 26 ) alice + bob ))

урожайность

 scoped : 51

Имя поля также может обозначаться символом ( $ name ).

`(( foo bar ))`

Выражение конкатенации, используемое для объединения последовательности динамических выражений.

`(( "foo" bar ))`

Конкатенация (где bar — это другое динамическое выражение). Любые последовательности простых значений (строковые, целые и логические) могут быть объединены, заданные любым динамическим выражением.

например:

 domain : example.com
uri : (( "https://" domain ))

В этом примере uri будет преобразован в значение "https://example.com" .

`(( [1,2] bar ))`

Объединение списков как выражение (где bar — это другое динамическое выражение). Любые последовательности списков могут быть объединены, заданные любым динамическим выражением.

например:

 other_ips : [ 10.0.0.2, 10.0.0.3 ]
static_ips : (( ["10.0.1.2","10.0.1.3"] other_ips ))

В этом примере static_ips разрешится в значение [ 10.0.1.2, 10.0.1.3, 10.0.0.2, 10.0.0.3 ] .

Если второе выражение возвращает значение, отличное от списка (целое, логическое, строковое или отображаемое), значение добавляется к первому списку.

например:

 foo : 3
bar : (( [1] 2 foo "alice" ))

возвращает список [ 1, 2, 3, "alice" ] для bar .

`(( map1 map2 ))`

Объединение карт как выражение. Любые последовательности карт могут быть объединены, заданные любым динамическим выражением. Таким образом, записи будут объединены. Записи с одинаковым ключом перезаписываются слева направо.

например:

 foo :
  alice : 24
  bob : 25

bar :
  bob : 26
  paul : 27

concat : (( foo bar ))

урожайность

 foo :
  alice : 24
  bob : 25

bar :
  bob : 26
  paul : 27

concat :
  alice : 24
  bob : 26
  paul : 27

`(( auto ))`

Контекстно-зависимый автоматический расчет значений.

В атрибуте «размер» пула ресурсов это означает расчет на основе общего количества экземпляров всех заданий, которые заявили о себе, что находятся в текущем пуле ресурсов.

например:

 resource_pools :
  - name : mypool
    size : (( auto ))

jobs :
  - name : myjob
    resource_pool : mypool
    instances : 2
  - name : myotherjob
    resource_pool : mypool
    instances : 3
  - name : yetanotherjob
    resource_pool : otherpool
    instances : 3

В этом случае размер пула ресурсов будет равен «5».

`(( merge ))`

Введите текущий путь из объединяемых файлов-заглушек.

например:

 foo :
  bar :
    baz : (( merge ))

Попробую внести foo.bar.baz из первой заглушки, или из второй и т.д., возвращая значение из последней заглушки, которая его предоставляет.

Если соответствующее значение не определено, оно вернет ноль. Тогда это имеет ту же семантику, что и ссылочные выражения; нулевое слияние — это неразрешенный шаблон. || .

`<<: (( merge ))`

Объединение карт или списков с содержимым одного и того же элемента, найденного в некоторой заглушке.

** Внимание ** У этой формы merge есть проблемы с совместимостью. В версиях до 1.0.8 это выражение никогда не анализировалось, имело значение только наличие ключа <<: Поэтому часто используется <<: (( merge )) где имеется в виду <<: (( merge || nil )) . Первый вариант потребует содержания хотя бы одной заглушки (как всегда для оператора слияния). Теперь это выражение вычисляется правильно, но это нарушит существующие наборы шаблонов манифестов, которые используют первый вариант, но подразумевают второй. Поэтому этот случай явно обрабатывается для описания необязательного слияния. Если действительно подразумевается обязательное слияние, необходимо использовать дополнительный явный квалификатор.

Примечание . Вместо использования поля вставки <<: для размещения выражений слияния теперь можно также использовать <<<: , что позволяет использовать обычные анализаторы yaml для spiff-подобных yaml-документов. <<: сохраняется для обратной совместимости. использоваться ( (( merge required )) ).

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

Например, ключ карты <<<! приведет к строковому ключу <<< и <<<!! приведет к строковому ключу <<<!

Объединение карт

значения.yml

 foo :
  a : 1
  b : 2

шаблон.yml

 foo :
  << : (( merge ))
  b : 3
  c : 4

spiff merge template.yml values.yml дает:

 foo :
  a : 1
  b : 2
  c : 4

Объединение списков

значения.yml

 foo :
  - 1
  - 2

шаблон.yml

 foo :
  - 3
  - << : (( merge ))
  - 4

spiff merge template.yml values.yml дает:

 foo :
  - 3
  - 1
  - 2
  - 4

`- <<: (( merge on key ))`

spiff умеет объединять списки карт с ключевым полем. Эти списки обрабатываются как карты со значением ключевого поля в качестве ключа. По умолчанию используется name ключа. Но с помощью селектора on выражения слияния списка можно указать произвольное имя ключа.

например:

 list :
  - << : (( merge on key ))
  - key : alice
    age : 25
  - key : bob
    age : 24

слился с

 list :
  - key : alice
    age : 20
  - key : peter
    age : 13

урожайность

 list :
  - key : peter
    age : 13
  - key : alice
    age : 20
  - key : bob
    age : 24

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

`<<: (( merge replace ))`

Заменяет полное содержимое элемента содержимым, найденным в некоторой заглушке, вместо выполнения глубокого слияния существующего содержимого.

Объединение карт

значения.yml

 foo :
  a : 1
  b : 2

шаблон.yml

 foo :
  << : (( merge replace ))
  b : 3
  c : 4

spiff merge template.yml values.yml дает:

 foo :
  a : 1
  b : 2

Объединение списков

значения.yml

 foo :
  - 1
  - 2

шаблон.yml

 foo :
  - << : (( merge replace ))
  - 3
  - 4

spiff merge template.yml values.yml дает:

 foo :
  - 1
  - 2

`<<: (( foo ))`

Объединение карт и списков, найденных в одном шаблоне или заглушке.

Объединение карт

 foo :
  a : 1
  b : 2

bar :
  << : (( foo )) # any dynaml expression
  b : 3

дает:

 foo :
  a : 1
  b : 2

bar :
  a : 1
  b : 3

Это выражение просто добавляет новые записи в фактический список. Он не объединяет существующие записи с содержимым, описанным выражением слияния.

Объединение списков

 bar :
  - 1
  - 2

foo :
  - 3
  - << : (( bar ))
  - 4

дает:

 bar :
  - 1
  - 2

foo :
  - 3
  - 1
  - 2
  - 4

Распространенным вариантом использования этого является объединение списков статических IP-адресов или диапазонов в список IP-адресов. Другая возможность — использовать одно выражение конкатенации.

`<<: (( merge foo ))`

Объединение карт или списков с содержимым произвольного элемента, найденного в некоторой заглушке (Redirecting merge). Дальнейшего (глубокого) слияния с одноименным элементом, найденным в какой-то заглушке, не будет. (Для глубокого объединения списков требуются карты с name поля)

Слияния перенаправления также можно использовать в качестве прямого значения поля. Их можно комбинировать с заменой слияний, например (( merge replace foo )) .

Объединение карт

значения.yml

 foo :
  a : 10
  b : 20

bar :
  a : 1
  b : 2

шаблон.yml

 foo :
  << : (( merge bar))
  b : 3
  c : 4

spiff merge template.yml values.yml дает:

 foo :
  a : 1
  b : 2
  c : 4

Другой способ слияния с другим элементом в некоторой заглушке также может быть выполнен традиционным способом:

значения.yml

 foo :
  a : 10
  b : 20

bar :
  a : 1
  b : 2

шаблон.yml

 bar :
  << : (( merge ))
  b : 3
  c : 4

foo : (( bar ))

Но в этом случае слияние по-прежнему выполняет глубокое слияние с исходным именем элемента. Поэтому spiff merge template.yml values.yml дает:

 bar :
  a : 1
  b : 2
  c : 4
foo :
  a : 10
  b : 20
  c : 4

Объединение списков

значения.yml

 foo :
  - 10
  - 20

bar :
  - 1
  - 2

шаблон.yml

 foo :
  - 3
  - << : (( merge bar ))
  - 4

spiff merge template.yml values.yml дает:

 foo :
  - 3
  - 1
  - 2
  - 4

`<<: (( merge none ))`

Если для ссылки перенаправленного слияния установлена константа none , слияние вообще не выполняется. Это выражение всегда дает нулевое значение.

например: для

шаблон.yml

 map :
  << : (( merge none ))
  value : notmerged

значения.yml

 map :
  value : merged

spiff merge template.yml values.yml дает:

 map :
  value : notmerged

Это можно использовать для явного объединения полей с использованием функции stub для доступа к выделенным частям восходящих заглушек.

например:

шаблон.yml

 map :
  << : (( merge none ))
  value : ((  "alice"  "+" stub(map.value) ))

значения.yml

 map :
  value : bob

spiff merge template.yml values.yml дает:

 test :
  value : alice+bob

Это также работает для выделенных полей:

шаблон.yml

 map :
  value : ((  merge none // "alice"  "+" stub() ))

значения.yml

 map :
  value : bob

spiff merge template.yml values.yml дает:

 test :
  value : alice+bob

`(( a || b ))`

Использует a или b, если a не может быть решена.

например:

 foo :
  bar :
    - name : some
    - name : complicated
    - name : structure

mything :
  complicated_structure : (( merge || foo.bar ))

Будет предпринята попытка слияния с mything.complicated_structure или, если слияние невозможно, используйте значение по умолчанию, указанное в foo.bar .

Оператор // дополнительно проверяет, может ли a быть решена до допустимого значения (не равного ~ ).

`(( 1 + 2 * foo ))`

Выражения Dynaml можно использовать для выполнения целочисленных арифметических вычислений и вычислений с плавающей запятой. Поддерживаемые операции: + , - , * и / . Оператор по модулю ( % ) поддерживает только целочисленные операнды.

например:

значения.yml

 foo : 3
bar : (( 1 + 2 * foo ))

spiff merge values.yml дает 7 для bar . Это можно комбинировать с конкатенациями (вычисление имеет более высокий приоритет, чем конкатенация в динамических выражениях):

 foo : 3
bar : (( foo " times 2 yields " 2 * foo ))

В результате строка 3 times 2 yields 6 .

`(( "10.10.10.10" - 11 ))`

Помимо арифметики с целыми числами, также можно использовать сложение и вычитание IP-адресов и cidr.

например:

 ip : 10.10.10.10
range : (( ip "-" ip + 247 + 256 * 256 ))

урожайность

 ip : 10.10.10.10
range : 10.10.10.10-10.11.11.1

Вычитание также работает с двумя IP-адресами или cidr для расчета количества IP-адресов между двумя IP-адресами.

например:

 diff : (( 10.0.1.0 - 10.0.0.1 + 1 ))

дает значение 256. Константы IP-адреса можно напрямую использовать в динамических выражениях. Они неявно преобразуются в строки и обратно в IP-адреса, если этого требует операция.

Умножение и деление можно использовать для обработки сдвигов диапазона IP-адресов в CIDR. При разделении сеть можно разделить. Размер сети увеличен, чтобы обеспечить как минимум выделенное количество подсетей ниже исходного CIDR. Затем умножение можно использовать для получения n-й следующей подсети того же размера.

например:

 subnet : (( "10.1.2.1/24" / 12 ))  # first subnet CIDR for 16 subnets
next : (( "10.1.2.1/24" / 12 * 2)) # 2nd next (3rd) subnet CIDRS

урожайность

 subnet : 10.1.2.0/28
next : 10.1.2.32/28

Дополнительно есть функции, работающие с CIDR IPv4:

 cidr : 192.168.0.1/24
range : (( min_ip(cidr) "-" max_ip(cidr) ))
next : (( max_ip(cidr) + 1 ))
num : (( min_ip(cidr) "+" num_ip(cidr) "=" min_ip(cidr) + num_ip(cidr) ))
contains : (( contains_ip(cidr, "192.168.0.2") ))

урожайность

 cidr : 192.168.0.1/24
range : 192.168.0.0-192.168.0.255
next : 192.168.1.0
num : 192.168.0.0+256=192.168.1.0
contains : true

`(( a > 1 ? foo :bar ))`

Dynaml поддерживает операторы сравнения < , <= , == , != , >= и > . Операторы сравнения работают с целочисленными значениями. Проверки на равенство также работают со списками и картами. Результатом всегда является логическое значение. Чтобы отменить условие, можно использовать унарный оператор not ( ! ).

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

например:

 foo : alice
bar : bob
age : 24
name : (( age > 24 ? foo :bar ))

возвращает значение bob для name свойства.

Выражение считается false если его значение равно

логическое значение false
целое значение 0
пустая строка, карта или список

В противном случае это считается true

Примечание

Использование символа : может противоречить синтаксису yaml, если полное выражение не является строковым значением в кавычках.

Операторы -or и -and можно использовать для объединения операторов сравнения для составления более сложных условий.

Примечание:

Более традиционный символ оператора || (и && ) здесь нельзя использовать, поскольку оператор || уже существует в dynaml с другой семантикой, которая неприменима для логических операций. Выражение false || true оценивается как false , поскольку возвращает первый операнд, если он определен, независимо от его значения. Чтобы обеспечить максимальную совместимость, это нельзя изменить и использовать простые символы or и and , поскольку это сделает недействительной конкатенацию ссылок с такими именами.

`(( 5 -or 6 ))`

Если обе стороны оператора -or или -and возвращают целочисленные значения, выполняется побитовая операция, и результатом снова является целое число. Следовательно, выражение 5 -or 6 оценивается как 7 .

Функции

Dynaml поддерживает набор предопределенных функций. Функция обычно называется так

 result : (( functionname(arg, arg, ...) ))

Дополнительные функции могут быть определены как часть документа yaml с использованием лямбда-выражений. Тогда имя функции представляет собой либо сгруппированное выражение, либо путь к узлу, содержащему лямбда-выражение.

`(( format( "%s %d", alice, 25) ))`

Отформатируйте строку на основе аргументов, заданных выражениями dynaml. Существует второй вариант этой функции: error форматирует сообщение об ошибке и устанавливает значение неудачной оценки.

`(( join( ", ", list) ))`

Объедините записи списков или прямые значения в одно строковое значение, используя заданную строку-разделитель. Аргументами для объединения могут быть динамические выражения, вычисляющие списки, значениями которых снова являются строки или целые числа, а также строковые или целочисленные значения.

например:

 alice : alice
list :
  - foo
  - bar

join : (( join(", ", "bob", list, alice, 10) ))

возвращает строковое значение bob, foo, bar, alice, 10 для join .

`(( split( ",", string) ))`

Разделите строку на специальный разделитель. Результатом является список. Вместо строки-разделителя может быть указано целочисленное значение, которое разбивает заданную строку на список строк с ограниченной длиной. Длина считается в рунах, а не в байтах.

например:

 list : (( split("," "alice, bob") ))
limited : (( split(4, "1234567890") ))

дает:

 list :
  - alice
  - ' bob '
limited :
  - " 1234 "
  - " 5678 "
  - " 90 "

Можно указать необязательный третий аргумент. Он ограничивает количество возвращаемых записей списка. Значение -1 приводит к неограниченной длине списка.

Если в качестве строки-разделителя необходимо использовать регулярное выражение, можно использовать функцию split_match .

`(( trim(string) ))`

Обрезать строку или все элементы списка строк. Существует необязательный второй строковый аргумент. Его можно использовать для указания набора символов, которые будут вырезаны. Набор вырезов по умолчанию состоит из пробела и символа табуляции.

например:

 list : (( trim(split("," "alice, bob")) ))

дает:

 list :
  - alice
  - bob

`(( element(list, index) ))`

Возвращает выделенный элемент списка, заданный его индексом.

например:

 list : (( trim(split("," "alice, bob")) ))
elem : (( element(list,1) ))

дает:

 list :
  - alice
  - bob
elem : bob

`(( element(map, key) ))`

Возвращает выделенное поле карты, заданное его ключом.

 map :
  alice : 24
  bob : 25
elem : (( element(map,"bob") ))

дает:

 map :
  alice : 24
  bob : 25
elem : 25

Эта функция также может обрабатывать клавиши, содержащие точки (.).

`(( compact(list) ))`

Отфильтруйте список, исключая пустые записи.

например:

 list : (( compact(trim(split("," "alice, , bob"))) ))

дает:

 list :
  - alice
  - bob

`(( uniq(list) ))`

Uniq предоставляет список без дубликатов.

например:

 list :
- a
- b
- a
- c
- a
- b
- 0
- " 0 "
uniq : (( uniq(list) ))

урожайность для поля uniq :

 uniq :
- a
- b
- c
- 0

`(( contains(list, "foobar") ))`

Проверяет, содержит ли список выделенное значение. Значения также могут быть списками или картами.

например:

 list :
  - foo
  - bar
  - foobar
contains : (( contains(list, "foobar") ))

дает:

 list :
  - foo
  - bar
  - foobar
contains : true

Функция contains также работает со строками для поиска подстрок или картами для поиска ключа. В этих случаях элемент должен быть строкой.

например:

 contains : (( contains("foobar", "bar") ))

дает true .

`(( basename(path) ))`

Функция basename возвращает имя последнего элемента пути. Аргументом может быть либо обычный путь, либо URL-адрес.

например:

 pathbase :  (( basename("alice/bob") ))
urlbase :  (( basename("http://foobar/alice/bob?any=parameter") ))

дает:

 pathbase :  bob
urlbase :  bob

`(( dirname(path) ))`

Функция dirname возвращает родительский каталог пути. Аргументом может быть либо обычный путь, либо URL-адрес.

например:

 pathbase :  (( dirname("alice/bob") ))
urlbase :  (( dirname("http://foobar/alice/bob?any=parameter") ))

дает:

 pathbase :  alice
urlbase :  /alice

`(( parseurl("http://github.com") ))`

Эта функция анализирует URL-адрес и создает карту со всеми элементами URL-адреса. Поля port , userinfo и password являются необязательными.

например:

 url :  (( parseurl("https://user:[email protected]:443/mandelsoft/spiff?branch=master&tag=v1#anchor") ))

дает:

 url :
  scheme : https
  host : github.com
  port : 443
  path : /mandelsoft/spiff
  fragment : anchor
  query : branch=master&tag=v1
  values :
    branch : [ master ]
    tag : [ v1 ]
  userinfo :
    username : user
    password : pass

`(( index(list, "foobar") ))`

Проверяет, содержит ли список выделенное значение, и возвращает индекс первого совпадения. Значения также могут быть списками или картами. Если вход не может быть найдено -1 возвращается.

например:

 list :
  - foo
  - bar
  - foobar
index : (( index(list, "foobar") ))

Доходность:

 list :
  - foo
  - bar
  - foobar
index : 2

index функций также работает на строках, чтобы найти подложки.

например:

 index : (( index("foobar", "bar") ))

Доходность 3 .

`(( lastindex(list, "foobar") ))`

Функция lastindex работает как index , но индекс последнего события возвращается.

`((sort (list)))

sort функций может использоваться для сортировки целочисленных или строковых списков. Операция сортировки стабильна.

например:

 list :
  - alice
  - foobar
  - bob

sorted : (( sort(list) ))

Доходность для sorted

- alice
- bob
- foobar

Если другие типы должны быть отсортированы, особенно сложные типы, такие как списки или карты, или требуется другое правило сравнения, функция сравнения может быть указана в качестве дополнительного второго аргумента. Функция сравнения должна быть выражением Lambda, принимающим два аргумента. Тип результата должен быть integer или bool указывающим , меньше, чем b . Если целое число возвращено, оно должно быть

отрицательный, если а <б
ноль, если a == b и
положительный, если a> b

например:

 list :
  - alice
  - foobar
  - bob

sorted : (( sort(list, |a,b|->length(a) < length(b)) ))

Доходность для sorted

- bob
- alice
- foobar

`(( replace(string, "foo", "bar") ))`

Замените все события поднудной строки в строке заменной строкой. С необязательным четвертым целым аргументом количество замен может быть ограничено (-1 среднее неограниченное).

например:

 string : (( replace("foobar", "o", "u") ))

доход к fuubar .

Если регулярное выражение следует использовать в качестве строки поиска, можно использовать функцию replace_match . Здесь строка поиска оценивается как регулярное выражение. Это может Conatain Subsperious. Эти совпадения можно использовать в запасной строке

например:

 string : (( replace_match("foobar", "(o*)b", "b${1}") ))

Доходность fbooar .

Аргумент замены также может быть функцией Lambda. В этом случае для каждого соответствия вызывается функция для определения замены. Одиночный входной аргумент - это список фактических соответствующих соответствующих соответствующих выражений.

например:

 string : (( replace_match("foobar-barfoo", "(o*)b", |m|->upper(m.[1]) "b" ) ))

Доходность fOObar-barfoo .

`(( substr(string, 1, 2) ))`

Извлеките строку заглушки из строки, начиная с заданного индекса начала до необязательного конечного индекса (эксклюзивный). Если конечный индекс не указан, подразделение до конца строки извлекается. Оба индекса могут быть отрицательными. В этом случае они взяты с конца строки.

например:

 string : " foobar "
end1 : (( substr(string,-2) ))
end2 : (( substr(string,3) ))
range : (( substr(string,1,-1) ))

оценивает

 string : foobar
end1 : ar
end2 : bar
range : ooba

`(( match("(f.)(b.)", "xxxfoobar") ))`

Возвращает совпадение регулярного выражения для данного строкового значения. Матч представляет собой список соответствующих значений для подражающих, содержащихся в регулярном выражении. Индекс 0 относится к совпадению полного регулярного выражения. Если значение строки не соответствует пустому списку, возвращается.

например:

 matches : (( match("(f.*)*(b.*)", "xxxfoobar") ))

Доходность:

 matches :
- foobar
- foo
- bar

Третий аргумент целого числа типов может быть предоставлен для запроса на много совпадений в максимум N повторения. Если значение отрицательно, все повторения сообщаются. Результатом является список всех совпадений, каждый из которых в формате, описанный выше.

`(( keys(map) ))`

Определите отсортированный список ключей, используемых на карте.

например:

 map :
  alice : 25
  bob : 25
keys : (( keys(map) ))

Доходность:

 map :
  alice : 25
  bob : 25
keys :
  - alice
  - bob

`(( length(list) ))`

Определите длину списка, карту или строковое значение.

например:

 list :
  - alice
  - bob
length : (( length(list) ))

Доходность:

 list :
  - alice
  - bob
length : 2

`(( base64(string) ))`

Функциональная base64 генерирует кодирование BASE64 данной строки. base64_decode декодирует кодированную строку Base64.

например:

 base64 : (( base64("test") ))
test : (( base64_decode(base64)))

оценивает

 base54 : dGVzdA==
test : test

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

`(( hash(string) ))`

Функциональный hash генерирует несколько видов хэшей для данной строки. По умолчанию, как генерируется хэш sha256 . Необязательный второй аргумент указывает тип хэша. Возможными типами являются md4 , md5 , sha1 , sha224 , sha256 , sha384 , sha2512 , sha512/224 или sha512/256 .

Хэши md5 все еще могут быть сгенерированы устаревшим Finctio md5(string) .

например:

 data : alice

hash :
  deprecated : (( md5(data) ))
  md4 : (( hash(data,"md4") ))
  md5 : (( hash(data,"md5") ))
  sha1 : (( hash(data,"sha1") ))
  sha224 : (( hash(data,"sha224") ))
  sha256 : (( hash(data,"sha256") ))
  sha384 : (( hash(data,"sha384") ))
  sha512 : (( hash(data,"sha512") ))
  sha512_224 : (( hash(data,"sha512/224") ))
  sha512_256 : (( hash(data,"sha512/256") ))

оценивает

 data : alice
hash :
  deprecated : 6384e2b2184bcbf58eccf10ca7a6563c
  md4 : 616c69636531d6cfe0d16ae931b73c59d7e0c089c0
  md5 : 6384e2b2184bcbf58eccf10ca7a6563c
  sha1 : 522b276a356bdf39013dfabea2cd43e141ecc9e8
  sha224 : 38b7e5d5651aaf85694a7a7c6d5db1275af86a6df93a36b8a4a2e771
  sha256 : 2bd806c97f0e00af1a1fc3328fa763a9269723c8db8fac4f93af71db186d6e90
  sha384 : 96a5353e625adc003a01bdcd9b21b21189bdd9806851829f45b81d3dfc6721ee21f6e0e98c4dd63bc559f66c7a74233a
  sha512 : 408b27d3097eea5a46bf2ab6433a7234a33d5e49957b13ec7acc2ca08e1a13c75272c90c8d3385d47ede5420a7a9623aad817d9f8a70bd100a0acea7400daa59
  sha512_224 : c3b8cfaa37ae15922adf3d21606e3a9836ba2a9d7838b040b7c96fd7
  sha512_256 : ad0a339b08dc090fe3b16eae376f7e162836e8728da9c45466842e19508d7627

`(( bcrypt("password", 10) ))`

Функция bcrypt генерирует хэш пароля BCRYPT для данной строки, используя указанный коэффициент затрат (не выполненные по умолчанию до 10, если отсутствует).

например:

 hash : (( bcrypt("password", 10) ))

оценивает

 hash : $2a$10$b9RKb8NLuHB.tM9haPD3N.qrCsWrZy8iaCD4/.cCFFCRmWO4h.koe

`(( bcrypt_check("password", hash) ))`

Функция bcrypt_check проверяет пароль против данного хэша Bcrypt.

например:

 hash : $2a$10$b9RKb8NLuHB.tM9haPD3N.qrCsWrZy8iaCD4/.cCFFCRmWO4h.koe
valid : (( bcrypt_check("password", hash) ))

оценивает

 hash : $2a$10$b9RKb8NLuHB.tM9haPD3N.qrCsWrZy8iaCD4/.cCFFCRmWO4h.koe
valid : true

`(( md5crypt("password") ))`

Функция md5crypt генерирует хэш зашифрованного пароля Apache MD5 для данной строки.

например:

 hash : (( md5crypt("password") ))

оценивает

 hash : $apr1$3Qc1aanY$16Sb5h7U1QrcqwZbDJIYZ0

`(( md5crypt_check("password", hash) ))`

Функция md5crypt_check проверяет пароль против данного зашифрованного хэша Apache MD5.

например:

 hash : $2a$10$b9RKb8NLuHB.tM9haPD3N.qrCsWrZy8iaCD4/.cCFFCRmWO4h.koe
valid : (( bcrypt_check("password", hash) ))

оценивает

 hash : $apr1$B77VuUUZ$NkNFhkvXHW8wERSRoi74O1
valid : true

`(( decrypt("secret") ))`

Эту функцию можно использовать для хранения зашифрованных секретов в файле Spiff YAML. Обработанный результат будет затем содержать расшифрованное значение. Все типы узлов могут быть зашифрованы и расшифрованы, включая полные карты и списки.

Пароль для расшифровки может быть дана либо в качестве второго аргумента, либо (предпочтительного способа), он может быть указан с помощью переменной среды SPIFF_ENCRYPTION_KEY .

Необязательный последний аргумент может выбрать метод шифрования. Единственный метод, поддерживаемый до сих пор, - 3DES . Другие методы могут быть добавлены для выделенных версий Spiff с использованием регистрации метода шифрования, предлагаемой библиотекой Spiff.

Значение может быть зашифровано, используя функцию encrypt("secret") .

например:

 password : this a very secret secret and may never be exposed to unauthorized people
encrypted : (( encrypt("spiff is a cool tool", password) ))
decrypted : (( decrypt(encrypted, password) ))

оценивается на что -то вроде

 decrypted : spiff is a cool tool
encrypted : d889f9e4cc7ae13effcbc8bb8cd0c38d1fb2197738444f753c48796d7946083e6639e5a1bf8f77648f2a1ddf37023c65ff57d52d0519d1d92cbcf87d3e263cba
password : this a very secret secret and may never be exposed to unauthorized people

`(( rand("[:alnum:]", 10) ))`

Функция rand генерирует случайные значения. Первый аргумент решает, какие ценности запрашиваются. Без аргумента он генерирует положительное случайное число в диапазоне int64 .

Тип аргумента	результат
интервал	целочисленное значение в диапазоне [0, N ) для положительного N и ( N , 0] для отрицательного n
логическое значение	логическое значение
нить	Одна строка руны, где руна находится в данном диапазоне символов, может использоваться любая комбинация классов символов или символов, доступных для REGEXP. Если указан дополнительный аргумент длины, полученная строка будет иметь данную длину.

например:

 int :   (( rand() ))
int10 : (( rand(10) ))
neg10 :   (( rand(-10) ))
bool : (( rand(true) ))
string : (( rand("[:alpha:][:digit:]-", 10) ))
upper : (( rand("A-Z", 10) ))
punct : (( rand("[:punct:]", 10) ))
alnum : (( rand("[:alnum:]", 10) ))

оценивает

 int : 8037669378456096839
int10 : 7
neg10 : -5
bool : true
string : ghhjAYPMlD
upper : LBZQFRSURL
alnum : 0p6KS7EhAj
punct : ' &{;,^])"(# '

`(( type(foobar) ))`

type функции дает строку, обозначающую тип данного выражения.

например:

 template :
  << : (( &template ))
  
types :
  - int : (( type(1) ))
  - float : (( type(1.0) ))
  - bool : (( type(true) ))
  - string : (( type("foobar") ))
  - list :   (( type([]) ))
  - map :    (( type({}) ))
  - lambda : (( type(|x|->x) ))
  - template : (( type(.template) ))
  - nil : (( type(~) ))
  - undef : (( type(~~) ))

оценивает типы

 types :
- int : int
- float : float
- bool : bool
- string : string
- list : list
- map : map
- lambda : lambda
- template : template

`(( defined(foobar) ))`

Функция defined проверяет, можно ли успешно оценить выражение. Это дает логическое значение true , если выражение может быть оценено, и false в противном случае.

например:

 zero : 0
div_ok : (( defined(1 / zero ) ))
zero_def : (( defined( zero ) ))
null_def : (( defined( null ) ))

оценивает

 zero : 0
div_ok : false
zero_def : true
null_def : false

Эта функция может использоваться в сочетании условного оператора для оценки выражений в зависимости от разрешения другого выражения.

`(( valid(foobar) ))`

Функция valid проверяет, можно ли успешно оценить выражение и оценивать определенное значение, не равное nil . Это дает логическое значение true , если выражение может быть оценено, и false в противном случае.

например:

 zero : 0
empty :
map : {}
list : []
div_ok : (( valid(1 / zero ) ))
zero_def : (( valid( zero ) ))
null_def : (( valid( ~ ) ))
empty_def : (( valid( empty ) ))
map_def : (( valid( map ) ))
list_def : (( valid( list ) ))

оценивает

 zero : 0
empty : null
map : {}
list : []
div_ok :   false
zero_def : true
null_def : false
empty_def : false
map_def :  true
list_def : true

`(( require(foobar) ))`

Функция require доходности ошибки, если заданный аргумент не определен или nil , в противном случае она дает заданное значение.

например:

 foo : ~
bob : (( foo || "default" ))
alice : (( require(foo) || "default" ))

оценивает

 foo : ~
bob : ~
alice : default

`(( stub(foo.bar) ))`

Функциональная stub дает значение выделенного поля, обнаруженного в первом восходящем заглушке, определяющем его.

например:

Шаблон.yml

 value : (( stub(foo.bar) ))

объединился с заглушкой

stub.yml

 foo :
  bar : foobar

оценивает

 value : foobar

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

Обратите внимание, что заданная единственная ссылка не будет оцениваться в качестве выражения, если его значение следует использовать, она должна быть преобразована в выражение, например, обозначая (ref) или [] ref для выражения списка.

В качестве альтернативы можно использовать операцию merge , например, merge foo.bar . Разница состоит в том, что stub не сливается, поэтому поле все равно будет объединено (с исходным путем в документе).

`(( tagdef("tag", value) ))`

Функция tagdef может использоваться для определения динамических тегов (см. Теги). В отличие от маркера тега эта функция позволяет указать имя тега и его предполагаемое значение выражением. Следовательно, его можно использовать в составлении элементов, таких как map или sum для создания динамического тега с расчетными значениями.

Необязательный третий аргумент может быть использован для указания предполагаемой области ( local или global ). По умолчанию создается локальный тег. Локальные теги видны только на фактическом уровне обработки (шаблон или суб), в то время как глобальные теги, после определения, могут использоваться на всех дальнейших уровнях обработки (заглушка или шаблон).

В качестве альтернативы имя тега можно префикс с началом ( * ) для объявления глобального тега.

Указанное значение тега будет использоваться в качестве результата для функции.

например:

Шаблон.yml

 value : (( tagdef("tag:alice", 25) ))
alice : (( tag:alice::. ))

оценивает

 value : 25
alice : 25

`(( eval(foo "." bar ) ))`

Оцените результат оценки выражения строки снова как динамическое выражение. Это, например, можно использовать для реализации костюмов.

Например: выражение в

 alice :
  bob : married

foo : alice
bar : bob

status : (( eval( foo "." bar ) ))

Вычисляет путь к поле, который затем снова оценивается, чтобы получить значение этого составленного поля:

 alice :
  bob : married

foo : alice
bar : bob

status : married

`(( env("HOME" ) ))`

Прочитайте значение переменной среды, имя которой дано как динамическое выражение. Если переменная среды не установлена, оценка не удается.

Во втором аромате функция env принимает несколько аргументов и/или аргументов списка, которые соединены с одним списком. Каждая запись в этом списке используется в качестве имени переменной среды, а результатом функции является карта заданных переменных в качестве элемента YAML. Настоящим не существующие переменные среды опущены.

`(( parse(yamlorjson) ))`

Разрабатывайте строку YAML или JSON и верните контент как значение YAML. Поэтому его можно использовать для дальнейшей оценки динамики.

например:

 json : |
   { "alice": 25 }
result : (( parse( json ).alice ))

дает значение 25 для result поля.

Функциональный parse поддерживает дополнительный второй аргумент, режим Parse . Здесь возможны те же режимы, что и для функции чтения. Режим анализа по умолчанию является import , контент просто анализируется, и на этом этапе нет дальнейшей оценки.

`(( asjson(expr) ))`

Эта функция преобразует значение YAML, данное его аргументом в строку JSON . Соответствующая функция asyaml дает значение YAML в качестве строки документа YAML .

например:

 data :
  alice : 25

mapped :
  json : (( asjson(.data) ))
  yaml : (( asyaml(.data) ))

решает

 data :
  alice : 25

mapped :
  json : ' {"alice":25} '
  yaml : |+
    alice: 25

`(( catch(expr) ))`

Эта функция выполняет выражение и дает некоторую карту информации о оценке. Это всегда удается, даже если выражение не удается. Карта включает в себя следующие поля:

имя	тип	значение
`valid`	логическое значение	Выражение верно
`error`	нить	текст сообщения об ошибке оценки
`value`	любой	ценность выражения, если оценка была успешной

например:

 data :
  fail : (( catch(1 / 0) ))
  valid : (( catch( 5 * 5) ))

решает

 data :
  fail :
    error : division by zero
    valid : false
  valid :
    error : " "
    valid : true
    value : 25

`(( static_ips(0, 1, 3) ))`

Создайте список статических IPS для работы.

например:

 jobs :
  - name : myjob
    instances : 2
    networks :
    - name : mynetwork
      static_ips : (( static_ips(0, 3, 4) ))

Это создаст 3 IP из подсети mynetwork и вернет две записи, так как есть только два экземпляра. Две записи будут 0 -е и 3 -е смещения из статических диапазонов IP, определенных сетью.

Например, с учетом файла bye.yml :

 networks : (( merge ))

jobs :
  - name : myjob
    instances : 3
    networks :
    - name : cf1
      static_ips : (( static_ips(0,3,60) ))

и файл hi.yml :

 networks :
- name : cf1
  subnets :
  - cloud_properties :
      security_groups :
      - cf-0-vpc-c461c7a1
      subnet : subnet-e845bab1
    dns :
    - 10.60.3.2
    gateway : 10.60.3.1
    name : default_unused
    range : 10.60.3.0/24
    reserved :
    - 10.60.3.2 - 10.60.3.9
    static :
    - 10.60.3.10 - 10.60.3.70
  type : manual

 spiff merge bye.yml hi.yml

возвращает

 jobs :
- instances : 3
  name : myjob
  networks :
  - name : cf1
    static_ips :
    - 10.60.3.10
    - 10.60.3.13
    - 10.60.3.70
networks :
- name : cf1
  subnets :
  - cloud_properties :
      security_groups :
      - cf-0-vpc-c461c7a1
      subnet : subnet-e845bab1
    dns :
    - 10.60.3.2
    gateway : 10.60.3.1
    name : default_unused
    range : 10.60.3.0/24
    reserved :
    - 10.60.3.2 - 10.60.3.9
    static :
    - 10.60.3.10 - 10.60.3.70
  type : manual

Если пока .

 networks : (( merge ))

jobs :
  - name : myjob
    instances : 2
    networks :
    - name : cf1
      static_ips : (( static_ips(0,3,60) ))

 spiff merge bye.yml hi.yml

Вместо этого возвращается

 jobs :
- instances : 2
  name : myjob
  networks :
  - name : cf1
    static_ips :
    - 10.60.3.10
    - 10.60.3.13
networks :
- name : cf1
  subnets :
  - cloud_properties :
      security_groups :
      - cf-0-vpc-c461c7a1
      subnet : subnet-e845bab1
    dns :
    - 10.60.3.2
    gateway : 10.60.3.1
    name : default_unused
    range : 10.60.3.0/24
    reserved :
    - 10.60.3.2 - 10.60.3.9
    static :
    - 10.60.3.10 - 10.60.3.70
  type : manual

static_ips также принимает аргументы списка, если все транзитивируемые элементы снова являются либо списками, либо целочисленными значениями. Это позволяет сократить список IPS следующим образом:

  static_ips: (( static_ips([1..5]) ))

`(( ipset(ranges, 3, 3,4,5,6) ))`

В то время как функция static_ips по историческим причинам опирается на структуру манифеста Bosh и работает только в выделенных местах в манифесте, функция IPSet предлагает аналогичный расчет, исключительно на основе его аргументов. Таким образом, доступные IP -диапазоны и необходимые номера IPS передаются в качестве аргументов.

Первым (диапазоном) аргумент может быть единственным диапазоном в качестве простой строки или списка строк. Каждая строка может быть

один IP -адрес
Явный диапазон IP, описанный двумя IP-адресами, разделенными приборной (-)
CIDR

Второй аргумент определяет запрошенное количество IP -адресов в наборе результатов.

Дополнительные аргументы указывают индексы IPS для выбора (начиная с 0) в заданных диапазонах. Здесь можно использовать списки индексов.

например:

 ranges :
  - 10.0.0.0 - 10.0.0.255
  - 10.0.2.0/24
ipset : (( ipset(ranges,3,[256..260]) ))

Разрешает IPSet до [ 10.0.2.0, 10.0.2.1, 10.0.2.2 ] .

Если не указаны индексы IP (только два аргумента), IPS выбираются, начиная с начала первого диапазона до конца последнего данного диапазона, без индекции.

`(( list_to_map(list, "key") ))`

Список записей карты с явным именем/полями ключей будет сопоставлен с картой с выделенными ключами. По умолчанию используется name поля ключа, которое может измениться дополнительным вторым аргументом. Явно обозначенное поле ключа в списке также будет принято во внимание.

например:

 list :
  - key:foo : alice
    age : 24
  - foo : bob
    age : 30

map : (( list_to_map(list) ))

будет нанести на карту

 list :
  - foo : alice
    age : 24
  - foo : bob
    age : 30

map :
  alice :
    age : 24
  bob :
    age : 30

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

`(( makemap(fieldlist) ))`

В этом аромате makemap создает карту с записями, описанными в данном полевом списке. Ожидается, что список будет содержать карты с key и value записей, описывая выделенные записи карты.

например:

 list :
  - key : alice
    value : 24
  - key : bob
    value : 25
  - key : 5
    value : 25

map : (( makemap(list) ))

урожайность

 list :
  - key : alice
    value : 24
  - key : bob
    value : 25
  - key : 5
    value : 25

map :
  " 5 " : 25
  alice : 24
  bob : 25

Если значение ключа является логическим или целым числом, оно будет сопоставлено с строкой.

`(( makemap(key, value) ))`

В этом аромате makemap создает карту с записями, описанными данными парами аргументов. Аргументы могут быть последовательностью паров ключей/значений (заданные отдельными аргументами).

например:

 map : (( makemap("peter", 23, "paul", 22) ))

урожайность

 map :
  paul : 22
  peter : 23

В отличие от предыдущего вкуса makemap , с этим также можно обрабатывать литералы MAP.

`(( merge(map1, map2) ))`

Помимо merge ключевого слова, есть также функция, называемая merge (за ней всегда следует начальный кронштейн). Он может быть использован для объединения карт севералов, взятых из фактического документа, аналогичного процессу слияния заглушки. Если карты указываются с помощью эталонных выражений, они не могут содержать каких -либо динамических выражений, поскольку они всегда оцениваются в контексте фактического документа, прежде чем оценивать аргументы.

например:

 map1 :
  alice : 24
  bob : (( alice ))
map2 :
  alice : 26
  peter : 8
result : (( merge(map1,map2) ))

разрешает result

 result :
  alice : 26
  bob : 24  # <---- expression evaluated before mergeing

В качестве альтернативы шаблоны карт могут быть переданы (без оператора оценки!). В этом случае динамические выражения из шаблона оцениваются при объединении данных документов как для регулярных вызовов слияния Spiff .

например:

 map1 :
  << : (( &template ))
  alice : 24
  bob : (( alice ))
map2 :
  alice : 26
  peter : 8
result : (( merge(map1,map2) ))

разрешает result

 result :
  alice : 26
  bob : 26

Карта также может быть дана выражением карты. Здесь можно указать динамические выражения с использованием обычного синтаксиса:

например:

 map1 :
  alice : 24
  bob : 25

map2 :
  alice : 26
  peter : 8

result : (( merge(map1, map2, { "bob"="(( carl ))", "carl"=100 }) ))

разрешает result

 result :
  alice : 26
  bob : 100

Вместо нескольких аргументов может быть дан аргумент одного списка. Список должен содержать карты, которые должны быть объединены.

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

например:

 data :
  alice :
    age : 24

template :
  << : (( &template ))
  bob :  25
  outer1 : (( __ctx.OUTER.[0].data )) # absolute access to outer context
  outer2 : (( data.alice.age ))       # relative access to outer binding
  sum : (( .bob + .outer2 ))

merged : (( merge(template) ))

разрешает merged

 merged :
  bob : 25
  outer1 :
    alice :
      age : 24
  outer2 : 24
  sum : 49

`(( intersect(list1, list2) ))`

Функция intersect пересечение нескольких списков. Список может содержать записи любого типа.

например:

 list1 :
- - a
- - b
- a
- b
- { a: b }
- { b: c }
- 0
- 1
- " 0 "
- " 1 "
list2 :
- - a
- - c
- a
- c
- { a: b }
- { b: b }
- 0
- 2
- " 0 "
- " 2 "
intersect : (( intersect(list1, list2) ))

разрешает intersect

 intersect :
- - a
- a
- { a: b }
- 0
- " 0 "

`(( reverse(list) ))`

Функция reverse изменяет порядок списка. Список может содержать записи любого типа.

например:

 list :
- - a
- b
- { a: b }
- { b: c }
- 0
- 1
reverse : (( reverse(list) ))

Решает reverse к

 reverse :
- 1
- 0
- { b: c }
- { a: b }
- b
- - a

`(( validate(value,"dnsdomain") ))`

Функция validate проверяет выражение с использованием набора валидаторов. Первый аргумент - это значение для проверки, и все другие аргументы являются валидаторами, которые должны принять это значение. Если по крайней мере один валидатор не выполняет сгенерированное сообщение об ошибке, которое объясняет причину неудачи.

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

Доступны следующие валидаторы:

Тип	Аргументы	Значение
`empty`	никто	пустой список, карта или строка
`dnsdomain`	никто	DNS доменное имя
`wildcarddnsdomain`	никто	доменное имя подстановочного знака
`dnslabel`	никто	DNS Label
`dnsname`	никто	DNS -домен или домен для подстановочного знака
`ip`	никто	IP-адрес
`cidr`	никто	сидр
`publickey`	никто	открытый ключ в формате PEM
`privatekey`	никто	Частный ключ в формате PEM
`certificate`	никто	Сертификат в формате PEM
`ca`	никто	Сертификат для CA
`semver`	Необязательный список ограничений	проверить версию SEMVER против ограничений
`type`	Список принятых ключей типа	По крайней мере, один ключ типа должен соответствовать
`valueset`	Перечислите аргумент со значениями	возможные значения
`value` или `=`	ценить	Проверьте выделенное значение
`gt` или `>`	ценить	больше, чем (число/строка)
`lt` или `<`	ценить	меньше, чем (число/строка)
`ge` или `>=`	ценить	больше или равен (число/строка)
`le` или `<=`	ценить	меньше или равно (число/строка)
`match` или `~=`	регулярное выражение	Сопоставление строковых значений регулярное выражение
`list`	Необязательный список валидаторов записи	Список и записи совпадают с данными валидаторов
`map`	[[<wardator>,] <intpirt valyator>]	Карта и ключи и записи соответствуют данным валидаторам
`mapfield`	<имя поля> [, <validator>]	Требуется запись в карте
`optionalfield`	<имя поля> [, <validator>]	Дополнительная запись в карте
`and`	Список валидаторов	Все валидаторы должны добиться успеха
`or`	Список валидаторов	По крайней мере, один валидатор должен добиться успеха
`not` или `!`	валидатор	отрицайте аргумент валидатора (ы)

Если проверка успешна, значение возвращается.

например:

 dnstarget : (( validate("192.168.42.42", [ "or", "ip", "dnsdomain" ]) ))

оценивает

 dnstarget : 192.168.42.42

Если проверка не выполняет ошибку, объясняющая причину сбоя.

например:

 dnstarget : (( validate("alice+bob", [ "or", "ip", "dnsdomain" ]) ))

дает следующую ошибку:

 *condition 1 failed: (is no ip address: alice+bob and is no dns domain: [a DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')])

Валидатор также может быть выражением Lambda, принимающего по крайней мере один аргумент и возвращает логическое значение. Таким образом, можно предоставить собственные валидаторы в рамках документа YAML.

например:

 val : (( validate( 0, |x|-> x > 1 ) ))

Если объявлено более одного параметра, дополнительные аргументы должны быть указаны как аргументы валидатора. Первый аргумент - это всегда значение для проверки.

например:

 val : (( validate( 0, [|x,m|-> x > m, 5] ) ))

Функция Lambda может вернуть список с 1, 2 или 3 элементами. Это может быть использовано для предоставления соответствующих сообщений.

Индекс	Значение
0	Первый индекс всегда является результатом соответствия, он должен быть оценен как логический
1	Если даны два элемента, второй индекс - это сообщение, описывающее фактический результат
2	Здесь индекс 1 уменьшает сообщение об успехе и 2 сообщение об отказе

например:

 val : (( validate( 6, [|x,m|-> [x > m, "is larger than " m, "is less than or equal to " m], 5] ) ))

Просто чтобы упомянуть, спецификация валидатора может быть дана встроенная, как показано в приведенных выше примерах, но также в качестве эталонных выражений. not , and or валидаторы принимают глубоко вложенные спецификации валидатора.

например:

 dnsrecords :
   domain : 1.2.3.4
validator :
  - map
  - - or                              # key validator
    - dnsdomain
    - wildcarddnsdomain
  - ip                                # entry validator

val : (( validate( map, validator)  ))

`(( check(value,"dnsdomain") ))`

check функции может использоваться для сопоставления структуры YAML с проверкой значений на основе YAML. Настоящим может использоваться то же описание проверки, которое уже описано для проверки. Результатом вызова является логическое значение, указывающее на результат совпадения. Он не сбой, если проверка не удается.

`(( error("message") ))`

error функции может быть использована, чтобы вызвать явные сбои оценки с выделенным сообщением.

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

например:

 value : (( <some complex potentially failing expression> || error("this was an error my friend") ))

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

Математика

Dynaml поддерживает различные математические функции:

Возвращающиеся целые числа: ceil , floor , round и roundtoeven

Возвращение поплавков или целых чисел: abs

Возвращающиеся поплавки: sin , cos , sinh , cosh , asin , acos , asinh , acosh , sqrt , exp , log , log10 ,

Конверсии

Dynaml поддерживает различные преобразования типа между integer , float , bool и string значениями по соответствующим функциям.

например:

 value : (( integer("5") ))

Преобразует строку в целочисленное значение.

Преобразование целого числа в строку принимает дополнительный дополнительный аргумент целого числа для определения базы для преобразования, например, string(55,2) приведет к "110111" . База по умолчанию составляет 10. База должна быть от 2 до 36.

Доступ к внешнему контенту

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

Кэшированный вкус выполняет операцию и кэширует результат для последующих идентичных операций. Это ускоряет обработку, особенно для выполнения команд.
Если результат развивается со временем, может быть полезно всегда получить последний контент. Это имеет место, если используется функция sync , которая предназначена для синхронизации обработки шаблона с использованием состояния посвященного (предоставленного внешним контентом). Здесь операции кэширования не будут полезны, поэтому существует второй Uncached Alura. Каждая функция доступна с суффиксом _uncached (например, read_uncached() )

`(( read("file.yml") ))`

Прочитайте файл и верните его контент. Существует поддержка трех типов контента: файлы yaml , text файлы и binary файлы. Чтение в двоичном режиме приведет к кодируемой многострочной строке BASE64.

.yml суффикс .json .yaml Если файл следует читать как text , этот тип должен быть явно указан. Во всех остальных случаях по умолчанию является text , поэтому срочно прочитать двоичный файл (например, архив), требуется указание binary режима.

Необходимый второй параметр может быть использован для явного определения желаемого типа возврата: yaml или text . Для документов YAML поддерживаются некоторые типы добавок: multiyaml , template , templates , import и importmulti .

Ямл документы

Документ YAML будет проанализирован, а дерево возвращено. Элементы дерева можно получить с помощью регулярных динамических выражений.

Кроме того, файл YAML может снова содержать динамические выражения. Все включенные динамические выражения будут оцениваться в контексте выражения чтения. Это означает, что один и тот же файл, включенный в разные места в документе YAML, может привести к различным подвесам, в зависимости от использованных выражений Dynaml.

Если возможно прочитать многодокумент Yaml, также. Если дается тип multiyaml , возвращается узел списка с корневыми узлами документа YAML.

Документ YAML или JSON также может читать как шаблон , указав template типа. Здесь результатом будет значение шаблона, которое можно использовать как регулярные встроенные шаблоны. Если указаны templates , многодокумент отображается в список шаблонов.

Если тип чтения установлен на import , содержимое файла читается как документ YAML, а корневой узел используется для замены выражения. Потенциальные выражения динамики, содержащиеся в документе, не будут оцениваться с фактическим связыванием выражения вместе с вызовом чтения, но, как это было бы частью исходного файла. Следовательно, этот режим может использоваться, только если нет дальнейшей обработки результата чтения или доставленных значений необработаны.

Это может использоваться вместе с цепью ссылкой (для экзамена (( read(...).selection )) ) для принятия выделенного фрагмента импортированного документа. Затем оценка будет выполнена только для выбранной части. Выражения и ссылки в других частях не оценены и вообще не могут привести к ошибке.

например:

Шаблон.yaml

 ages :
  alice : 25

data : (( read("import.yaml", "import").first ))

Import.yaml

 first :
  age : (( ages.alice ))

second :
  age : (( ages.bob ))

не потерпит неудачу, потому что second раздел никогда не оценивается.

Этот режим должен быть принят с осторожностью, потому что он часто приводит к неожиданным результатам.

importmulti типа чтения может использоваться для импорта файлов многодокументов YAML в качестве списка узлов.

текстовые документы

Текстовый документ будет возвращен в качестве отдельной строки.

бинарные документы

Также можно читать двоичные документы. Контент не может быть использован в качестве строки (или документа YAML), напрямую. Поэтому должен быть указан binary режима чтения. Содержание возвращается в виде кодируемого многострочного строкового значения BASE64.

`(( exec("command", arg1, arg2) ))`

Выполнить команду. Аргументы могут быть любыми динамическими выражениями, включая эталонные выражения, оцениваемые на списки или карты. Списки или карты передаются в виде отдельных аргументов, содержащих документ YAML с данным фрагментом.

Результат определяется путем анализа стандартного вывода команды. Это может быть документ YAML или одна многострочная строка или целочисленное значение. Документ YAML должен начинаться с префикса документа --- . Если команда не удается, выражение обрабатывается как неопределенное.

например

 arg :
  - a
  - b
list : (( exec( "echo", arg ) ))
string : (( exec( "echo", arg.[0] ) ))

урожайность

 arg :
- a
- b
list :
- a
- b
string : a

В качестве альтернативы exec можно вызвать с помощью одного аргумента списка, полностью описывающего командную строку.

Та же команда будет выполнена только один раз, даже если она используется в нескольких выражениях.

`(( pipe(data, "command", arg1, arg2) ))`

Выполните команду и подайте его стандартный ввод специальными данными. Аргумент команды должен быть строкой. Аргументы для команды могут быть любыми динамическими выражениями, включая эталонные выражения, оцениваемые на списки или карты. Списки или карты передаются в виде отдельных аргументов, содержащих документ YAML с данным фрагментом.

Входной поток генерируется из данных данных. Если это простой тип, его строковое представление используется. В противном случае документ YAML генерируется из входных данных. Результат определяется путем анализа стандартного вывода команды. Это может быть документ YAML или одна многострочная строка или целочисленное значение. Документ YAML должен начинаться с префикса документа --- . Если команда не удается, выражение обрабатывается как неопределенное.

например

 data :
  - a
  - b
list : (( pipe( data, "tr", "a", "z") ))

урожайность

 arg :
- a
- b
list :
- z
- b

В качестве альтернативы можно pipe с помощью данных и аргумента списка, полностью описывающего командную строку.

Та же команда будет выполнена только один раз, даже если она используется в нескольких выражениях.

`(( write("file.yml", data) ))`

Запишите файл и верните его контент. Если результат может быть проанализирован как документ YAML, документ возвращается. Дополнительный 3 -й аргумент может использоваться для прохождения параметров записи. Аргументы опции могут быть целочисленными разрешениями, обозначающими файл (по умолчанию 0644 ) или разделенной запятой строкой с параметрами. Поддерживаемые варианты

binary : данные декодируются базой 64 перед написанием
Интеллектуальная строка: разрешения на файл, ведущий 0 указывает восьмидесятничество.

`(( tempfile("file.yml", data) ))`

Напишите временный файл AA и верните его имя пути. Дополнительный 3 -й аргумент может использоваться для прохождения параметров записи. Это в основном ведет себя как write

Внимание : временный файл существует только во время обработки слияния. Это будет удалено впоследствии.

Например, его можно использовать, чтобы предоставить временный аргумент файла для функции exec .

`(( lookup_file("file.yml", list) ))`

Поиск. Файл - это список каталогов. Результатом является список существующих файлов. Вместо этого с lookup_dir можно найти каталог.

Если существующие файлы не могут быть найдены, пустой список возвращается.

Можно пройти несколько аргументов в список или строковых аргументов, чтобы составить путь поиска.

`(( mkdir("dir", 0755) ))`

Создайте каталог и все его промежуточные каталоги, если они еще не существуют.

Часть разрешения является необязательной (по умолчанию 0755). Путь каталога может быть указан путем приоритетного значения или в виде списка компонентов пути.

`(( list_files(".") ))`

Список файлов в каталоге. Результатом является список существующих файлов. С list_dirs можно перечислить каталоги, вместо этого.

`(( archive(files, "tar") ))`

Создайте архив данного типа (по умолчанию tar ), содержащий перечисленные файлы. Результатом является кодированный архив BASE64.

Поддерживаемые типы архивов - это tar и targz .

files могут быть списком или картой записей файлов. В случае карты клавиша карты используется в качестве по умолчанию для пути файла. Запись файла - это карта со следующими полями:

поле	тип	значение
`path`	нить	Необязательно для карт, путь файла в архиве, не выполненный по умолчанию ключом карты
`mode`	int или int String	Режим файла или параметры записи. Это в основном ведет себя как опционный аргумент для `write` .
`data`	любой	Содержание файла, YAML будет маршал как документ YAML. Если `mode` показывает двоичный режим, строковое значение будет декодировано.
`base64`	нить	Base64, кодированные бинарные данные

например:

 yaml :
  alice : 26
  bob : 27

files :
  " data/a/test.yaml " :
    data : (( yaml ))
  " data/b/README.md " :
    data : |+
      ### Test Docu

      **Note**: This is a test

archive : (( archive(files,"targz") ))

content : (( split("n", exec_uncached("tar", "-tvf", tempfile(archive,"binary"))) ))

Доходность:

 archive : |-
  H4sIAAAAAAAA/+zVsQqDMBAG4Mx5igO3gHqJSQS3go7tUHyBqIEKitDEoW9f
  dLRDh6KlJd/yb8ll+HOd8SY1qbfOJw8zDmQHiIhayjURcZuIQhOeSZlphVwL
  glwsAXvM8mJ23twJ4qfnbB/3I+I4pmboW1uA0LSZmgJETr89VXCUtf9Neq1O
  5blKxm6PO972X/FN/7nKVej/EaIogto6D+XUzpQydpm8ZayA+tY76B0YWHYD
  DV9CEATBf3kGAAD//5NlAmIADAAA
content :
- -rw-r--r-- 0/0              22 2019-03-18 09:01 data/a/test.yaml
- -rw-r--r-- 0/0              41 2019-03-18 09:01 data/b/README.md

files :
  data/a/test.yaml :
    data :
      alice : 26
      bob : 27
  data/b/README.md :
    data : |+
      ### Test Docu

      **Note**: This is a test

yaml :
  alice : 26
  bob : 27

Функции семантической версии

Spiff поддерживает обработку семантических имен версий. Он поддерживает все функциональные возможности из пакета Masterminds Semver, принимающего версии с или без ведущего v

`(( semver("v1.2-beta.1") ))`

Проверьте, является ли данная строка семантической версией, и верните его нормализованную форму (без лидирования v и полной части выпуска с номером Major, Minor и и Patch версии).

например:

 normalized : (( semver("v1.2-beta.1") ))

решает

 normalized : 1.2.0-beta.1

`(( semverrelease("v1.2.3-beta.1") ))`

Верните релиз части семантической версии, пропущенной метаданной и предварительной информацией.

например:

 release : (( semverrelease("v1.2.3-beta.1") ))

решает

 release : v1.2.3

Если дополнительный строковый аргумент дается, эта функция заменяет выпуск путем выпуска заданных семантических метаданных и предварительной информации.

например:

 new : (( semverrelease("1.2.3-beta.1", "1.2.1) ))

решает

 new : 1.2.1-beta.1

`(( semvermajor("1.2.3-beta.1") ))`

Определите основной номер версии данной семантической версии. Результат - целое число.

например:

 major : (( semvermajor("1.2.3-beta.1") ))

решает

 major : 1

Функция semverincmajor может использоваться для увеличения основного номера версии и сброса незначительной версии, патч версии и выпуска суффиксов.

например:

 new : (( semverincmajor("1.2.3-beta.1") ))

решает

 new : 2.0.0

`(( semverminor("1.2.3-beta.1") ))`

Определите второстепенный номер версии данной семантической версии. Результат - целое число.

например:

 minor : (( semverminor("1.2.3-beta.1") ))

решает

 minor : 2

Функция semverincminor может использоваться для увеличения незначительного номера версии и сброса версии и выпуска суффиксов.

например:

 new : (( semverincmajor("v1.2.3-beta.1") ))

решает

 new : v1.3.0

`(( semverpatch("1.2.3-beta.1") ))`

Определите номер версии патчей данной семантической версии. Результат - целое число.

например:

 patch : (( semverpatch("1.2.3-beta.1") ))

решает

 patch : 3

Функция semverincpatch может использоваться для увеличения номера версии патча или сброса суффиксов выпуска. Если есть суффиксы Rlease, они удаляются, а информация о выпуске остается неизменной, в противном случае номер версии патча увеличивается.

например:

 final : (( semverincpatch("1.2.3-beta.1") ))
new : (( semverincpatch(final) ))

решает

 final : 1.2.3
new : 1.2.4

`(( semverprerelease("1.2.3-beta.1") ))`

Определите предварительную сферу данной семантической версии. Результат - строка.

например:

 prerelease : (( semverprerelease("1.2.3-beta.1") ))

решает

 prerelease : beta.1

Если дополнительный аргумент строки дается эти наборы функций, заменяет или очищает (если установить на пустую строку) предварительный срок

например:

 new : (( semverprerelease("1.2.3-beta.1", "beta.2) ))

решает

 new : 1.2.3-beta.2

`(( semvermetadata("1.2.3+demo") ))`

Определите метаданные данной семантической версии. Результат - строка.

например:

 metadata : (( semvermetadata("1.2.3+demo") ))

решает

 metadata : demo

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

например:

 new : (( semvermetadata("1.2.3-test", "demo) ))

решает

 new : 1.2.3+demo

`(( semvercmp("1.2.3", 1.2.3-beta.1") ))`

Сравните две семантические версии. Пререзелис всегда меньше, чем финальный релиз. Результатом является целое число со следующими значениями:

результат	значение
-1	Первая версия перед второй версией
0	Обе версии равны
1	Первый Versuon после второго

например:

 compare : (( semvercmp("1.2.3", "1.2.3-beta.1") ))

решает

 compare : 1

`(( semvermatch("1.2.3", "~1.2") ))`

Сопоставьте данную семантическую версию против списка противореем. Результат - логический. Можно указать любое количество ограничений версий. Если не указано ограничение, функция просто проверяет, является ли данная строка семантической версией.

например:

 match : (( semvermatch("1.2.3", "~1.2") ))

решает

 match : true

Полный список возможных ограничений можно найти здесь.

`(( semversort("1.2.3", "1.2.1") ))`

Сортируйте список версий в порядке возрастания. Ведущий v сохраняется.

например:

 sorted : (( semversort("1.2.3", "1.2.1") ))

решает

 sorted :
  - 1.2.1
  - 1.2.3

Список версий, которые будут отсортированы, также может быть указан с помощью одного списка аргумента.

X509 функции

Spiff поддерживает некоторые полезные функции для работы с сертификатами X509 и ключами. Пожалуйста, обратитесь в раздел «Полезный, чтобы узнать», чтобы найти несколько советов по обеспечению состояния.

`(( x509genkey(spec) ))`

Эту функцию можно использовать генерировать частные клавиши RSA или ECDSA. Результатом будет кодированный ключ PEM в качестве значения строки. Если размер ключа (целое число или строка) дано в качестве аргумента, ключ RSA будет генерироваться с данным размером ключа (например, 2048). Учитывая одно из строковых значений

"P224"
"P256"
"P384"
"P521"

Функция генерирует соответствующий ключ ECDSA.

например:

 keys :
  key : (( x509genkey(2048) ))

решает что -то вроде

 key : |+
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEAwxdZDfzxqz4hlRwTL060pm1J12mkJlXF0VnqpQjpnRTq0rns
    CxMxvSfb4crmWg6BRaI1cEN/zmNcT2sO+RZ4jIOZ2Vi8ujqcbzxqyoBQuMNwdb32
    ...
    oqMC9QKBgQDEVP7FDuJEnCpzqddiXTC+8NsC+1+2/fk+ypj2qXMxcNiNG1Az95YE
    gRXbnghNU7RUajILoimAHPItqeeskd69oB77gig4bWwrzkijFXv0dOjDhQlmKY6c
    pNWsImF7CNhjTP7L27LKk49a+IGutyYLnXmrlarcNYeCQBin1meydA==
    -----END RSA PRIVATE KEY-----

`(( x509publickey(key) ))`

Для заданного ключа или сертификата в формате PEM (например, сгенерированный с функцией x509GenKey) эта функция извлекает открытый ключ и возвращает его в формате PEM в качестве многострочной строки.

например:

 keys :
  key : (( x509genkey(2048) ))
  public : (( x509publickey(key)

решает что -то вроде

 key : |+
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEAwxdZDfzxqz4hlRwTL060pm1J12mkJlXF0VnqpQjpnRTq0rns
    CxMxvSfb4crmWg6BRaI1cEN/zmNcT2sO+RZ4jIOZ2Vi8ujqcbzxqyoBQuMNwdb32
    ...
    oqMC9QKBgQDEVP7FDuJEnCpzqddiXTC+8NsC+1+2/fk+ypj2qXMxcNiNG1Az95YE
    gRXbnghNU7RUajILoimAHPItqeeskd69oB77gig4bWwrzkijFXv0dOjDhQlmKY6c
    pNWsImF7CNhjTP7L27LKk49a+IGutyYLnXmrlarcNYeCQBin1meydA==
    -----END RSA PRIVATE KEY-----
public : |+
    -----BEGIN RSA PUBLIC KEY-----
    MIIBCgKCAQEAwxdZDfzxqz4hlRwTL060pm1J12mkJlXF0VnqpQjpnRTq0rnsCxMx
    vSfb4crmWg6BRaI1cEN/zmNcT2sO+RZ4jIOZ2Vi8ujqcbzxqyoBQuMNwdb325Bf/
   ...
    VzYqyeQyvvRbNe73BXc5temCaQayzsbghkoWK+Wrc33yLsvpeVQBcB93Xhus+Lt1
    1lxsoIrQf/HBsiu/5Q3M8L6klxeAUcDbYwIDAQAB
    -----END RSA PUBLIC KEY-----

Чтобы сгенерировать открытый ключ SSH, необязательный дополнительный аргумент формата может быть установлен на ssh . Результат будет тогда обычным форматом открытого ключа, используемого для SSH. Формат по умолчанию - это pem предоставляющий формат вывода PEM, показанный выше.

Ключи RSA по умолчанию в формате PKCS#1 ( RSA PUBLIC KEY ) в PKCS#1. Если требуется общий формат PKIX ( PUBLIC KEY ), должен быть указан аргумент формата pkix .

Использование формата ssh Эта функция также может быть использована для преобразования открытого ключа PEM в ключ SSH,

`(( x509cert(spec) ))`

Функция x509cert создает локально подписанные сертификаты, либо сами подписанный, либо сертификат, подписанный данным CA. Он возвращает кодированный сертификат PEM в качестве многострочного строкового значения.

Один параметр спецификации принимает карту с некоторыми необязательными и не дополнительными полями, используемыми для указания информации о сертификате. Это может быть встроенное выражение карты или любая ссылка на карту в остальную часть документа YAML.

Наблюдаются следующие поля карты:

Имя поля	Тип	Необходимый	Значение
`commonName`	нить	необязательный	Общее поле поля предмета
`organization`	Список строки или строки	необязательный	Организационная область предмета
`country`	Список строки или строки	необязательный	Страновое поле предмета
`isCA`	логическое значение	необязательный	CA опция сертификата
`usage`	Список строки или строки	необходимый	Ключи использования для сертификата (см. Ниже)
`validity`	целое число	необязательный	Интервал достоверности в часы
`validFrom`	нить	необязательный	Время начала в формате "1 января 01:22:31 2019"
`hosts`	Список строки или строки	необязательный	Список имен DNS или IP -адресов
`privateKey`	нить	Требуется или PublicKey	закрытый ключ для получения сертификата для
`publicKey`	нить	Требуется или частный	открытый ключ для получения сертификата для
`caCert`	нить	необязательный	Сертификат, чтобы подписать с
`caPrivateKey`	нить	необязательный	Priavte Key для `caCert`

Для самоотверженных сертификатов необходимо установить поле privateKey . publicKey и поля ca должны быть опущены. Если поле caCert поля дано, также требуется поле caKey . Если поле privateKey предоставляется вместе с caCert , открытый ключ для сертификата извлечен из частного ключа.

Дополнительные поля молча игнорируются.

Поддерживаются следующие ключи от использования (случай игнорируется):

Ключ	Значение
`Signature`	x509. Keyusagedigitalsignature
`Commitment`	x509. KeyusageContentCommitment
`KeyEncipherment`	x509. Keyusagekeyencipherment
`DataEncipherment`	x509. Keyusagedataencipherment
`KeyAgreement`	x509. KeyusageKeyGreement
`CertSign`	x509. Keyusagecertsign
`CRLSign`	x509. KeyusageCrlSign
`EncipherOnly`	x509. Keyusageencipheronly
`DecipherOnly`	x509. KeyusedeCipheronly
`Any`	x509.ExtkeyUsageany
`ServerAuth`	x509.extkeyusageserverauth
`ClientAuth`	x509.extkeyusageclientauth
`codesigning`	x509.ExtkeyUsageDesigning
`EmailProtection`	x509.extkeyusageemailprotection
`IPSecEndSystem`	x509.extkeyusageipsecendsystem
`IPSecTunnel`	x509.
`IPSecUser`	x509.extkeyusageipsecuser
`TimeStamping`	x509.
`OCSPSigning`	x509.extkeyusageocspsigning
`MicrosoftServerGatedCrypto`	x509.extkeyusagemicrosoftservergatedCrypto
`NetscapeServerGatedCrypto`	x509.extkeyusagenetscapeservergatedCrypto
`MicrosoftCommercialCodeSigning`	x509.extkeyusagemyrosoftcommercialCodeSigning
`MicrosoftKernelCodeSigning`	x509.extkeyusagemyrosoftkernelcodeSigning

например:

 spec :
  << : (( &local ))
  ca :
    organization : Mandelsoft
    commonName : Uwe Krueger
    privateKey : (( data.cakey ))
    isCA : true
    usage :
      - Signature
      - KeyEncipherment

data :
  cakey : (( x509genkey(2048) ))
  cacert : (( x509cert(spec.ca) ))

генерирует самозаверяющий корневой сертификат и решает что-то вроде

 cakey : |+
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEAwxdZDfzxqz4hlRwTL060pm1J12mkJlXF0VnqpQjpnRTq0rns
    CxMxvSfb4crmWg6BRaI1cEN/zmNcT2sO+RZ4jIOZ2Vi8ujqcbzxqyoBQuMNwdb32
    ...
    oqMC9QKBgQDEVP7FDuJEnCpzqddiXTC+8NsC+1+2/fk+ypj2qXMxcNiNG1Az95YE
    gRXbnghNU7RUajILoimAHPItqeeskd69oB77gig4bWwrzkijFXv0dOjDhQlmKY6c
    pNWsImF7CNhjTP7L27LKk49a+IGutyYLnXmrlarcNYeCQBin1meydA==
    -----END RSA PRIVATE KEY-----
cacert : |+
    -----BEGIN CERTIFICATE-----
    MIIDCjCCAfKgAwIBAgIQb5ex4iGfyCcOa1RvnKSkMDANBgkqhkiG9w0BAQsFADAk
    MQ8wDQYDVQQKEwZTQVAgU0UxETAPBgNVBAMTCGdhcmRlbmVyMB4XDTE4MTIzMTE0
    ...
    pOUBE3Tgim5rnpa9K9RJ/m8IVqlupcONlxQmP3cCXm/lBEREjODPRNhU11DJwDdJ
    5fd+t5SMEit2BvtTNFXLAwz48EKTxsDPdnHgiQKcbIV8NmgUNPHwXaqRMBLqssKl
    Cyvds9xGtAtmZRvYNI0=
    -----END CERTIFICATE-----

`(( x509parsecert(cert) ))`

Эта функция анализирует сертификат, приведенный в формате PEM, и возвращает карту полей:

Имя поля	Тип	Необходимый	Значение
`commonName`	нить	необязательный	Общее поле поля предмета
`organization`	Строки Список	необязательный	Организационная область предмета
`country`	Строки Список	необязательный	Страновое поле предмета
`isCA`	логическое значение	всегда	CA опция сертификата
`usage`	Строки Список	всегда	Ключи использования для сертификата (см. Ниже)
`validity`	целое число	всегда	Интервал достоверности в часы
`validFrom`	нить	всегда	Время начала в формате "1 января 01:22:31 2019"
`validUntil`	нить	всегда	Время начала в формате "1 января 01:22:31 2019"
`hosts`	Строки Список	необязательный	Список имен DNS или IP -адресов
`dnsNames`	Строки Список	необязательный	Список имен DNS
`ipAddresses`	Строки Список	необязательный	Список IP -адресов
`publicKey`	нить	всегда	открытый ключ для получения сертификата для

например:

 data :
  << : (( &temporary ))
  spec :
    commonName : test
    organization : org
    validity : 100
    isCA : true
    privateKey : (( gen.key ))
    hosts :
      - localhost
      - 127.0.0.1

    usage :
     - ServerAuth
     - ClientAuth
     - CertSign

  gen :
    key : (( x509genkey() ))
    cert : (( x509cert(spec) ))

cert : (( x509parsecert(data.gen.cert) ))

решает

 cert :
  commonName : test
  dnsNames :
  - localhost
  hosts :
  - 127.0.0.1
  - localhost
  ipAddresses :
  - 127.0.0.1
  isCA : true
  organization :
  - org
  publickey : |+
    -----BEGIN RSA PUBLIC KEY-----
    MIIBCgKCAQEA+UIZQUTa/j+WlXC394bccBTltV+Ig3+zB1l4T6Vo36pMBmU4JIkJ
    ...
    TCsrEC5ey0cCeFij2FijOJ5kmm4cK8jpkkb6fLeQhFEt1qf+QqgBw3targ3LnZQf
    uE9t5MIR2X9ycCQSDNBxcuafHSwFrVuy7wIDAQAB
    -----END RSA PUBLIC KEY-----
  usage :
  - CertSign
  - ServerAuth
  - ClientAuth
  validFrom : Mar 11 15:34:36 2019
  validUntil : Mar 15 19:34:36 2019
  validity : 99  # yepp, that's right, there has already time passed since the creation

Функции проволоки

Spiff поддерживает некоторые полезные функции для работы с ключами Wireguard . Please refer also to the Useful to Know section to find some tips for providing state.

`(( wggenkey() ))`

This function can be used generate private wireguard key. The result will base64 encoded.

например:

 keys :
  key : (( wggenkey() ))

resolves to something like

 key : WH9xNVJuSuh7sDVIyUAlmxc+woFDJg4QA6tGUVBtGns=

`(( wgpublickey(key) ))`

For a given key (for example generated with the wggenkey function) this function extracts the public key and returns it again in base64 format-

например:

 keys :
  key : (( wggenkey() ))
  public : (( wgpublickey(key)

resolves to something like

 key : WH9xNVJuSuh7sDVIyUAlmxc+woFDJg4QA6tGUVBtGns=
public : n405KfwLpfByhU9pOu0A/ENwp0njcEmmQQJvfYHHQ2M=

`(( lambda |x|->x ":" port ))`

Lambda expressions can be used to define additional anonymous functions. They can be assigned to yaml nodes as values and referenced with path expressions to call the function with approriate arguments in other dynaml expressions. For the final document they are mapped to string values.

There are two forms of lambda expressions. Пока

 lvalue : (( lambda |x|->x ":" port ))

yields a function taking one argument by directly taking the elements from the dynaml expression,

 string : " |x|->x " : " port "
lvalue : (( lambda string ))

evaluates the result of an expression to a function. The expression must evaluate to a function or string. If the expression is evaluated to a string it parses the function from the string.

Since the evaluation result of a lambda expression is a regular value, it can also be passed as argument to function calls and merged as value along stub processing.

A complete example could look like this:

 lvalue : (( lambda |x,y|->x + y ))
mod : (( lambda|x,y,m|->(lambda m)(x, y) + 3 ))
value : (( .mod(1,2, lvalue) ))

урожайность

 lvalue : lambda |x,y|->x + y
mod : lambda|x,y,m|->(lambda m)(x, y) + 3
value : 6

If a complete expression is a lambda expression the keyword lambda can be omitted.

Lambda expressions evaluate to lambda values, that are used as final values in yaml documents processed by spiff .

Note : If the final document still contains lambda values, they are transferred to a textual representation. It is not guaranteed that this representation can correctly be parsed again, if the document is re-processed by spiff . Especially for complex scoped and curried functions this is not possible.

Therefore function nodes should always be temporary or local to be available during processing or merging, but being omitted for the final document.

Positional versus Named Arguments

A typical function call uses positional arguments. Here the given arguments satisfy the declared function parameters in the given order. For lambda values it is also possible to use named arguments in the call expression. Here an argument is assigned to a dedicated parameter as declared by the lambda expression. The order of named arguments can be arbitrarily chosen.

например:

 func : (( |a,b,c|->{$a=a, $b=b, $c=c } ))
result : (( .func(c=1, b=2, a=1) ))

It is also posible to combine named with positional arguments. Hereby the positional arguments must follow the named ones.

например:

 func : (( |a,b,c|->{$a=a, $b=b, $c=c } ))
result : (( .func(c=1, 1, 2) ))

The same argument MUST NOT be satified by both, a named and a positional argument.

Instead of using the parameter name it is also possible to use the parameter index, instead.

например:

 func : (( |a,b,c|->{$a=a, $b=b, $c=c } ))
result : (( .func(3=1, 1) ))

As such, this feature seems to be quite useless, but it shows its power if combined with optional parameters or currying as shown in the next paragraphs.

Scopes and Lambda Expressions

A lambda expression might refer to absolute or relative nodes of the actual yaml document of the call. Relative references are evaluated in the context of the function call. Поэтому

 lvalue : (( lambda |x,y|->x + y + offset ))
offset : 0
values :
  offset : 3
  value : (( .lvalue(1,2) ))

yields 6 for values.value .

Besides the specified parameters, there is an implicit name ( _ ), that can be used to refer to the function itself. It can be used to define self recursive function. Together with the logical and conditional operators a fibunacci function can be defined:

 fibonacci : (( lambda |x|-> x <= 0 ? 0 :x == 1 ? 1 :_(x - 2) + _( x - 1 ) ))
value : (( .fibonacci(5) ))

yields the value 8 for the value property.

By default reference expressions in a lambda expression are evaluated in the static scope of the lambda dedinition followed by the static yaml scope of the caller. Absolute references are always evalated in the document scope of the caller.

The name _ can also be used as an anchor to refer to the static definition scope of the lambda expression in the yaml document that was used to define the lambda function. Those references are always interpreted as relative references related to the this static yaml document scope. There is no denotation for accessing the root element of this definition scope.

Relative names can be used to access the static definition scope given inside the dynaml expression (outer scope literals and parameters of outer lambda parameters)

например:

 env :
  func : (( |x|->[ x, scope, _, _.scope ] ))
  scope : definition

call :
   result : (( env.func("arg") ))
   scope : call

yields the result list:

 call :
  result :
  - arg
  - call
  - (( lambda|x|->[x, scope, _, _.scope] ))  # the lambda expression as lambda value
  - definition

This also works across multiple stubs. The definition context is the stub the lambda expression is defined in, even if it is used in stubs down the chain. Therefore it is possible to use references in the lambda expression, not visible at the caller location, they carry the static yaml document scope of their definition with them.

Inner lambda expressions remember the local binding of outer lambda expressions. This can be used to return functions based on arguments of the outer function.

например:

 mult : (( lambda |x|-> lambda |y|-> x * y ))
mult2 : (( .mult(2) ))
value : (( .mult2(3) ))

yields 6 for property value .

Optional Parameters

Trailing parameters may be defaulted in the lambda expression by assigning values in the declaration. Those parameter are then optional, it is not required to specify arguments for those parameters in function calls.

например:

 mult : (( lambda |x,y=2|-> x * y ))
value : (( .mult(3) ))

yields 6 for property value .

It is possible to default all parameters of a lambda expression. The function can then be called without arguments. There might be no non-defaulted parameters after a defaulted one.

A call with positional arguments may only omit arguments for optional parameters from right to left. If there should be an explicit argument for the right most parameter, arguments for all parameters must be specified or named arguments must be used. Here the desired optional parameter can explicitly be set prior to the regular positional arguments.

например:

 func :  (( |a,b=1,c=2|->{$a=a, $b=b, $c=c } ))
result : (( .func(c=3, 2) ))

evaluates result to

 result :
  a : 2
  b : 1
  c : 3

The expression for the default does not need to be a constant value or even expression, it might refer to other nodes in the yaml document. The default expression is always evaluated in the scope of the lambda expression declaration at the time the lambda expression is evaluated.

например:

stub.yaml

 default : 2
mult : (( lambda |x,y=default * 2|-> x * y ))

template.yaml

 mult : (( merge ))
scope :
  default : 3
  value : (( .mult(3) ))

evaluates value to 12

Variable Argument Lists

The last parameter in the parameter list of a lambda expression may be a varargs parameter consuming additional argument in a fnction call. This parameter is always a list of values, one entry per additional argument.

A varargs parameter is denoted by a ... following the last parameter name.

например:

 func : (( |a,b...|-> [a] b ))
result : (( .func(1,2,3) ))

yields the list [1, 2, 3] for property result .

If no argument is given for the varargs parameter its value is the empty list.

The ... operator can also be used for inline list expansion.

If a vararg parameter should be set by a named argument its value must be a list.

Currying

Using the currying operator ( *( ) a lambda function may be transformed to another function with less parameters by specifying leading argument values.

The result is a new function taking the missing arguments (currying) and using the original function body with a static binding for the specified parameters.

например:

 mult : (( lambda |x,y|-> x * y ))
mult2 : (( .mult*(2) ))
value : (( .mult2(3) ))

Currying may be combined with defaulted parameters. But the resulting function does not default the leading parameters, it is just a new function with less parameters pinning the specified ones.

If the original function uses a variable argument list, the currying may span any number of the variable argument part, but once at least one such argument is given, the parameter for the variable part is satisfied. It cannot be extended by a function call of the curried function.

например:

 func : (( |a,b...|->join(a,b) ))
func1 : (( .func*(",","a","b")))
# invalid: (( .func1("c") ))
value : (( .func1() ))

evaluates value to "a,b" .

It is also possible to use currying for builtin functions, like join .

например:

 stringlist : (( join*(",") ))
value : (( .stringlist("a", "b")  ))

evaluates value to "a,b" .

There are several builtin functions acting on unevaluated or unevaluatable arguments, like defined . For these functions currying is not possible.

Using positional arguments currying is only possible from right to left. But currying can also be done for named arguments. Here any parameter combination, regardless of the position in the parameter list, can be preset. The resulting function then has the unsatisfied parameters in their original order. Switching the parameter order is not possible.

например:

 func : (( |a,b=1,c=2|->{$a=a, $b=b, $c=c } ))
curry : (( .func(c=3, 2) ))

result : (( .curry(5) ))

evalutes result to

 result :
  a : 2
  b : 5
  c : 3

The resulting function keeps the parameter b . Hereby the default value will be kept. Therefore it can just be called without argument ( .curry() ), which would produce

 result :
  a : 2
  b : 1
  c : 3

Внимание :

For compatibility reasons currying is also done, if a lambda function without defaulted parameters is called with less arguments than declared parameters.

This behaviour is deprecated and will be removed in the future. It is replaced by the currying operator.

например:

 mult : (( lambda |x,y|-> x * y ))
mult2 : (( .mult(2) ))
value : (( .mult2(3) ))

evaluates value to 6.

`(( catch[expr|v,e|->v] ))`

This expression evaluates an expression ( expr ) and then executes a lambda function with the evaluation state of the expression. It always succeeds, even if the expression fails. The lambda function may take one or two arguments, the first is always the evaluated value (or nil in case of an error). The optional second argument gets the error message the evaluation of the expression failed (or nil otherwise)

The result of the function is the result of the whole expression. If the function fails, the complete expression fails.

например:

 data :
  fail : (( catch[1 / 0|v,e|->{$value=v, $error=e}] ))
  valid : (( catch[5 * 5|v,e|->{$value=v, $error=e}] ))

resolves to

 data :
  fail :
    error : division by zero
    value : null
  valid :
    error : null
    value : 25

`(( sync[expr|v,e|->defined(v.field),v.field|10] ))`

If an expression expr may return different results for different evaluations, it is possible to synchronize the final output with a dedicated condition on the expression value. Such an expression could, for example, be an uncached read , exec or pipe call.

The second element must evaluate to a lambda value, given by either a regular expression or by a lambda literal as shown in the title. It may take one or two arguments, the actual value of the value expression and optionally an error message in case of a failing evaluation. The result of the evaluation of the lamda expression decides whether the state of the evaluation of the value expression is acceptable ( true ) or not ( false ).

If the value is accepted, an optional third expression is used to determine the final result of the sync[] expression. It might be given as an expression evaluating to a lambda value, or by a comma separated expression using the same binding as the preceeding lambda literal. If not given, the value of the synched expression is returned.

If the value is not acceptable, the evaluation is repeated until a timeout applies. The timeout in seconds is given by an optional fourth expression (default is 5 min). Either the fourth, or the both, the third and the fourth elements may be omitted.

The lambda values might be given as literal, or by expression, leading to the following flavors:

sync[expr|v,e|->cond,value|10]
sync[expr|v,e|->cond|valuelambda|10]
sync[expr|v,e|->cond|v|->value|10]
sync[expr|condlambda|valuelambda|10]
sync[expr|condlambda|v|->value|10]

with or without the timeout expression.

например:

 data :
  alice : 25
result : (( sync[data|v|->defined(v.alice),v.alice] ))

resolves to

 data :
  alice : 25
result : 25

This example is quite useless, because the sync expression is a constant. It just demonstrates the usage.

Mappings

Mappings are used to produce a new list from the entries of a list or map , or a new map from entries of a map containing the entries processed by a dynaml expression. The expression is given by a lambda function. There are two basic forms of the mapping function: It can be inlined as in (( map[list|x|->x ":" port] )) , or it can be determined by a regular dynaml expression evaluating to a lambda function as in (( map[list|mapping.expression)) (here the mapping is taken from the property mapping.expression , which should hold an approriate lambda function).

The mapping comes in two target flavors: with [] or {} in the syntax. The first flavor always produces a list from the entries of the given source. The second one takes only a map source and produces a filtered or transformed map .

Additionally the mapping uses three basic mapping behaviours:

transforming the values using the keyword map . Here the result of the lambda function is used as new value to replace the original one. Или
filtering using the keywork select . Here the result of the lambda function is used as a boolean to decide whether the entry should be kept ( true ) or omitted ( false ).
composing using the keyword sum . Here always the list flavor is used, but the result type and content is completely determined by the parameterization of the statement by successively aggregating one entry after the other into an arbitrary initial value.

Note : The special reference _ is not set for inlined lambda functions as part of the mapping syntax. Therefore the mapping statements (and all other statements using inlined lambda functions as part of their syntax) can be used inside regular lambda functions without hampering the meaning of this special refrence for the surrounding explicit lambda expression.

`(( map[list|elem|->dynaml-expr] ))`

Execute a mapping expression on members of a list to produce a new (mapped) list. The first expression ( list ) must resolve to a list. The last expression ( x ":" port ) defines the mapping expression used to map all members of the given list. Inside this expression an arbitrarily declared simple reference name (here x ) can be used to access the actually processed list element.

например

 port : 4711
hosts :
  - alice
  - bob
mapped : (( map[hosts|x|->x ":" port] ))

урожайность

 port : 4711
hosts :
- alice
- bob
mapped :
- alice:4711
- bob:4711

This expression can be combined with others, for example:

 port : 4711
list :
  - alice
  - bob
joined : (( join( ", ", map[list|x|->x ":" port] ) ))

which magically provides a comma separated list of ported hosts:

 port : 4711
list :
  - alice
  - bob
joined : alice:4711, bob:4711

`(( map[list|idx,elem|->dynaml-expr] ))`

In this variant, the first argument idx is provided with the index and the second elem with the value for the index.

например

 list :
  - name : alice
    age : 25
  - name : bob
    age : 24

ages : (( map[list|i,p|->i + 1 ". " p.name " is " p.age ] ))

урожайность

 list :
  - name : alice
    age : 25
  - name : bob
    age : 24

ages :
- 1. alice is 25
- 2. bob is 24

`(( map[map|key,value|->dynaml-expr] ))`

Mapping of a map to a list using a mapping expression. The expression may have access to the key and/or the value. If two references are declared, both values are passed to the expression, the first one is provided with the key and the second one with the value for the key. If one reference is declared, only the value is provided.

например

 ages :
  alice : 25
  bob : 24

keys : (( map[ages|k,v|->k] ))

урожайность

 ages :
  alice : 25
  bob : 24

keys :
- alice
- bob

`(( map{map|elem|->dynaml-expr} ))`

Using {} instead of [] in the mapping syntax, the result is again a map with the old keys and the new entry values. As for a list mapping additionally a key variable can be specified in the variable list.

 persons :
  alice : 27
  bob : 26
older : (( map{persons|x|->x + 1} ) ))

just increments the value of all entries by one in the field older :

 older :
  alice : 28
  bob : 27

Примечание

An alternate way to express the same is to use sum[persons|{}|s,k,v|->s { k = v + 1 }] .

`(( map{list|elem|->dynaml-expr} ))`

Using {} instead of [] together with a list in the mapping syntax, the result is again a map with the list elements as key and the mapped entry values. For this all list entries must be strings. As for a list mapping additionally an index variable can be specified in the variable list.

 persons :
  - alice
  - bob
length : (( map{persons|x|->length(x)} ) ))

just creates a map mapping the list entries to their length:

 length :
  alice : 5
  bob : 3

`(( select[expr|elem|->dynaml-expr] ))`

With select a map or list can be filtered by evaluating a boolean expression for every entry. An entry is selected if the expression evaluates to true equivalent value. (see conditions).

Basically it offers all the mapping flavors available for map[]

например

 list :
  - name : alice
    age : 25
  - name : bob
    age : 26


selected : (( select[list|v|->v.age > 25 ] ))

evaluates selected to

 selected :
- name : bob
  age : 26

Примечание

An alternate way to express the same is to use map[list|v|->v.age > 25 ? v :~] .

`(( select{map|elem|->dynaml-expr} ))`

Using {} instead of [] in the mapping syntax, the result is again a map with the old keys filtered by the given expression.

 persons :
  alice : 25
  bob : 26
older : (( select{persons|x|->x > 25} ))

just keeps all entries with a value greater than 25 and omits all others:

 selected :
  bob : 26

This flavor only works on maps .

Примечание

An alternate way to express the same is to use sum[persons|{}|s,k,v|->v > 25 ? s {k = v} :s] .

Агрегации

Aggregations are used to produce a single result from the entries of a list or map aggregating the entries by a dynaml expression. The expression is given by a lambda function. There are two basic forms of the aggregation function: It can be inlined as in (( sum[list|0|s,x|->s + x] )) , or it can be determined by a regular dynaml expression evaluating to a lambda function as in (( sum[list|0|aggregation.expression)) (here the aggregation function is taken from the property aggregation.expression , which should hold an approriate lambda function).

`(( sum[list|initial|sum,elem|->dynaml-expr] ))`

Execute an aggregation expression on members of a list to produce an aggregation result. The first expression ( list ) must resolve to a list. The second expression is used as initial value for the aggregation. The last expression ( s + x ) defines the aggregation expression used to aggregate all members of the given list. Inside this expression an arbitrarily declared simple reference name (here s ) can be used to access the intermediate aggregation result and a second reference name (here x ) can be used to access the actually processed list element.

например

 list :
  - 1
  - 2
sum : (( sum[list|0|s,x|->s + x] ))

урожайность

 list :
  - 1
  - 2
sum : 3

`(( sum[list|initial|sum,idx,elem|->dynaml-expr] ))`

In this variant, the second argument idx is provided with the index and the third elem with the value for the index.

например

 list :
  - 1
  - 2
  - 3

prod : (( sum[list|0|s,i,x|->s + i * x ] ))

урожайность

 list :
  - 1
  - 2
  - 3

prod : 8

`(( sum[map|initial|sum,key,value|->dynaml-expr] ))`

Aggregation of the elements of a map to a single result using an aggregation expression. The expression may have access to the key and/or the value. The first argument is always the intermediate aggregation result. If three references are declared, both values are passed to the expression, the second one is provided with the key and the third one with the value for the key. If two references are declared, only the second one is provided with the value of the map entry.

например

 ages :
  alice : 25
  bob : 24

sum : (( map[ages|0|s,k,v|->s + v] ))

урожайность

 ages :
  alice : 25
  bob : 24

sum : 49

Projections

Projections work over the elements of a list or map yielding a result list. Hereby every element is mapped by an optional subsequent reference expression. This may contain again projections, dynamic references or lambda calls. Basically this is a simplified form of the more general mapping yielding a list working with a lambda function using only a reference expression based on the elements.

`(( expr.[*].value ))`

All elements of a map or list given by the expression expr are dereferenced with the subsequent reference expression (here .expr ). If this expression works on a map the elements are ordered accoring to their key values. If the subsequent reference expression is omitted, the complete value list isreturned. For a list expression this means the identity operation.

например:

 list :
  - name : alice
    age : 25
  - name : bob
    age : 26
  - name : peter
    age : 24

names : (( list.[*].name ))

yields for names :

 names :
  - alice
  - bob
  - peter

or for maps:

 networks :
  ext :
    cidr : 10.8.0.0/16
  zone1 :
    cidr : 10.9.0.0/16

cidrs : (( .networks.[*].cidr ))

yields for cidrs :

 cidrs :
  - 10.8.0.0/16
  - 10.9.0.0/16

`(( list.[1..2].value ))`

This projection flavor only works for lists. The projection is done for a dedicated slice of the initial list.

например:

 list :
  - name : alice
    age : 25
  - name : bob
    age : 26
  - name : peter
    age : 24

names : (( list.[1..2].name ))

yields for names :

 names :
  - bob
  - peter

Inline List Expansion

In argument lists or list literals the list expansion operator ( ... ) can be used. It is a postfix operator on any list expression. It substituted the list expression by a sequence of the list members. It can be be used in combination with static list argument denotation.

например:

 list :
  - a
  - b
  
result : (( [ 1, list..., 2, list... ]  ))

evaluates result to

 result :
  - 1
  - a
  - b
  - 2
  - a
  - b

The following example demonstrates the usage in combination with the varargs operator in functions:

 func : (( |a,b...|-> [a] b ))

list :
  - a
  - b

a : (( .func(1,2,3) ))
b : (( .func("x",list..., "z") ))
c : (( [ "x", .func(list...)..., "z" ] ))

evaluates the following results:

 a :
- 1
- 2
- 3
b :
- x
- a
- b
- z
c :
- x
- a
- b
- z

Please note, that the list expansion might span multiple arguments (including the varargs parameter) in lambda function calls.

Маркеры

Nodes of the yaml document can be marked to enable dedicated behaviours for this node. Such markers are part of the dynaml syntax and may be prepended to any dynaml expression. They are denoted by the & character directly followed by a marker name. If the expression is a combination of markers and regular expressions, the expression follows the marker list enclosed in brackets (for example (( &temporary( a + b ) )) ).

Note : Instead of using a <<: insert field to place markers it is possible now to use <<<: , also, which allows to use regular yaml parsers for spiff-like yaml documents. <<: is kept for backward compatibility.

`(( &temporary ))`

Maps, lists or simple value nodes can be marked as temporary . Temporary nodes are removed from the final output document, but are available during merging and dynaml evaluation.

например:

 temp :
  << : (( &temporary ))
  foo : bar

value : (( temp.foo ))

yields:

 value : bar

Adding - <<: (( &temporary )) to a list can be used to mark a list as temporary.

The temporary marker can be combined with regular dynaml expressions to tag plain fields. Hereby the parenthesised expression is just appended to the marker

например:

 data :
  alice : (( &temporary ( "bar" ) ))
  foo : (( alice ))

yields:

 data :
  foo : bar

The temporary marker can be combined with the template marker to omit templates from the final output.

`(( &local ))`

The marker &local acts similar to &temporary but local nodes are always removed from a stub directly after resolving dynaml expressions. Such nodes are therefore not available for merging and they are not used for further merging of stubs and finally the template.

`(( &dynamic ))`

This marker can be used to mark a template expression (direct or referenced) to enforce the re-evaluation of the template in the usage context whenever the node is used to override or inject a node value along the processing chain. It can also be used together with &inject or &default .

например:

template.yaml

 data : 1

слился с

stub.yaml

 id : (( &dynamic &inject &template(__ctx.FILE) ))

will resolve to

 id : template.yaml
data : 1

The original template is kept along the merge chain and is evaluated separately in the context of the very stub or template it is used.

Using this marker for nodes not evaluationg to a template value is not possible.

`(( &inject ))`

This marker requests the marked item to be injected into the next stub level, even is the hosting element (list or map) does not requests a merge. This only works if the next level stub already contains the hosting element.

например:

template.yaml

 alice :
 foo : 1

stub.yaml

 alice :
  bar : (( &inject(2) ))
  nope : not injected
bob :
  << : (( &inject ))
  foobar : yep

is merged to

 alice :
  foo : 1
  bar : 2
bob :
  foobar : yep

`(( &default ))`

Nodes marked as default will be used as default values for downstream stub levels. If no such entry is set there it will behave like &inject and implicitly add this node, but existing settings will not be overwritten.

Maps (or lists) marked as default will be considered as values. The map is used as a whole as default if no such field is defined downstream.

например:

template.yaml

 data : { }

stub.yaml

 data :
  foobar :
    << : (( &default ))
    foo : claude
    bar : peter

is merged to

 data :
  foobar :
    foo : claude
    bar : peter

Their entries will neither be used for overwriting existing downstream values nor for defaulting non-existng fields of a not defaulted map field.

например:

template.yaml

 data :
  foobar :
    bar : bob

stub.yaml

 data :
  foobar :
    << : (( &default ))
    foo : claude
    bar : peter

is merged to

 data :
  foobar :
    bar : bob

If sub sequent defaulting is desired, the fields of a default map must again be marked as default.

например:

template.yaml

 data :
  foobar :
    bar : bob

stub.yaml

 data :
  foobar :
    << : (( &default ))
    foo : (( &default ("claude") ))
    bar : peter

is merged to

 data :
  foobar :
    foo : claude
    bar : bob

Note : The behaviour of list entries marked as default is undefined.

`(( &state ))`

Nodes marked as state are handled during the merge processing as if the marker would not be present. But there will be a special handling for enabled state processing (option --state <path> ) at the end of the template processing. Additionally to the regular output a document consisting only of state nodes (plus all nested nodes) will be written to a state file. This file will be used as top-level stub for further merge processings with enabled state support.

This enables to keep state between two merge processings. For regular merging sich nodes are only processed during the first processing. Later processings will keep the state from the first one, because those nodes will be overiden by the state stub added to the end of the sub list.

If those nodes additionally disable merging (for example using (( &state(merge none) )) ) dynaml expressions in sub level nodes may perform explicit merging using the function stub() to refer to values provided by already processed stubs (especially the implicitly added state stub). For an example please refer to the state library.

`(( &template ))`

Nodes marked as template will not be evaluated at the place of their occurrence. Instead, they will result in a template value stored as value for the node. They can later be instantiated inside a dynaml expression (see below).

`(( &tag:name ))`

The tag marker can be used to assign a logical name to a node value. This name can then be used in tagged reference expressions to refer to this node value (see below).

A tagged reference has the form <tagname>::<path> . The <path> may denote any sub node of a tagged node. If the value of a complete node (or a simple value node) should be used, the <path> must denote the root path ( . ).

Tags can be used to label node values in multi-document streams (used as template). After defined for a document the tag can then be used to reference node values from the actual or previous document(s) of a document sequence in a multi-document stream. Tags can be added for complex or simple value nodes. A tagged reference may be used to refer to the tagged value as a whole or sub structure.

`(( &tag:name(value) ))`

This syntax is used to tag a node whose value is defined by a dynaml expression. It can also be used to denote tagged simple value nodes. (As usual the value part is optional for adding markers to structured values (see Markers).)

например:

template.yaml

 data :
  << : (( &tag:persons ))
  alice : (( &tag:alice(25)

If the name is prefixed with a star ( * ), the tag is defined globally. Gobal tags surive stub processing and their value is visible in subsequent stub (and template) processings.

A tag name may consist of multiple components separated by a colon ( : ).

Tags can also be defined dynamically by the dynaml function tagdef.

`(( tag::foo ))`

Reference a sub path of the value of a tagged node.

например:

template.yaml

 data :
  << : (( &tag:persons ))
  alice : 25

tagref : (( persons::alice ))

resolves tagref to 25

`(( tag::. ))`

Reference the whole (structured) value of tagged node.

например:

template.yaml

 data :
  alice : (( &tag:alice(25) ))

tagref : (( alice::. ))

resolves tagref to 25

`(( foo.bar::alice ))`

Tag names may be structured. A tag name consists of a non-empty list of tag components separated by a dot or colon ( : ). A tag component may contain ASCII letters or numbers, starting wit a letter. Multi-component tags are subject to Tag Resolution.

Path Resolution for Tags

A tag reference always contains a tag name and a path separated by a double colon ( :: ). The standard use-case is to describe a dedicated sub node for a tagged node value.

for example, if the tag X describes the value

 data :
  alice : 25
  bob : 24

the tagged reference X::data.alice describes the value 25 .

For tagged references with a path other than . (the whole tag value), structured tags feature a more sophisticated resolution mechanism. A structured tag consist of multiple tag components separated by a colon ( : ), for example lib:mylib . Therefore, tags span a tree of namespaces or scopes used to resolve path references. A tag-less reference just uses the actual document or binding to resolve a path expression.

Evaluation of a path reference for a tag tries to resolve the path in the first tag tree level where the path is available (breadth-first search). If this level contains multiple tags that could resolve the given path, the resolution fails because it cannot be unambigiously resolved.

Например:

 tags :
  - << : (( &tag:lib:alice ))
    data : alice.alice
  - << : (( &tag:lib:alice:v1))
    data : alice.v1
  - << : (( &tag:lib:bob))
    other : bob
usage :
   data : (( lib::data ))

effectively resolves usage.data to lib:alice::data and therefore to the value alice.alice .

To achieve this all matching sub tags are orderd by their number of tag components. The first sub-level tag containing such a given path is selected. For this level, the matching tag must be non-ambigious. There must only be one tag with this level containing a matching path. If there are multiple ones the evaluation fails. In the above example this would be the case if tag lib:bob would contain a field data instead of or additional to other .

This feature can be used in library stubs to provide qualified names for their elements that can be used with merging the containing document nodes into the template.

Tags in Multi-Document Streams

If the template file is a multi-document stream the tags are preserved during the complete processing. This means tags defined in a earlier document can be used in all following documents, also. But the tag names must be unique across all documents in a multi-document stream.

например:

template.yaml

 << : (( &temporary ))
data :
  << : (( &tag:persons ))
  alice : 25
  bob : 24
---
alice : (( persons::alice ))
---
bob : (( persons::bob ))

resolves to

---
alice : 25
---
bob : 24

Tags defined by tag markers are available for stubs and templates. Global tags are available down the stub processing to the templates. Local tags are only avaialble on the processing level they are declared.

Additionally to the tags explicitly set by tag markers, there are implicit document tags given by the document index during the processing of a (multi-document) template. The implicit document tags are qualified with the prefix doc. . This prefix should not be used to own tags in the documents

например:

template.yaml

 << : (( &temporary ))
data :
  << : (( &tag:persons ))
  alice : 25
  bob : 24
---
alice : (( persons::alice ))
prev : (( doc.1::. ))
---
bob : (( persons::bob ))
prev : (( doc.2::. ))

resolves to

---
alice : 25
prev :
  data :
    alice : 25
    bob : 24
---
bob : 24
prev :
  alice : 25
  prev :
    data :
      alice : 25
      bob : 24

If the given document index is negative it denotes the document relative to the one actually processed (so, the tag doc.-1 denotes the previous document). The index doc.0 can be used to denote the actual document. Here always a path must be specified, it is not possible to refer to the complete document (with . ).

Шаблоны

A map can be tagged by a dynaml expression to be used as template. Dynaml expressions in a template are not evaluated at its definition location in the document, but can be inserted at other locations using dynaml. At every usage location it is evaluated separately.

`<<: (( &template ))`

The dynaml expression &template can be used to tag a map node as template:

например:

 foo :
  bar :
    << : (( &template ))
    alice : alice
    bob : (( verb " " alice ))

The template will be the value of the node foo.bar . As such it can be overwritten as a whole by settings in a stub during the merge process. Dynaml expressions in the template are not evaluated. A map can have only a single << field. Therefore it is possible to combine the template marker with an expression just by adding the expression in parenthesis.

Adding - <<: (( &template )) to a list it is also possible to define list templates. It is also possible to convert a single expression value into a simple template by adding the template marker to the expression, for example foo: (( &template (expression) ))

The template marker can be combined with the temporary marker to omit templates from the final output.

Note : Instead of using a <<: insert field to place the template marker it is possible now to use <<<: , also, which allows to use regular yaml parsers for spiff-like yaml documents. <<: is kept for backward compatibility.

`(( *foo.bar ))`

The dynaml expression *<reference expression> can be used to evaluate a template somewhere in the yaml document. Dynaml expressions in the template are evaluated in the context of this expression.

например:

 foo :
  bar :
    << : (( &template ))
    alice : alice
    bob : (( verb " " alice ))


use :
  subst : (( *foo.bar ))
  verb : loves

verb : hates

evaluates to

 foo :
  bar :
    << : (( &template ))
    alice : alice
    bob : (( verb " " alice ))

use :
  subst :
    alice : alice
    bob : loves alice
  verb : loves

verb : hates

Scope References

`_`

The special reference _ ( self ) can be used inside of lambda functions and templates . They refer to the containing element (the lambda function or template).

Additionally it can be used to lookup relative reference expressions starting with the defining document scope of the element skipping intermediate scopes.

например:

 node :
  data :
    scope : data
  funcs :
    a : (( |x|->scope ))
    b : (( |x|->_.scope ))
    c : (( |x|->_.data.scope ))
    scope : funcs

call :
  scope : call

  a : (( node.funcs.a(1) ))
  b : (( node.funcs.b(1) ))
  c : (( node.funcs.c(1) ))

evaluates call to

 call :
  a : call
  b : funcs
  c : data
  scope : call

`__`

The special reference __ can be used to lookup references as relative references starting with the document node hosting the actually evaluated dynaml expression skipping intermediate scopes.

This can, for example be used to relatively access a lambda value field besides the actual field in a map. The usage of plain function names is reserved for builtin functions and are not used as relative references.

This special reference is also available in expressions in templates and refer to the map node in the template hosting the actually evaluated expression.

например:

 templates :
  templ :
    << : (( &template ))
    self : (( _ ))
    value : (( ($self="value") __.self ))
    result : (( scope ))
    templ : (( _.scope ))

  scope : templates


result :
  inst : (( *templates.templ ))
  scope : result

evaluates result to

 result :
  inst :
    result : result
    templ : templates
    
    self :
      << : (( &template ))
      result : (( scope ))
      self : (( _ ))
      templ : (( _.scope ))
      value : (( ($self="value") __.self ))
    value :
      << : (( &template ))
      result : (( scope ))
      self : (( _ ))
      templ : (( _.scope ))
      value : (( ($self="value") __.self ))
  scope : result

or with referencing upper nodes:

 templates :
  templ :
    << : (( &template ))
    alice : root
    data :
      foo : (( ($bob="local") __.bob ))
      bar : (( ($alice="local") __.alice ))
      bob : static


result : (( *templates.templ ))

evaluates result to

 result :
  alice : root
  data :
    bar : root
    foo : static
    
    bob : static

`___`

The special reference ___ can be used to lookup references in the outer most scope. It can therefore be used to access processing bindings specified for a document processing via command line or API. If no bindings are specified the document root is used.

Calling spiff merge template.yaml --bindings bindings.yaml with a binding of

bindings.yaml

 input1 : binding1
input2 : binding2

and the template

template.yaml

 input1 : top1
map :
  input : map
  input1 : map1
  
  results :
    frommap : (( input1 ))
    fromroot : (( .input1 ))
    frombinding1 : (( ___.input1 ))
    frombinding2 : (( input2 ))

evaluates map.results to

  results :
    frombinding1 : binding1
    frombinding2 : binding2
    frommap : map1
    fromroot : top1

`__ctx.OUTER`

The context field OUTER is used for nested merges. It is a list of documents, index 0 is the next outer document, and so on.

Special Literals

`(( {} ))`

Provides an empty map.

`(( [] ))`

Provides an empty list. Basically this is not a dedicated literal, but just a regular list expression without a value.

`(( ~ ))`

Provides the null value.

`(( ~~ ))`

This literal evaluates to an undefined expression. The element (list entry or map field) carrying this value, although defined, will be removed from the document and handled as undefined for further merges and the evaluation of referential expressions.

например:

 foo : (( ~~ ))
bob : (( foo || ~~ ))
alice : (( bob || "default"))

evaluates to

 alice : default

Access to evaluation context

Inside every dynaml expression a virtual field __ctx is available. It allows access to information about the actual evaluation context. It can be accessed by a relative reference expression.

The following fields are supported:

Field Name	Тип	Значение
`VERSION`	нить	current version of spiff
`FILE`	нить	name of actually processed template file
`DIR`	нить	name of directory of actually processed template file
`RESOLVED_FILE`	нить	name of actually processed template file with resolved symbolic links
`RESOLVED_DIR`	нить	name of directory of actually processed template file with resolved symbolic links
`PATHNAME`	нить	path name of actually processed field
`PATH`	list[string]	path name as component list
`OUTER`	yaml doc	outer documents for nested merges, index 0 is the next outer document
`BINDINGS`	yaml doc	the external bindings for the actual processing (see also ___)

If external bindings are specified they are the last elements in OUTER .

например:

template.yml

 foo :
  bar :
    path : (( __ctx.PATH ))
    str : (( __ctx.PATHNAME ))
    file : (( __ctx.FILE ))
    dir : (( __ctx.DIR ))

evaluates to

например:

 foo :
  bar :
    dir : .
    file : template.yml
    path :
    - foo
    - bar
    - path
    str : foo.bar.str

Operation Priorities

Dynaml expressions are evaluated obeying certain priority levels. This means operations with a higher priority are evaluated first. For example the expression 1 + 2 * 3 is evaluated in the order 1 + ( 2 * 3 ) . Operations with the same priority are evaluated from left to right (in contrast to version 1.0.7). This means the expression 6 - 3 - 2 is evaluated as ( 6 - 3 ) - 2 .

The following levels are supported (from low priority to high priority)

|| , //
White-space separated sequence as concatenation operation ( foo bar )
-or , -and
== , != , <= , < , > , >=
+ , -
* , / , %
Grouping ( ) , ! , constants, references ( foo.bar ), merge , auto , lambda , map[] , and functions

The complete grammar can be found in dynaml.peg.

String Interpolation

Feature state: alpha

Attention: This is an alpha feature. It must be enabled on the command line with the --interpolation or --features=interpolation option. Also for the spiff library it must explicitly be enabled. By adding the key interpolation to the feature list stored in the environment variable SPIFF_FEATURES this feature will be enabled by default.

Typically a complete value can either be a literal or a dynaml expression. For string literals it is possible to use an interpolation syntax to embed dynaml expressions into strings.

Например

 data : test
interpolation : this is a (( data ))

replaces the part between the double brackets by the result of the described expression evaluation. Here the brackets can be escaped by the usual escaping ( ((! ) syntax.

Those string literals will implicitly be converted to complete flat dynaml expressions. The example above will therefore be converted into

(( "this is a " data ))

which is the regular dynaml equivalent. The escaping is very ticky, and may be there are still problems. Quotes inside an embedded dynaml expression can be escaped to enable quotes in string literals.

Incomplete or partial interpolation expressions will be ignored and just used as string.

Strings inside a dynaml expression are NOT directly interpolated again, thus

 data : " test "
interpolated : " this is a (( length( " (( data )) " ) data )) "

will resolve interpolation to this is 10test and not to this is 4test .

But if the final string after the expression evaluation again describes a string interpolation it will be processed, again.

 data : test
interpolation : this is a (( "(( data ))" data ))

will resolve interpolation to this is testtest .

The embedded dynaml expression must be concatenatable with strings.

YAML-based Control Structures

Feature state: alpha

In addition to describe conditions and loops with dynaml expressions it is also possible to use elements of the document structure to embed control structures.

Such a YAML-based control structure is always described as a map in YAML/JSON. The syntactical elements are expressed as map fields starting with << . Additionally, depending on the control structure, regular fields are possible. Control structures finally represent a value for the containing node. They may contain marker expressions ( << ), also.

например:

 temp :
  << : (( &temporary ))
  <<if : (( features("control") ))
  <<then :
    alice : 25
    bob : 26

resolves to

 final :
  alice : 25
  bob : 26

Tu use this alpha feature the feature flag control must be enabled.

Please be aware: Control structure maps typically are always completely resolved before they are evaluated.

Control Structures in Maps

A control structure itself is always a dedicated map node in a document. It is substituted by a regular value node determined by the execution of the control structure.

The fields of a control structure map are not subject to overwriting by stubs, but the complete structure can be overwritten.

If used as value for a map field the resulting value is just used as effective value for this field.

If a map should be enriched by maps resulting from multiple control structures the special control structure <<merge: can be used. It allows to specify a list of maps which should be merged with the actual control structure map to finally build the result value.

Control Structures in Lists

A control structure can be used as list value, also. In this case there is a dedicated interpretation of the resulting value of the control structure. If it is NOT a list value, for convenience, the value is directly used as list entry and substitutes the control structure map.

If the resulting value is again a list, it is inserted into the containing list at the place of occurrence of the control structure. So, if a list value should be used as dedicated entry in a list, the result of a control structure must be a list with the intended list as entry.

например:

 list :
 - <<if : (( features("control") ))
   <<then : alice
 - <<if : (( features("control") ))
   <<then :
   - - peter
 - <<if : (( features("control") ))
   <<then :
   - bob

resolves to

 list :
- alice
- - peter
- bob

`<<if:`

The condition structure is defined by the syntax field <<if . It additionally accepts the fields <<then and <<else .

The condition field must provide a boolean value. If it is true the optional <<then field is used to substitute the control structure, otherwise the optional <<else field is used.

If the appropriate case is not specified, the result is the undefined (( ~~ )) value. The containing field is therefore completely omitted from the output.

.например:

 x : test1
cond :
  field :
    <<if : (( x == "test" ))
    <<then : alice
    <<else : bob

evaluates cond.field to bob

If the else case is omitted, the cond field would be an empty map ( field is omitted, because the contained control structure evaluates to undefined )

A comparable way to do this with regular dynaml could look like this:

 cond : (( x == "test" ? "alice" :"bob" ))

A better way more suitable for complex cases would be:

 local :
  << : (( &local))
  then : alice
  else : bob

cond : (( x == "test" ? local.then :local.else ))

`<<switch:`

The switch control structure evaluates the switch value of the <<switch field to a string and uses it to select an appropriate regular field in the control map.

If it is not found the value of the optional field <<default is used. If no default is specified, the control structure evaluates to an error, if no appropriate regular field is available.

The nil value matches the default case. If the switch value is undefined the control evaluates to the undefined value (( ~~ )) .

например:

 x : alice

value :
  <<switch : (( x ))
  alice : 25
  bob : 26 
  <<default : other

evaluates value to 25 .

A comparable way to do this with regular dynaml could look like this:

 local :
  << : (( &local))
  cases :
    alice : 25
    bob : 26
  default : other

value : (( local.cases[x] || local.default ))

`<<type:`

The type control structure evaluates the type of the value of the <<type field and uses it to select an appropriate regular field in the control map.

If it is not found the value of the optional field <<default is used. If no default is specified, the control structure evaluates to an error, if no appropriate regular field is available.

например:

 x : alice

value :
  <<type : (( x ))
  string : alice
  <<default : unknown

evaluates value to alice .

A comparable way to do this with regular dynaml could look like this:

 local :
  << : (( &local))
  cases :
    string : alice
  default : unknown

value : (( local.cases[type(x)] || local.default ))

For more complex scenarios not only switching on strings a second syntax can be used. Instead of using fields in the control map as cases, a dedicated field <<cases may contain a list of cases, that are checked sequentially (In this flavor regular fields are not allowed anymore).

Every case is described again by a map containing the fields:

case : the expected value to match the switch value
match : a lambda function taking one argument and yielding a boolean value used to match the given switch value
value : (optional) the resulting value in case of a match. If not defined the result will be the undefined value.

One of case or match must be present.

например:

 x : 5
selected :
  <<switch : (( x ))
  <<cases :
    - case :
        alice : 25
      value : alice
    - match : (( |v|->v == 5 ))
      value : bob
  <<default : unknown

resolves to

 x : 5
selected : bob

If x would be set to the complex value

 x :
  alice : 25

it would resolve to

 x :
  alice : 25
selected : alice

`<<for:`

The loop control is able to execute a multi-dimensional loop and produce a list or map based on the value combinations.

The loop ranges are specified by the value of the <<for field. It is possible ol loop over lists or maps. The range specification can be given by either a map or list:

map : the keys of the map are the names of the control variables and the values must be lists or maps specifying the ranges.
The map key might optionally be a comma-separated pair (for example key,value ) of variable names. In this case the first name is the name for the index variable and the second one for the value variable.
If multiple ranges are specified iterations are alphabetically ordered by value variable name (first) and index variable name (second) to determine the traversing order.
list : if the control variables are defined by a list, each list element must contain two mandatory and one optional field(s):
- name : the name of the (list or map entry value) control variable
- values : a list to define the value range.
- index : (optional) the name of the variable providing the list index or map key of the loop range (defaulted to index-<name> )
Here the order in the list determine the traversal order.

Traversal is done by recursively iterating follow up ranges for every entry in the actual range. This means the last range is completely iterated for the first values of the first ranges first.

If no index variable is specified for a loop range there is an additional implicit binding for every control variable describing the actual list index or map key of the processed value for this dimension. It is denoted by index-<control variable>

If multiple loop ranges are specified, the ranges may mix iterations over maps and lists.

The iteration result value is determined by the value of the <<do field. It is implicitly handled as template and is evaluated for every set of iteration values.

Lists as Iteration Result

The result of the evaluation using only the <<do value field is a list.

например:

 alice :
 - a
 - b
bob :
 - 1
 - 2
 - 3
list :
  <<for : 
     key,alice : (( .alice )) # sorted by using alice as primary sort key
     bob : (( .bob ))
  <<do :
    value : (( alice "-" key "-" bob "-" index-bob ))

evaluates list to

 list :
- value : a-0-1-0
- value : a-0-2-1
- value : a-0-3-2
- value : b-1-1-0
- value : b-1-2-1
- value : b-1-3-2

It first iterates over the values for alice . For each such value it then iterates over the values of bob .

A comparable way to do this with regular dynaml could look like this:

 list : (( sum[alice|[]|s,key,alice|-> s sum[bob|[]|s,index_bob,bob|->s (alice "-" key "-" bob "-" index_bob)]] ))

A result list may omit entries if the value expression evaluates to the undefined value ( ~~ ). The nil value ( ~ ) is kept. This way a for control can be used to filter lists.

например:

 bob :
- 1
- 2
- 3
filtered :
  <<for : 
     bob : (( .bob ))
  <<do : (( bob == 2 ? ~~ :bob ))

resolves to

 bob :
- 1
- 2
- 3
filtered :
- 1
- 3

Maps as Iteration Result

If the result should be a map it is required to additionally specify a key value for every iteration. This is specified by the optional <<mapkey field. Like the <<do field it is implicitly handled as template and re-evaluated for every iteration.

например:

 x : suffix

alice :
  - a
  - b
bob :
  - 1
  - 2
  - 3

map : 
  <<for :
     - name : alice
       values : (( .alice ))
     - name : bob
       values :  (( .bob ))
  <<mapkey : (( alice bob ))
  <<do :
    value : (( alice bob x ))

evaluates the field map to

 map :
  a1 :
    value : a1suffix
  a2 :
    value : a2suffix
  a3 :
    value : a3suffix
  b1 :
    value : b1suffix
  b2 :
    value : b2suffix
  b3 :
    value : b3suffix

Here the traversal order is irrelevant as long as the generated key values are unique. If several evaluations of the key expression yield the same value the last one will win.

A comparable way to do this with regular dynaml could look like this:

 map : (( sum[alice|{}|s,index_alice,alice|-> s sum[bob|{}|s,index_bob,bob|->s {(alice bob)=alice bob x}]] ))

An iteration value is ignored if the key or the value evaluate to the undefined value (( ~~ )) . Additionally the key may evaluate to the nil value (( ~ )) , also.

например:

 bob :
  b1 : 1
  b2 : 2
  b3 : 3
filtered :
  <<for : 
     key,bob : (( .bob ))
  <<mapkey : (( key ))
  <<do : (( bob == 2 ? ~~ :bob ))

или

 bob :
  b1 : 1
  b2 : 2
  b3 : 3
filtered :
  <<for : 
     key,bob : (( .bob ))
  <<mapkey : (( bob == 2 ? ~~ :key ))
  <<do : (( bob ))

resolve to

 bob :
  b1 : 1
  b2 : 2
  b3 : 3
filtered :
  b1 : 1
  b3 : 3

`<<merge:`

With merge it is possible to merge maps given as list value of the <<merge field with regular map fields from the control structure to determine the final map value.

The value for <<merge: may be a single map or a list of maps to join with the directly given fields.

например:

 map :
  <<merge : 
    - bob : 26
      charlie : 1
    - charlie : 27
  alice : 25
  charlie : 2

resolves to

 map :
  alice : 25
  bob : 26
  charlie : 27

If multiple maps contain the same key, the last value (in order of list) will win.

This might be combined with other control structures, for example to conditionally merge multiple maps:

например:

 x : charlie
map :
  <<merge : 
    - <<if : (( x == "charlie" ))
      <<then :
        charlie : 27
    - <<if : (( x == "alice" ))
      <<then :
        alice : 20
  alice : 25
  charlie : 2

resolves to

 x : charlie
map :
  alice : 25
  charlie : 27

Structural Auto-Merge

By default spiff performs a deep structural merge of its first argument, the template file, with the given stub files. The merge is processed from right to left, providing an intermediate merged stub for every step. This means, that for every step all expressions must be locally resolvable.

Structural merge means, that besides explicit dynaml merge expressions, values will be overridden by values of equivalent nodes found in right-most stub files. In general, flat value lists are not merged. Only lists of maps can be merged by entries in a stub with a matching index.

There is a special support for the auto-merge of lists containing maps, if the maps contain a name field. Hereby the list is handled like a map with entries according to the value of the list entries' name field. If another key field than name should be used, the key field of one list entry can be tagged with the prefix key: to indicate the indended key name. Such tags will be removed for the processed output.

In general the resolution of matching nodes in stubs is done using the same rules that apply for the reference expressions (( foo.bar.[1].baz )).

For example, given the file template.yml :

 foo :
  - name : alice
    bar : template
  - name : bob
    bar : template

plip :
  - id : 1
    plop : template
  - id : 2
    plop : template

bar :
  - foo : template

list :
  - a
  - b

and file stub.yml :

 foo :
  - name : bob
    bar : stub

plip :
  - key:id : 1
    plop : stub

bar :
  - foo : stub

list :
  - c
  - d

 spiff merge template.yml stub.yml

возвращает

 foo :
- bar : template
  name : alice
- bar : stub
  name : bob

plip :
- id : 1
  plop : stub
- id : 2
  plop : template

bar :
- foo : stub

list :
- a
- b

Be careful that any name: key in the template for the first element of the plip list will defeat the key:id: 1 selector from the stub. When a name field exist in a list element, then this element can only be targeted by this name. When the selector is defeated, the resulting value is the one provided by the template.

Bringing it all together

Merging the following files in the given order

deployment.yml

 networks : (( merge ))

cf.yml

 utils : (( merge ))
network : (( merge ))
meta : (( merge ))

networks :
  - name : cf1
    << : (( utils.defNet(network.base.z1,meta.deployment_no,30) ))
  - name : cf2
    << : (( utils.defNet(network.base.z2,meta.deployment_no,30) ))

infrastructure.yml

 network :
  size : 16
  block_size : 256
  base :
    z1 : 10.0.0.0
    z2 : 10.1.0.0

rules.yml

 utils :
  defNet : (( |b,n,s|->(*.utils.network).net ))
  network :
    << : (( &template ))
    start : (( b + n * .network.block_size ))
    first : (( start + ( n == 0 ? 2 :0 ) ))
    lower : (( n == 0 ? [] :b " - " start - 1 ))
    upper : (( start + .network.block_size " - " max_ip(net.subnets.[0].range) ))
    net :
      subnets :
      - range : (( b "/" .network.size ))
        reserved : (( [] lower upper ))
        static :
          - (( first " - " first + s - 1 ))

instance.yml

 meta :
  deployment_no : 1

will yield a network setting for a dedicated deployment

 networks :
- name : cf1
  subnets :
  - range : 10.0.0.0/16
    reserved :
    - 10.0.0.0 - 10.0.0.255
    - 10.0.2.0 - 10.0.255.255
    static :
    - 10.0.1.0 - 10.0.1.29
- name : cf2
  subnets :
  - range : 10.1.0.0/16
    reserved :
    - 10.1.0.0 - 10.1.0.255
    - 10.1.2.0 - 10.1.255.255
    static :
    - 10.1.1.0 - 10.1.1.29

Using the same config for another deployment of the same type just requires the replacement of the instance.yml . Using a different instance.yml

 meta :
  deployment_no : 0

will yield a network setting for a second deployment providing the appropriate settings for a unique other IP block.

 networks :
- name : cf1
  subnets :
  - range : 10.0.0.0/16
    reserved :
    - 10.0.1.0 - 10.0.255.255
    static :
    - 10.0.0.2 - 10.0.0.31
- name : cf2
  subnets :
  - range : 10.1.0.0/16
    reserved :
    - 10.1.1.0 - 10.1.255.255
    static :
    - 10.1.0.2 - 10.1.0.31

If you move to another infrastructure you might want to change the basic IP layout. You can do it just by adapting the infrastructure.yml

 network :
  size : 17
  block_size : 128
  base :
    z1 : 10.0.0.0
    z2 : 10.0.128.0

Without any change to your other settings you'll get

 networks :
- name : cf1
  subnets :
  - range : 10.0.0.0/17
    reserved :
    - 10.0.0.128 - 10.0.127.255
    static :
    - 10.0.0.2 - 10.0.0.31
- name : cf2
  subnets :
  - range : 10.0.128.0/17
    reserved :
    - 10.0.128.128 - 10.0.255.255
    static :
    - 10.0.128.2 - 10.0.128.31

Useful to Know

There are several scenarios yielding results that do not seem to be obvious. Here are some typical pitfalls.

The auto merge never adds nodes to existing structures
For example, merging
template.yml
```
 foo :
  alice : 25
```
с
stub.yml
```
 foo :
  alice : 24
  bob : 26
```
урожайность
```
 foo :
  alice : 24
```
Use <<: (( merge )) to change this behaviour, or explicitly add desired nodes to be merged:
template.yml
```
 foo :
  alice : 25
  bob : (( merge ))
```
Simple node values are replaced by values or complete structures coming from stubs, structures are deep merged.
For example, merging
template.yml
```
 foo : (( ["alice"] ))
```
с
stub.yml
```
 foo :
  - peter
  - paul
```
урожайность
```
 foo :
  - peter
  - paul
```
But the template
```
 foo : [ (( "alice" )) ]
```
is merged without any change.
Expressions are subject to be overridden as a whole
A consequence of the behaviour described above is that nodes described by an expession are basically overridden by a complete merged structure, instead of doing a deep merge with the structues resulting from the expression evaluation.
For example, merging
template.yml
```
 men :
  - bob : 24
women :
  - alice : 25

people : (( women men ))
```
с
stub.yml
```
 people :
  - alice : 13
```
урожайность
```
 men :
  - bob : 24
women :
  - alice : 25

people :
  - alice : 24
```
To request an auto-merge of the structure resulting from the expression evaluation, the expression has to be preceeded with the modifier prefer ( (( prefer women men )) ). This would yield the desired result:
```
 men :
  - bob : 24
women :
  - alice : 25

people :
  - alice : 24
  - bob : 24
```
Nested merge expressions use implied redirections
merge expressions implicity use a redirection implied by an outer redirecting merge. In the following example
```
 meta :
  << : (( merge deployments.cf ))
  properties :
    << : (( merge ))
    alice : 42
```
the merge expression in meta.properties is implicity redirected to the path deployments.cf.properties implied by the outer redirecting merge . Therefore merging with
```
 deployments :
  cf :
    properties :
      alice : 24
      bob : 42
```
урожайность
```
 meta :
  properties :
    alice : 24
    bob : 42
```

Functions and mappings can freely be nested

например:

 pot : (( lambda |x,y|-> y == 0 ? 1 :(|m|->m * m)(_(x, y / 2)) * ( 1 + ( y % 2 ) * ( x - 1 ) ) ))
seq : (( lambda |b,l|->map[l|x|-> .pot(b,x)] ))
values : (( .seq(2,[ 0..4 ]) ))

yields the list [ 1,2,4,8,16 ] for the property values .

Functions can be used to parameterize templates

The combination of functions with templates can be use to provide functions yielding complex structures. The parameters of a function are part of the scope used to resolve reference expressions in a template used in the function body.

например:

 relation :
  template :
    << : (( &template ))
    bob : (( x " " y ))
  relate : (( |x,y|->*relation.template ))

banda : (( relation.relate("loves","alice") ))

evaluates to

 relation :
  relate : lambda|x,y|->*(relation.template)
  template :
    << : (( &template ))
    bob : (( x " " y ))

  banda :
    bob : loves alice

Scopes can be used to parameterize templates

Scope literals are also considered when instantiating templates. Therefore they can be used to set explicit values for relative reference expressions used in templates.

например:

 alice : 1
template :
  << : (( &template ))
  sum : (( alice + bob ))
scoped : (( ( $alice = 25, "bob" = 26 ) *template ))

evaluates to

 alice : 1
template :
  << : (( &template ))
  sum : (( alice + bob ))
scoped :
  sum : 51

Aggregations may yield complex values by using templates
The expression of an aggregation may return complex values by returning inline lists or instantiated templates. The binding of the function will be available (as usual) for the evaluation of the template. In the example below the aggregation provides a map with both the sum and the product of the list entries containing the integers from 1 to 4.
например:
```
 sum : (( sum[[1..4]|init|s,e|->*temp] ))

temp :
  << : (( &template ))
  sum : (( s.sum + e ))
  prd : (( s.prd * e ))
init :
  sum : 0
  prd : 1
```
yields for sum the value
```
 sum:
  prd: 24
  sum: 10
```
Taking advantage of the undefined value
At first glance it might look strange to introduce a value for undefined . But it can be really useful as will become apparent with the following examples.
- Whenever a stub syntactically defines a field it overwrites the default in the template during merging. Therefore it would not be possible to define some expression for that field that eventually keeps the default value. Here the undefined value can help:
  eg: merging
  template.yml
```
 alice : 24
bob : 25
```
  с
  stub.yml
```
 alice : (( config.alice * 2 || ~ ))
bob : (( config.bob * 3 || ~~ ))
```
  урожайность
```
 alice : ~
bob : 25
```
- There is a problem accessing upstream values. This is only possible if the local stub contains the definition of the field to use. But then there will always be a value for this field, even if the upstream does not overwrite it.
  Here the undefined value can help by providing optional access to upstream values. Optional means, that the field is only defined, if there is an upstream value. Otherwise it is undefined for the expressions in the local stub and potential downstream templates. This is possible because the field is formally defined, and will therefore be merged, only after evaluating the expression if it is not merged it will be removed again.
  eg: merging
  template.yml
```
 alice : 24
bob : 25
peter : 26
```
  с
  mapping.yml
```
 config :
  alice : (( ~~ ))
  bob : (( ~~ ))

alice : (( config.alice || ~~ ))
bob : (( config.bob || ~~ ))
peter : (( config.peter || ~~ ))
```
  и
  config.yml
```
 config :
  alice : 4711
  peter : 0815
```
  урожайность
```
 alice : 4711  # transferred from config's config value
bob : 25      # kept default value, because not set in config.yml
peter : 26    # kept, because mapping source not available in mapping.yml
```
This can be used to add an intermediate stub, that offers a dedicated configuration interface and contains logic to map this interface to a manifest structure already defining default values.
Templates versus map literals
As described earlier templates can be used inside functions and mappings to easily describe complex data structures based on expressions refering to parameters. Before the introduction of map literals this was the only way to achieve such behaviour. The advantage is the possibility to describe the complex structure as regular part of a yaml document, which allows using the regular yaml formatting facilitating readability.
например:
```
 scaling :
  runner_z1 : 10
  router_z1 : 4

  jobs : (( sum[scaling|[]|s,k,v|->s [ *templates.job ] ] ))

templates :
  job :
    << : (( &template ))
    name : (( k ))
    instances : (( v ))
```
evaluates to
```
 scaling :
  runner_z1 : 10
  router_z1 : 4

jobs :
  - instances : 4
    name : router_z1
  - instances : 10
    name : runner_z1
  ...
```
With map literals this construct can significantly be simplified
```
 scaling :
  runner_z1 : 10
  router_z1 : 4

jobs :  (( sum[scaling|[]|s,k,v|->s [ {"name"=k, "value"=v} ] ] ))
```
Nevertheless the first, template based version might still be useful, if the data structures are more complex, deeper or with complex value expressions. For such a scenario the description of the data structure as template should be preferred. It provides a much better readability, because every field, list entry and value expression can be put into dedicated lines.
But there is still a qualitative difference. While map literals are part of a single expression always evaluated as a whole before map fields are available for referencing, templates are evaluated as regular yaml documents that might contain multiple fields with separate expressions referencing each other.
например:
```
 range : (( (|cidr,first,size|->(*templates.addr).range)("10.0.0.0/16",10,255) ))

templates :
  addr :
    << : (( &template ))
    base : (( min_ip(cidr) ))
    start : (( base + first ))
    end : (( start + size - 1 ))
    range : (( start " - " end ))
```
evaluates range to
```
 range : 10.0.0.10 - 10.0.1.8
...
```
Defaulting and Requiring Fields
Traditionally defaulting in spiff is done by a downstream template where the playload data file is used as stub.
Fields with simple values can just be specified with their values. They will be overwritten by stubs using the regular spiff document merging mechanisms.
It is more difficult for maps or lists. If a map is specified in the template only its fields will be merged (see above), but it is never replaced as a whole by settings in the playload definition files. And Lists are never merged.
Therefore maps and lists that should be defaulted as a whole must be specified as initial expressions (referential or inline) in the template file.
eg: merging of
template.yaml
```
 defaults :
  << : (( &temporary ))
  person :
    name : alice
    age : bob
config :
  value1 : defaultvalue
  value2 : defaultvalue
  person : (( defaults.person ))
```
и
payload.yaml
```
 config :
   value2 : configured
   othervalue : I want this but don't get it
```
evaluates to
```
 config :
  person :
    age : bob
    name : alice
  value1 : defaultvalue
    value2 : configured
```
In such a scenario the structure of the resulting document is defined by the template. All kinds of variable fields or sub-structures must be forseen by the template by using <<: (( merge )) expressions in maps.
eg: changing template to
template.yaml
```
 defaults :
  << : (( &temporary ))
  person :
    name : alice
    age : bob
config :
  << : (( merge ))
  value1 : defaultvalue
  value2 : defaultvalue
  person : (( defaults.person ))
```
Known optional fields can be described using the undefined ( ~~ ) expression:
template.yaml
```
 config :
  optional : (( ~~ ))
```
Such fields will only be part of the final document if they are defined in an upstream stub, otherwise they will be completely removed.
Required fields can be defined with the expression (( merge )) . If no stub contains a value for this field, the merge cannot be fullfilled and an error is reported. If a dedicated message should be shown instead, the merge expression can be defaulted with an error function call.
например:
template.yaml
```
 config :
  password : (( merge || error("the field password is required") ))
```
will produce the following error if no stub contains a value:
```
 error generating manifest: unresolved nodes:
	(( merge || error("the field password is required") ))	in c.yaml	config.password	()	*the field password is required 
```
This can be simplified by reducing the expression to the sole error expression.
Besides this template based defaulting it is also possible to provide defaults by upstream stubs using the &default marker. Here the payload can be a downstream file.

X509 and providing State

When generating keys or certificates with the X509 Functions there will be new keys or certificates for every execution of spiff . But it is also possible to use spiff to maintain key state. A very simple script could look like this:

 #! /bin/bash
DIR= " $( dirname " $0 " ) /state "
if [ ! -f " $DIR /state.yaml " ] ; then
  echo " state: " > " $DIR /state.yaml "
fi
spiff merge " $DIR /template.yaml " " $DIR /state.yaml " > " $DIR /. $$ " && mv " $DIR /. $$ " " $DIR /state.yaml "

It uses a template file (containing the rules) and a state file with the actual state as stub. The first time it is executed there is an empty state and the rules are not overridden, therefore the keys and certificates are generated. Later on, only additional new fields are calculated, the state fields already containing values just overrule the dynaml expressions for those fields in the template.

If a re-generation is required, the state file can just be deleted.

A template may look like this:

state/template.yaml

 spec :
  << : (( &local ))
  ca :
    organization : Mandelsoft
    commonName : rootca
    privateKey : (( state.cakey ))
    isCA : true
    usage :
      - Signature
      - KeyEncipherment
  peer :
    organization : Mandelsoft
    commonName : etcd
    publicKey : (( state.pub ))
    caCert : (( state.cacert ))
    caPrivateKey : (( state.cakey ))
    validity : 100
    usage :
      - ServerAuth
      - ClientAuth
      - KeyEncipherment
    hosts :
      - etcd.mandelsoft.org

state :
  cakey : (( x509genkey(2048) ))
  capub : (( x509publickey(cakey) ))

  cacert : (( x509cert(spec.ca) ))

  key : (( x509genkey(2048) ))
  pub : (( x509publickey(key) ))
  peer : (( x509cert(spec.peer) ))

The merge then generates a rootca and some TLS certificate signed with this CA.

Generating, Deploying and Accessing Status for Kubernetes Resources
The sync function offers the possibility to synchronize the template processing with external content. This can also be the output of a command execution. Therefore the template processing can not only be used to generate a deployment manifest, but also for applying this to a target system and retrieving deployment status values for the further processing.
A typical scenario of this kind could be a kubernetes setup including a service of type LoadBalancer . Once deployed it gets assigned status information about the IP address or hostname of the assigned load balancer. This information might be required for some other deployment manifest.
A simple template for such a deployment could like this:
```
 service :
  apiVersion : v1
  kind : Service
  metadata :
    annotations :
      dns.mandelsoft.org/dnsnames : echo.test.garden.mandelsoft.org
      dns.mandelsoft.org/ttl : " 500 "
    name : test-service
    namespace : default
  spec :
    ports :
    - name : http
      port : 80
      protocol : TCP
      targetPort : 8080
    sessionAffinity : None
    type : LoadBalancer

deployment :
   testservice : (( sync[pipe_uncached(service, "kubectl", "apply", "-f", "-", "-o", "yaml")|value|->defined(value.status.loadBalancer.ingress)] ))


otherconfig :
   lb : (( deployment.testservice.status.loadBalancer.ingress ))
```

Crazy Shit: Graph Analaysis with spiff

It is easy to describe a simple graph with knots and edges (for example for a set of components and their dependencies) just by using a map of lists.

graph.yaml

 graph :
  a :
  - b
  - c
  b : []
  c :
  - b
  - a
  d :
  - b
  e :
  - d
  - b

Now it would be useful to figure out whether there are dependency cycles or to determine ordered transitive dependencies for a component.

Let's say something like this:

closures.yaml

 graph :
utilities :

closures : (( utilities.graph.evaluate(graph) ))
cycles : (( utilities.graph.cycles(closures) ))

Indeed, this can be done with spiff. The only thing required is a "small utilities stub" .

utilities.yaml

 utilities :
  << : (( &temporary ))
  graph :
    _dep : (( |model,comp,closure|->contains(closure,comp) ? { $deps=[], $err=closure [comp]} :($deps=_._deps(model,comp,closure [comp]))($err=sum[deps|[]|s,e|-> length(s) >= length(e.err) ? s :e.err]) { $deps=_.join(map[deps|e|->e.deps]), $err=err} ))
    _deps : (( |model,comp,closure|->map[model.[comp]|dep|->($deps=_._dep(model,dep,closure)) { $deps=[dep] deps.deps, $err=deps.err }] ))
    join : (( |lists|->sum[lists|[]|s,e|-> s e] ))
    min : (( |list|->sum[list|~|s,e|-> s ? e < s ? e :s :e] ))

    normcycle : (( |cycle|->($min=_.min(cycle)) min ? sum[cycle|cycle|s,e|->s.[0] == min ? s :(s.[1..] [s.[1]])] :cycle  ))
    cycle : (( |list|->list ? ($elem=list.[length(list) - 1]) _.normcycle(sum[list|[]|s,e|->s ? s [e] :e == elem ? [e] :s]) :list ))
    norm : (( |deps|->{ $deps=_.reverse(uniq(_.reverse(deps.deps))), $err=_.cycle(deps.err) } ))
    reverse : (( |list|->sum[list|[]|s,e|->[e] s] ))

    evaluate : (( |model|->sum[model|{}|s,k,v|->s { k=_.norm(_._dep(model,k,[]))}] ))
    cycles : (( |result|->uniq(sum[result|[]|s,k,v|-> v.err ? s [v.err] :s]) ))

And magically spiff does the work just by calling

spiff merge closure.yaml graph.yaml utilities.yaml

And the result is

   closures :
     a :
       deps :
       - c
       - b
       - a
       err :
       - a
       - c
       - a
     b :
       deps : []
       err : []
     c :
       deps :
       - a
       - b
       - c
       err :
       - a
       - c
       - a
     d :
       deps :
       - b
       err : []
     e :
       deps :
       - d
       - b
       err : []
   cycles :
   - - a
     - c
     - a
   graph :
     a :
     - b
     - c
     b : []
     c :
     - b
     - a
     d :
     - b
     e :
     - d
     - b

Отчеты об ошибках

The evaluation of dynaml expressions may fail because of several reasons:

it is not parseable
involved references cannot be satisfied
arguments to operations are of the wrong type
operations fail
there are cyclic dependencies among expressions

If a dynaml expression cannot be resolved to a value, it is reported by the spiff merge operation using the following layout:

	(( <failed expression> ))	in <file>	<path to node>	(<referred path>)	<tag><issue>

Пример

	(( min_ip("10") ))	in source.yml	node.a.[0]	()	*CIDR argument required

Cyclic dependencies are detected by iterative evaluation until the document is unchanged after a step. Nodes involved in a cycle are therefore typically reported just as unresolved node without a specific issue.

The order of the reported unresolved nodes depends on a classification of the problem, denoted by a dedicated tag. The following tags are used (in reporting order):

Ярлык	Значение
`*`	error in local dynaml expression
`@`	dependent or involved in cyclic dependencies
`-`	subsequent error because of refering to a yaml node with an error

Problems occuring during inline template processing are reported as nested problems. The classification is propagated to the outer node.

If a problem occurs in nested lamba calls the call stack together with the lamba function and is local binding is listed.

Пример

	(( 2 + .func(2) ))	in local/err.yaml	value	()	*evaluation of lambda expression failed: lambda|x|->x > 0 ? _(x - 1) : *(template): {x: 2}
		... evaluation of lambda expression failed: lambda|x|->x > 0 ? _(x - 1) : *(template): {x: 1}
		... evaluation of lambda expression failed: lambda|x|->x > 0 ? _(x - 1) : *(template): {x: 0}
		... resolution of template 'template' failed
			(( z ))	in local/err.yaml	val	()*'z' not found

In case of parsing errors in dynaml expressions, the error location is shown now. If it is a multi line expression the line a character/symbol number in that line is show, otherwise the line numer is omitted.

Пример

	((
	  2 ++ .func(2)
	))	in local/err.yaml	faulty	()	*parse error near line 2 symbol 2 - line 2 symbol 3: " "

Using spiff as Go Library

Spiff provides a Go package ( spiffing ) that can be used to include spiff templates in Go programs.

An example program could look like this:

 import (
	"fmt"
	"math"
	"os"

	"github.com/mandelsoft/spiff/dynaml"
	"github.com/mandelsoft/spiff/spiffing"
)

func func_pow ( arguments [] interface {}, binding dynaml. Binding ) ( interface {}, dynaml. EvaluationInfo , bool ) {
	info := dynaml . DefaultInfo ()

	if len ( arguments ) != 2 {
		return info . Error ( "pow takes 2 arguments" )
	}

	a , b , err := dynaml . NumberOperands ( arguments [ 0 ], arguments [ 1 ])

	if err != nil {
		return info . Error ( "%s" , err )
	}
	_ , i := a .( int64 )
	if i {
		r := math . Pow ( float64 ( a .( int64 )), float64 ( b .( int64 )))
		if float64 ( int64 ( r )) == r {
			return int64 ( r ), info , true
		}
		return r , info , true
	} else {
		return math . Pow ( a .( float64 ), b .( float64 )), info , true
	}
}

var state = `
state: {}
`
var stub = `
unused: (( input ))
ages:
  alice: (( pow(2,5) ))
  bob: (( alice + 1 ))
`

var template = `
state:
  <<<: (( &state ))
  random: (( rand("[:alnum:]", 10) )) 
ages: (( &temporary ))

example:
  name: (( input ))  # direct reference to additional values 
  sum: (( sum[ages|0|s,k,v|->s + v] ))
  int: (( pow(2,4) ))
  float: 2.1
  pow: (( pow(1.1e1,2.1) ))
`

func Error ( err error ) {
	if err != nil {
		fmt . Fprintf ( os . Stderr , "Error: %s n " , err )
		os . Exit ( 1 )
	}
}

func main () {
	values := map [ string ] interface {}{}
	values [ "input" ] = "this is an input"

	functions := spiffing . NewFunctions ()
	functions . RegisterFunction ( "pow" , func_pow )

	spiff , err := spiffing . New (). WithFunctions ( functions ). WithValues ( values )
	Error ( err )
	pstate , err := spiff . Unmarshal ( "state" , [] byte ( state ))
	Error ( err )
	pstub , err := spiff . Unmarshal ( "stub" , [] byte ( stub ))
	Error ( err )
	ptempl , err := spiff . Unmarshal ( "template" , [] byte ( template ))
	Error ( err )
	result , err := spiff . Cascade ( ptempl , []spiffing. Node { pstub }, pstate )
	Error ( err )
	b , err := spiff . Marshal ( result )
	Error ( err )
	newstate , err := spiff . Marshal ( spiff . DetermineState ( result ))
	Error ( err )
	fmt . Printf ( "==== new state === n " )
	fmt . Printf ( "%s n " , string ( newstate ))
	fmt . Printf ( "==== result === n " )
	fmt . Printf ( "%s n " , string ( b ))
}

Он поддерживает

transforming file data to and from spiffs internal node representation
the processing of stubs and templates with or without state handling
defining an outer binding for injected path names
defining additional spiff functions
enabling/disabling command execution and/or filesystem operations
using a virtual filesystem for file system operations

Расширять

spiff

Установка

Использование

spiff merge template.yml [template2.yml ...]

spiff diff manifest.yml other-manifest.yml

spiff convert --json manifest.yml

spiff encrypt secret.yaml

Флаги функций

Библиотеки

Язык шаблонов dynaml

(( foo ))

(( foo.bar.[1].baz ))

(( foo.[bar].baz ))

(( list.[1..3] ))

(( 1.2e4 ))

(( "foo" ))

(( [ 1, 2, 3 ] ))

(( { "alice" = 25 } ))

(( ( "alice" = 25 ) alice ))

(( foo bar ))

(( "foo" bar ))

(( [1,2] bar ))

(( map1 map2 ))

(( auto ))

(( merge ))

<<: (( merge ))

Объединение карт

Объединение списков

- <<: (( merge on key ))

<<: (( merge replace ))

Объединение карт

Объединение списков

<<: (( foo ))

Объединение карт

Объединение списков

<<: (( merge foo ))

Объединение карт

Объединение списков

<<: (( merge none ))

(( a || b ))

(( 1 + 2 * foo ))

(( "10.10.10.10" - 11 ))

(( a > 1 ? foo :bar ))

(( 5 -or 6 ))

Функции

(( format( "%s %d", alice, 25) ))

(( join( ", ", list) ))

(( split( ",", string) ))

(( trim(string) ))

(( element(list, index) ))

(( element(map, key) ))

(( compact(list) ))

(( uniq(list) ))

(( contains(list, "foobar") ))

(( basename(path) ))

(( dirname(path) ))

(( parseurl("http://github.com") ))

(( index(list, "foobar") ))

(( lastindex(list, "foobar") ))

`((sort (list)))

(( replace(string, "foo", "bar") ))

(( substr(string, 1, 2) ))

(( match("(f.*)(b.*)", "xxxfoobar") ))

(( keys(map) ))

(( length(list) ))

(( base64(string) ))

(( hash(string) ))

(( bcrypt("password", 10) ))

(( bcrypt_check("password", hash) ))

(( md5crypt("password") ))

(( md5crypt_check("password", hash) ))

(( decrypt("secret") ))

(( rand("[:alnum:]", 10) ))

(( type(foobar) ))

(( defined(foobar) ))

(( valid(foobar) ))

(( require(foobar) ))

(( stub(foo.bar) ))

(( tagdef("tag", value) ))

(( eval(foo "." bar ) ))

`spiff merge template.yml [template2.yml ...]`

`spiff diff manifest.yml other-manifest.yml`

`spiff convert --json manifest.yml`

`spiff encrypt secret.yaml`

`(( foo ))`

`(( foo.bar.[1].baz ))`

`(( foo.[bar].baz ))`

`(( list.[1..3] ))`

`(( 1.2e4 ))`

`(( "foo" ))`

`(( [ 1, 2, 3 ] ))`

`(( { "alice" = 25 } ))`

`(( ( "alice" = 25 ) alice ))`

`(( foo bar ))`

`(( "foo" bar ))`

`(( [1,2] bar ))`

`(( map1 map2 ))`

`(( auto ))`

`(( merge ))`

`<<: (( merge ))`

`- <<: (( merge on key ))`

`<<: (( merge replace ))`

`<<: (( foo ))`

`<<: (( merge foo ))`

`<<: (( merge none ))`

`(( a || b ))`

`(( 1 + 2 * foo ))`

`(( "10.10.10.10" - 11 ))`

`(( a > 1 ? foo :bar ))`

`(( 5 -or 6 ))`

`(( format( "%s %d", alice, 25) ))`

`(( join( ", ", list) ))`

`(( split( ",", string) ))`

`(( trim(string) ))`

`(( element(list, index) ))`

`(( element(map, key) ))`

`(( compact(list) ))`

`(( uniq(list) ))`

`(( contains(list, "foobar") ))`

`(( basename(path) ))`

`(( dirname(path) ))`

`(( parseurl("http://github.com") ))`

`(( index(list, "foobar") ))`

`(( lastindex(list, "foobar") ))`

`(( replace(string, "foo", "bar") ))`

`(( substr(string, 1, 2) ))`

`(( match("(f.)(b.)", "xxxfoobar") ))`

`(( keys(map) ))`

`(( length(list) ))`

`(( base64(string) ))`

`(( hash(string) ))`

`(( bcrypt("password", 10) ))`

`(( bcrypt_check("password", hash) ))`

`(( md5crypt("password") ))`

`(( md5crypt_check("password", hash) ))`

`(( decrypt("secret") ))`

`(( rand("[:alnum:]", 10) ))`

`(( type(foobar) ))`

`(( defined(foobar) ))`

`(( valid(foobar) ))`

`(( require(foobar) ))`

`(( stub(foo.bar) ))`

`(( tagdef("tag", value) ))`

`(( eval(foo "." bar ) ))`

`(( env("HOME" ) ))`

`(( parse(yamlorjson) ))`

`(( asjson(expr) ))`

`(( catch(expr) ))`

`(( static_ips(0, 1, 3) ))`

`(( ipset(ranges, 3, 3,4,5,6) ))`

`(( list_to_map(list, "key") ))`

`(( makemap(fieldlist) ))`

`(( makemap(key, value) ))`

`(( merge(map1, map2) ))`

`(( intersect(list1, list2) ))`

`(( reverse(list) ))`

`(( validate(value,"dnsdomain") ))`

`(( check(value,"dnsdomain") ))`

`(( error("message") ))`

`(( read("file.yml") ))`