Как читать статью оператора

Каждая статья оператора содержит:

• Вид — трансформер (перестраивает значение) или фильтр (отбирает/отбрасывает значения до маппинга).
• Обработка значения — как оператор трактует скалярный, массивный и объектный вход:
  • per-item — применяется к скаляру напрямую; над массивом обрабатывает поэлементно (элементы неподходящего типа проходят насквозь без изменений).
  • whole-value — работает со значением как с единым целым независимо от его формы.
  • array — ориентирован на массив; вход, не являющийся массивом, проходит насквозь без изменений (если не указано иное).
  • item-filter — операторы-фильтры: массив фильтруется поэлементно; скаляр трактуется как один элемент, а не прошедший фильтр скаляр отбрасывается (становится отсутствующим, поэтому правило маппинга откатывается к своему значению по умолчанию).
• Аргументы — имя, тип (string / number / boolean / json), его обязательность и значение по умолчанию, используемое при его отсутствии.
• Поведение, крайние случаи и один разобранный Пример (input + аргументы → output).

Общие соглашения (верны для каждого оператора, если в статье не сказано иное):

• Несоответствие типа — это проброс, а не ошибка. Строковый оператор, получивший число, оператор массива, получивший объект, оператор даты, получивший неразбираемую строку, и т. п. возвращают вход без изменений. Операторы никогда не выбрасывают исключение на пути ingest; действительно сбойное правило откатывается согласно собственной политике ошибок.
• null / отсутствующий вход. Отсутствующий исходный путь не даёт значения; правило маппинга применяет своё значение по умолчанию до запуска трансформеров. Большинство трансформеров возвращают вход null/отсутствие без изменений. Операторы-предикаты (семейство is*) сначала приводят через String(value), поэтому null становится текстом "null".
• Неизменяемость. Операторы объектов и массивов никогда не мутируют вход; они возвращают новое значение.
• Безопасность регулярных выражений. Каждый аргумент-регулярное выражение проверяется при сохранении и повторно во время выполнения защитой от ReDoS (шаблоны длиннее 512 символов или с вложенными неограниченными квантификаторами вроде (a+)+ отклоняются). Отклонённый или некорректный шаблон делает оператор безопасной no-op-операцией (он возвращает вход или не срабатывает), не рискуя неконтролируемым разрастанием сопоставления.
• Синонимы аргументов. Некоторые аргументы принимают альтернативные имена (например, dt также принимает expression или path). Синонимы перечислены в таблице аргументов.

Алфавитный указатель

Разделы руководства

• 1. Строковые трансформеры (String)
• 2. Трансформеры списков и массивов (List & array)
• 3. Объектные трансформеры (Object)
• 4. Трансформеры даты и времени (Date & time)
• 5. Числовые и математические трансформеры (Number & math)
• 6. Трансформеры конвертации и кодирования (Conversion & encoding)
• 7. Сетевые трансформеры и IOC (Network & IOC)
• 8. Условные и контентные трансформеры (Conditional & content)
• 9. Фильтры (where-операторы)