ЯМЛ

Информацию о платформе CSS см. в разделе YAML (фреймворк) .

ЯМЛ

Расширения имен файлов	.yaml, .yml
Тип интернет-СМИ	application/yaml
Единый идентификатор типа (UTI)	public.yaml
Первоначальный выпуск	11 мая 2001 г ( 11.05.2001 )
Последний выпуск	1.2 (Версия 1.2.2) 1 октября 2021 г ( 01.10.2021 )
Тип формата	Обмен данными
Открытый формат ?	Да
Веб-сайт	ямл .org

YAML ( / ˈ j æ m ə l / ; см. § История и название ) — удобочитаемый язык сериализации данных . Он обычно используется для файлов конфигурации и в приложениях, где данные хранятся или передаются. YAML предназначен для многих из тех же коммуникационных приложений, что и расширяемый язык разметки (XML), но имеет минимальный синтаксис, который намеренно отличается от стандартного обобщенного языка разметки (SGML). Он использует Python для обозначения вложенности. отступы в стиле и не требует кавычек для большинства строковых значений (он также поддерживает JSON ). стиль [...] и } смешанные в одном файле).

Пользовательские типы данных разрешены, но YAML изначально кодирует скаляры (такие как строки , целые числа и числа с плавающей запятой ), списки и ассоциативные массивы (также известные как карты, словари или хеши). Эти типы данных основаны на языке программирования Perl , хотя все широко используемые языки программирования высокого уровня имеют очень схожие концепции. Синтаксис с двоеточием, используемый для выражения пар ключ-значение , основан на заголовках электронной почты, как определено в RFC   822 и разделитель документов. --- заимствовано из MIME ( RFC   2046 ). Escape-последовательности повторно используются из C , а перенос пробелов для многострочных строк вдохновлен HTML . Списки и хеши могут содержать вложенные списки и хеши, образующие древовидную структуру ; произвольные графы могут быть представлены с использованием псевдонимов YAML (аналогично XML в SOAP ). YAML предназначен для чтения и записи в виде потоков — функция, вдохновленная SAX .

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

Официальное рекомендуемое расширение имени файла YAML: .yaml с 2006 года. В 2024 году тип MIME application/yaml был завершен.

История и название

YAML ( / ˈ j æ m əl / рифмуется со словом верблюд ) был впервые предложен Кларком Эвансом в 2001 году, который разработал его вместе с Ingy döt Net и Орен Бен-Кики. Первоначально считалось, что YAML означает «еще один язык разметки» . потому что он был выпущен в эпоху распространения языков разметки для представления и связи (HTML, XML, SGML и т. д.). Его первоначальное название было задумано как насмешливая отсылка. в технологическую среду, ссылаясь на его цель как язык разметки с еще одной конструкцией, но затем он был перепрофилирован как YAML Ain't Markup Language , рекурсивная аббревиатура , чтобы отличать его цель как ориентированную на данные, а не разметку документов.

Версии

Версия	Дата выпуска
ЯМЛ 1.0	29 января 2004 г.
ЯМЛ 1.1	18 января 2005 г.
ЯМЛ 1.2.0	21 июля 2009 г.
ЯМЛ 1.2.1	1 октября 2009 г.
ЯМЛ 1.2.2	1 октября 2021 г.

Дизайн

Синтаксис

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

YAML принимает весь набор символов Юникода, за исключением некоторых управляющих символов , и может быть закодирован в любом из UTF-8 , UTF-16 или UTF-32 . (Хотя UTF-32 не является обязательным, синтаксический анализатор должен иметь совместимость с JSON .)

• пробелов Отступы используются для обозначения структуры; однако символы табуляции в этом отступе не допускаются.
• Комментарии начинаются со знака номера ( #), может начинаться в любом месте строки и продолжаться до конца строки. Комментарии должны быть отделены от других токенов пробелами. Если # символы встречаются внутри строки, то это числовой знак ( #) литералы.
• Члены списка обозначаются дефисом в начале ( -) с одним членом в строке.
  • Список также можно указать, заключив текст в квадратные скобки ( [...]) с каждой записью, разделенной запятой .
• Запись ассоциативного массива представляется с использованием в двоеточия форме ключ: значение с одной записью в строке. YAML требует, чтобы после двоеточия следовал пробел, чтобы строки в стиле URL-адреса, такие как http://www.wikipedia.org могут быть представлены без заключения в кавычки.
  • кавычек . Перед ключом можно использовать вопросительный знак в форме «?ключ: значение», чтобы ключ мог содержать ведущие тире, квадратные скобки и т. д. без
  • Ассоциативный массив также можно задать текстом, заключенным в фигурные скобки ( {...}), где ключи отделяются от значений двоеточием, а записи — запятыми (пробелы не требуются для обеспечения совместимости с JSON).
• Строки (один из типов скаляров в YAML) обычно не заключаются в кавычки, но могут быть заключены в двойные кавычки ( ") или одинарные кавычки ( ').
  • В двойных кавычках специальные символы могут быть представлены с помощью escape-последовательностей в стиле C, начинающихся с обратной косой черты ( \). Согласно документации, поддерживается только восьмеричный escape. \0.
  • Внутри одинарных кавычек единственной поддерживаемой escape-последовательностью является двойная одинарная кавычка ( ''), обозначающий саму одинарную кавычку, как в 'don''t'.
• Блочные скаляры разделяются отступами с дополнительными модификаторами для сохранения ( |) или сложить ( >) новые строки.
• Несколько документов в одном потоке разделяются тремя дефисами ( ---).
  • Три периода ( ...) опционально завершает документ внутри потока.
• Повторяющиеся узлы изначально обозначаются амперсандом ( &) и после этого обозначается звездочкой ( *).
• Узлы могут быть помечены типом или тегом с использованием двойного восклицательного знака ( !!), за которым следует строка, которую можно расширить до URI.
• Документам YAML в потоке могут предшествовать «директивы», состоящие из знака процента ( %), за которым следует имя и параметры, разделенные пробелами. В YAML 1.1 определены две директивы:
  • Директива %YAML используется для идентификации версии YAML в данном документе.
  • Директива %TAG используется как ярлык для префиксов URI. Эти ярлыки затем можно использовать в тегах типов узлов.

Основные компоненты

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

--- # Favorite movies
- Casablanca
- North by Northwest
- The Man Who Wasn't There

Необязательный встроенный формат разделяется запятой+пробелом и заключен в скобки (аналогично JSON ).

--- # Shopping list
[milk, pumpkin pie, eggs, juice]

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

--- # Indented Block
  name: John Smith
  age: 33
--- # Inline Block
{name: John Smith, age: 33}

Строки не требуют кавычек. Существует два способа записи многострочных строк: один с сохранением новой строки (с использованием оператора | символ) и тот, который сворачивает символы новой строки (с помощью > символ), за которыми следует символ новой строки.

data: |
   There once was a tall man from Ealing
   Who got on a bus to Darjeeling
       It said on the door
       "Please don't sit on the floor"
   So he carefully sat on the ceiling

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

data: >
   Wrapped text
   will be folded
   into a single
   paragraph

   Blank lines denote
   paragraph breaks

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

--- # The Smiths
- {name: John Smith, age: 33}
- name: Mary Smith
  age: 27
- [name, age]: [Rae Smith, 4]   # sequences as keys are supported
--- # People, by gender
men: [John Smith, Bill Jones]
women:
  - Mary Smith
  - Susan Williams

Объекты и списки являются важными компонентами yaml и их можно смешивать. Первый пример — это список объектов «ключ-значение», включающих всех людей из семьи Смитов. Во втором они перечислены по полу; это объект «ключ-значение», содержащий два списка.

Расширенные компоненты

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

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

Для ясности, компактности и предотвращения ошибок при вводе данных YAML предоставляет привязки узлов (с помощью &) и ссылки (с использованием *). Ссылки на якорь работают для всех типов данных (см. ссылку на место доставки в примере ниже).

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

--- # Sequencer protocols for Laser eye surgery
- step:  &id001                  # defines anchor label &id001
    instrument:      Lasik 2000
    pulseEnergy:     5.4
    pulseDuration:   12
    repetition:      1000
    spotSize:        1mm

- step: &id002
    instrument:      Lasik 2000
    pulseEnergy:     5.0
    pulseDuration:   10
    repetition:      500
    spotSize:        2mm
- Instrument1: *id001   # refers to the first step (with anchor &id001)
- Instrument2: *id002   # refers to the second step

Явная типизация данных редко встречается в большинстве документов YAML, поскольку YAML автоматически определяет простые типы. Типы данных можно разделить на три категории: основные, определенные и определяемые пользователем. Ядро — это те, которые, как ожидается, существуют в любом парсере (например, числа с плавающей запятой, целые числа, строки, списки, карты и т. д.). Многие более сложные типы данных, такие как двоичные данные, определены в спецификации YAML, но поддерживаются не во всех реализациях. Наконец, YAML определяет способ локального расширения определений типов данных для размещения определяемых пользователем классов, структур или примитивов (например, чисел с плавающей запятой четырехкратной точности).

YAML автоматически определяет тип данных объекта, но иногда требуется явно указать тип данных. Наиболее распространенная ситуация — когда строка из одного слова, которая выглядит как число, логическое значение или тег, требует устранения неоднозначности, заключая ее в кавычки или используя тег явного типа данных.

---
a: 123                     # an integer
b: "123"                   # a string, disambiguated by quotes
c: 123.0                   # a float
d: !!float 123             # also a float via explicit data type prefixed by (!!)
e: !!str 123               # a string, disambiguated by explicit type
f: !!str Yes               # a string via explicit type
g: Yes                     # a boolean True (yaml1.1), string "Yes" (yaml1.2)
h: Yes we have No bananas  # a string, "Yes" and "No" disambiguated by context.

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

---
picture: !!binary |
  R0lGODdhDQAIAIAAAAAAANn
  Z2SwAAAAADQAIAAACF4SDGQ
  ar3xxbJ9p0qa7R0YxwzaFME
  1IAADs=

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

Пример

Иерархия структуры данных поддерживается за счет контурных отступов.

---
receipt:     Oz-Ware Purchase Invoice
date:        2012-08-06
customer:
    first_name:   Dorothy
    family_name:  Gale

items:
    - part_no:   A4786
      descrip:   Water Bucket (Filled)
      price:     1.47
      quantity:  4

    - part_no:   E1628
      descrip:   High Heeled "Ruby" Slippers
      size:      8
      price:     133.7
      quantity:  1

bill-to:  &id001
    street: |
            123 Tornado Alley
            Suite 16
    city:   East Centerville
    state:  KS

ship-to:  *id001

specialDelivery:  >
    Follow the Yellow Brick
    Road to the Emerald City.
    Pay no attention to the
    man behind the curtain.
...

Обратите внимание, что строки не требуют заключения в кавычки. Конкретное количество пробелов в отступе не имеет значения, если параллельные элементы имеют одинаковое выравнивание по левому краю, а иерархически вложенные элементы имеют больший отступ. В этом образце документа определяется ассоциативный массив с 7 ключами верхнего уровня: один из ключей, «элементы», содержит список из двух элементов, каждый элемент которого сам по себе является ассоциативным массивом с разными ключами. Отображаются реляционные данные и удаление избыточности: содержимое ассоциативного массива «отправитель» копируется из содержимого ассоциативного массива «получатель счета», как указано привязкой ( &) и ссылка ( *) этикетки. Для удобства чтения можно добавить дополнительные пустые строки. Несколько документов могут существовать в одном файле/потоке и разделяться ---. Дополнительный ... может использоваться в конце файла (полезно для сигнализации окончания потоковой передачи данных без закрытия канала).

Функции

Разделитель с отступом

Поскольку YAML в первую очередь полагается на контурные отступы для структуры, он особенно устойчив к коллизиям разделителей . Нечувствительность YAML к кавычкам и фигурным скобкам в скалярных значениях означает, что можно встраивать документы XML, JSON или даже YAML в документ YAML, просто делая отступ в блочном литерале (используя | или >):

---
example: >
        HTML goes into YAML without modification
message: |

        <blockquote style="font: italic 1em serif">
        <p>"Three is always greater than two,
           even for large values of two"</p>
        <p>--Author Unknown</p>
        </blockquote>
date: 2007-06-01

YAML можно поместить в JSON, заключив в кавычки и экранируя все внутренние кавычки. YAML можно поместить в XML, экранируя зарезервированные символы ( <, >, &, ', ") и преобразуя пробелы или помещая их в раздел CDATA .

Неиерархические модели данных

В отличие от JSON, который может представлять данные только в иерархической модели, где каждый дочерний узел имеет одного родительского узла, YAML также предлагает простую реляционную схему, которая позволяет ссылаться на повторы идентичных данных из двух или более точек дерева, а не вводить их избыточно. эти точки. Это похоже на функцию IDREF, встроенную в XML. Затем анализатор YAML расширяет эти ссылки до полностью заполненных структур данных, которые они подразумевают при считывании, поэтому какой бы программе, которая использует анализатор, не обязательно знать о модели реляционного кодирования, в отличие от процессоров XML, которые не расширяют ссылки. Это расширение может улучшить читаемость и одновременно уменьшить количество ошибок при вводе данных в файлах конфигурации или протоколах обработки, где многие параметры остаются неизменными в последовательной серии записей, а изменяются лишь немногие. Например, записи «Кому-отправитель» и «Получатель счета» в счете-фактуре почти всегда представляют собой одни и те же данные.

Практические соображения

YAML является построчно-ориентированным, поэтому часто легко преобразовать неструктурированный вывод существующих программ в формат YAML, сохраняя при этом большую часть внешнего вида исходного документа. Поскольку здесь нет закрывающих тегов, фигурных скобок или кавычек, которые нужно было бы сбалансировать, обычно легко сгенерировать правильно сформированный YAML непосредственно из распределенных операторов печати в несложных программах. Аналогичным образом, разделители-пробелы облегчают быструю фильтрацию файлов YAML с использованием строковых команд в grep, AWK, Perl, Ruby и Python.

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

Как ни странно, хотя разделение с отступами может показаться усложняющим глубоко вложенные иерархии, YAML обрабатывает отступы размером до одного пробела, и это может обеспечить лучшее сжатие, чем языки разметки. Кроме того, чрезвычайно глубоких отступов можно полностью избежать, выполнив следующие действия: 1) вернувшись к «встроенному стилю» (т. е. JSON-подобному формату) без отступов; или 2) использование реляционных привязок для преобразования иерархии в плоскую форму, которую синтаксический анализатор YAML прозрачно преобразует в полную структуру данных.

Безопасность

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

Однако YAML допускает использование тегов, специфичных для языка, поэтому синтаксический анализатор, поддерживающий эти теги, может создавать произвольные локальные объекты. Любой синтаксический анализатор YAML, который позволяет выполнять сложное создание экземпляров объектов, открывает потенциальную возможность атаки путем внедрения. Парсеры Perl, позволяющие загружать объекты произвольных классов, создают так называемые «благословенные» значения. Использование этих значений может вызвать неожиданное поведение, например, если класс использует перегруженные операторы. Это может привести к выполнению произвольного кода Perl.

Ситуация аналогична для парсеров Python или Ruby. Согласно документации PyYAML:

Обратите внимание, что возможность создания произвольного объекта Python может быть опасной, если вы получаете документ YAML из ненадежного источника, например из Интернета. Функция yaml.safe_load ограничивает эту возможность простыми объектами Python, такими как целые числа или списки. [...]

PyYAML позволяет создавать объекты Python любого типа. Даже экземпляры классов Python могут быть созданы с использованием !!python/object ярлык.

Обработка и представление данных

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

Более того, при определении соответствия процессоров YAML спецификация YAML определяет две основные операции: дамп и загрузку . Все процессоры, совместимые с YAML, должны обеспечивать хотя бы одну из этих операций или при необходимости могут обеспечивать обе. Наконец, спецификация YAML определяет информационную модель или «граф представления», который должен быть создан во время обработки как для операций дампа , так и для операций загрузки , хотя это представление не обязательно должно быть доступно пользователю через API.

Сравнение с другими форматами сериализации

Сравнение с JSON

См. также: JSON § YAML.

Синтаксис JSON лежит в основе YAML версии 1.2, которая была опубликована с явной целью привести YAML «в соответствие с JSON как официальным подмножеством». Хотя предыдущие версии YAML не были строго совместимы, расхождения редко были заметны, и большинство документов JSON можно анализировать некоторыми анализаторами YAML, такими как Syck. Это связано с тем, что семантическая структура JSON эквивалентна необязательному «встроенному стилю» написания YAML. Хотя расширенные иерархии могут быть написаны во встроенном стиле, например JSON, этот стиль YAML не рекомендуется, за исключением тех случаев, когда он способствует ясности.

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

Благодаря лаконичности и десериализация JSON сериализация происходит намного быстрее, чем YAML.

Сравнение с ТОМЛ

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

Сравнение с XML

В YAML отсутствует понятие атрибутов тегов, которые можно найти в XML. Вместо этого YAML имеет расширяемые объявления типов (включая типы классов для объектов).

Сам YAML не имеет дескрипторов схемы документа, определяемых языком XML, которые позволяют, например, документу самопроверяться. Однако существует несколько внешне определяемых языков дескрипторов схемы для YAML (например, Doctrine , Kwalify и Rx), которые выполняют эту роль. Более того, семантика, обеспечиваемая объявлениями типов, определяемыми языком YAML, в самом документе YAML, часто снижает потребность в валидаторе в простых и распространенных ситуациях. Кроме того, YAXML , который представляет структуры данных YAML в XML, позволяет импортеры схем XML и механизмы вывода, такие как XSLT применять к YAML .

Сравнение форматов сериализации данных обеспечивает более полное сравнение YAML с другими форматами сериализации.

Программное обеспечение (эмиттеры и парсеры)

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

Эмиттеры и парсеры YAML существуют для многих популярных языков. Большинство из них написано на родном языке. Некоторые из них являются языковыми привязками библиотеки C libyaml ; они могут бежать быстрее. Раньше существовала еще одна библиотека C, называемая Syck , написанная и осиротевшая по воле счастливчика : она не поддерживается, нет авторитетного исходного пакета, а веб-сайт был взломан. Следовательно, единственной рекомендуемой библиотекой C является libyaml . Первоначально он был разработан Кириллом Симоновым. В 2018 году разработку возобновили новые сопровождающие Ян Кордаско и Инги Дёт Нет.

Программисты C++ имеют выбор между библиотекой C libyaml и библиотекой C++ libyaml-cpp . Оба имеют полностью независимые базы кода и совершенно разные API . Библиотека libyaml-cpp по-прежнему имеет основной номер версии 0, что указывает на то, что API может измениться в любой момент, как это действительно произошло после версии 0.3. Существует реализация, ориентированная на грамматику, написанная на C#, с целью расширения вложенных элементов.

Некоторые реализации YAML, такие как Perl YAML.pm, загружают целый файл (поток) и анализируют его массово . Другие реализации, такие как PyYaml, ленивы и перебирают следующий документ только по запросу. Для очень больших файлов, в которых планируется обрабатывать документы независимо, создание экземпляра всего файла перед обработкой может оказаться невозможным. Таким образом, в YAML.pm иногда приходится разбивать файл на документы и анализировать их по отдельности. YAML упрощает это, поскольку для этого просто требуется разбить маркер конца документа, который определяется как три точки в начале строки, за которыми следует пробел (и, возможно, комментарий). Этот маркер запрещен по содержанию.

Критика

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

• Файлы конфигурации могут выполнять команды или загружать содержимое незаметно для пользователей.
• Редактировать большие файлы YAML сложно, поскольку ошибки отступов могут остаться незамеченными.
• Автоопределение типа является источником ошибок. Например, без кавычек Yes и No преобразуются в логические значения; номера версий программного обеспечения могут быть преобразованы в числа с плавающей запятой.
• Усеченные файлы часто интерпретируются как действительные YAML из-за отсутствия терминаторов.
• Сложность стандарта привела к противоречивым реализациям и сделала язык непереносимым.

Осознанные недостатки и сложность YAML привели к появлению более строгих альтернатив, таких как StrictYAML и NestedText .

См. также

• Сравнение форматов сериализации данных
• Легкий язык разметки

Внешние ссылки

• Официальный сайт
• YAMLскрипт