Ускоренный курс по YAML

Потому что, видимо, нет никаких хороших.

SS14 использует YAML для определений прототипов. Это как JSON, но на самом деле предназначенный для написания маргинально-разумными углеродными формами жизни вроде нас с вами.

Комментарии

Ладно, прежде всего, вы можете создать однострочный комментарий, поставив # где угодно, всё после него полностью игнорируется. Пример:

foo: bar # Вот комментарий.

Типы данных

Для наших целей в YAML есть вроде как 3 типа данных: строки, списки и словари. Если вы знаете о YAML достаточно, чтобы понимать, что это неправда, пролистайте вниз до объяснения.

Строка

Определить строку легко, вы просто пишете её там.

hello

Молодец, ты мастер YAML, ты определил строку с содержимым hello.

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

"hello: hi"

Всё ещё одна строка.

Двойные кавычки (") допускают escape-последовательности, такие как наш друг \n (перевод строки), одинарные кавычки (') - нет.

Список

Определение списка выполняется просто постановкой - перед чем-то другим, например строкой:

- A
- B
- C

Это определяет список из 3 элементов: A, B и C. Вау! Значения - это обычные строки, и вы можете вытворять любые шалости: кавычки или что угодно.

Ужасные советы: Вы также можете определять YAML инлайн. Вместо вышеприведённого вы также можете написать:

   [A, B, C]

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

   x: [ DoAct ]

Словарь

И наконец у нас есть словари, которые представляют собой просто сопоставление ключ/значение. Так вы можете сделать A равным B, а C равным D. Просто используйте двоеточия (:) для определения вот так:

A: B
C: D

Вжух. Значения здесь (и ключ, и значение!) ТОЖЕ являются обычными строками, так что вы можете сделать и так:

"A": "B"
"C": "D"

Чудеса современной технологии.

Ужасные советы: Как и списки, словари тоже можно определять инлайн. 

{ A: B, C: D}

Если вы сейчас думаете: “Погодите-ка, инлайн YAML - это же просто JSON.” Вы правы. YAML - это надмножество JSON, и на самом деле вы можете просто парсить JSON-файлы как YAML напрямую, если хотите.

Вложенность

Эй, оказывается, что вместо строк вы также можете использовать словари и списки.

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

Когда у вас есть список, вы можете поместить словарь в элемент, сделав отступ. Так вы можете сделать следующее:

# Вот так, первый ключ на той же строке.
- A: B
  X: "Y"

На самом деле это просто логично.

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

A:
- "X"
- "Y"
- "Z"

B:
- "U"
- "V"
- "W"

Легко.

И ура, вы можете смешивать и сочетать:

Warning

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


# Во-первых, вся эта штука хранится в огромном списке. Вот почему стоит -.
# Мы смотрим на одну запись, словарь.
- type: entity # Простые пары ключ/значение.
  id: SMES
  name: SMES
  description: Stores power in its super-magnetic cells
  components:
  # АГА! Список внутри ключа. Вау!
  # Этот список ТАКЖЕ хранит словари.
  - type: Sprite
    sprite: Buildings/smes.rsi
    scale: 2, 2
    layers:
    - state: smes
    - state: smes-display
      shader: unshaded
    # Входящий свет.
    - shader: unshaded
      state: smes-oc0
    # Индикатор заряда.
    - visible: false
      shader: unshaded
      state: smes-og1
    # Исходящий свет.
    - shader: unshaded
      state: smes-op0
  - type: Icon
    sprite: Buildings/smes.rsi
    state: smes

Примечания

На самом деле у YAML гораздо больше типов данных. YAML также беспорядочен. Есть более 10 способов определить строки. Вся спецификация занимает более 100 страниц и переусложнена.

Ужасные советы: Кстати о типах данных:

    behaviors:
    - !type: HeartBehavior {}

Чему соответствует !type? Классу в SpaceStation14 и/или RobustToolbox. На C#. Это, конечно, сбивает с толку любой валидатор YAML, который пытается найти схему тегов YAML для него. Будьте осторожны при автоформатировании .yml-ресурсов.

SS14 не использует прямую десериализацию объектов, и YamlDotNet (библиотека, которую мы используем для парсинга YAML) достаточно любезна, чтобы трактовать скаляры только как строки. Он не пытается парсить строки как числа или что-то ещё при использовании API “YAML to LINQ” (как я люблю его называть, “разумный, который не совсем бесполезен для практического использования”). Парсинг чисел выполняется нашим собственным кодом на C# на месте, так что если код ожидает boolean, он правильно обработает true и false, а если он ожидает строку, он просто увидит её как строку.

Subpages