YML и все-все-все...

Как можно заметить, уровень вложенности элементов в данном примере регулируется не знаками препинания, как это принято в нормальных языках программирования, а сдвигом на два пробела вправо относительно начала строки. Таким образом, элемент settings для всех остальных является корневым и содержит в качестве дочерних элементы различных типов: логические (debug: false), строковые (restart-script: ./start.sh), целочисленные (sample-count: 12) и дробные (moved-wrongly-threshold: 0.0625). Кроме того, он также содержит в себе другие комплексные элементы (например, attribute), которые, в свою очередь, также включают в себя набор дочерних элементов. Причем эти дочерние элементы сдвинуты еще на два пробела вправо (maxHealth, movementSpeed, attackDamage), что говорит интерпретатору о том, что они принадлежат не корневому элементу settings, а его дочернему элементу attribute, который обрабатывается в данный момент.

Описание каждого элемента данных состоит из его имени и значения, указанного через двоеточие с пробелом (!). Комплексные элементы (имеющие дочерние подэлементы) могут иметь формат как именованного списка (как в вышеприведенном примере), так и неименованного списка, в котором подэлементы перечисляются следующим образом (опять же ведущие пробелы и пробел между тире и значением заменены на точки):

..replace-commands:
..-.setblock
..-.summon
..-.testforblock
..-.tellraw

Обратите внимание, подэлементы комплексного элемента replace-commands не имеют имен, только значения. И все равно относительно родительского элемента эти значения сдвинуты на два символа вправо, только в вместо первого пробела указывается символ '-' как признак элемента неименованного списка. Обычно именованные списки YML-формата называются ассоциативными массивами, а неименованные - просто списками или массивами.

Текст конфигурационных файлов YML-формата можно и нужно разбавлять комментариями, для этого используется знак #, все что расположено после него до конца строки считается комментарием. Комментарий можно вставлять в любом месте YML-файла.

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

Лучше всего для редактирования YML-файлов подходит Notepad++. Во-первых, это сам по себе отличная замена виндовому нотпаду. Во-вторых, у него есть подсветка синтаксиса всех основных текстовых форматов и языков программирования. Не обошли вниманием и YML. В третьих, он отлично поддерживает функцию "смарт-таб", автоматически вставляя нужное количество пробелов (или символов табуляции) при переходе на новую строку. И в четвертых, для каждого типа файлов у него можно включить или отключить преобразование табуляции в пробелы и определить количество заменяемых пробелов. После этого в YML-файлах уровень вложенности можно увеличивать (и уменьшать) просто нажатием клавиши "Таб" (альт-таб).

Вот такой интересный формат. Со своими недостатками (серьезными, на мой взгляд), но, тем не менее, позволяющий описывать достаточно серьезные структуры (имеется опыт создания YML-конфига на 3500 строк - нормально работает, как ни странно).

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

[
  {
    "uuid": "27a854c8-8965-4d2a-a6fd-23e64dfdc825",
    "name": "MrBadBoy",
    "created": "2015-07-23 20:13:51 +0400",
    "source": "operator",
    "expires": "forever",
    "reason": "нарушение правил сервера"
  },
  {
    "uuid": "7675832b-a75b-291c-fb09-3b1a043f35fa",
    "name": "_SuPeR_NaGiBaToR_",
    "created": "2015-08-16 12:28:47 +0400",
    "source": "admin",
    "expires": "forever",
    "reason": "неадекватность"
  }
]

Основные моменты при написании конфига в формате JSON следующие:

• символы пробела, переноса строки и табуляции в обработке не участвуют и могут вставляться в любом месте и в любом количестве для улучшения читабельности
• объект - это ассоциативный массив, список подэлементов (именованных) которого заключается в фигурные скобки (перечисляются через запятую в виде пар "ключ: значение").
• массив - это неименованный список, значения которого заключаются в прямые скобки, где перечисляются через запятую.
• названия элементов заключаются в двойные кавычки (некоторые JSON-парсеры допускают использование одинарных кавычек, но лучше соблюдать стандарт оформления).
• значения элементов могут представлять собой строковое значение (заключенное в двойные кавычки), целое или дробное число, логический литерал true или false, определяющем логическое значение, а также литерал null, определяющий нулевое значение. Кроме того, в качестве значения может выступать вложенный объект в фигурных скобках или вложенный массив в прямых скобках.

Корневым элементом JSON структуры может являться либо объект либо массив, то есть весь конфиг в JSON-формате должен быть обернут либо в прямые либо в фигурные скобки.

В остальном, на форматирование JSON-структуры не налагается никаких ограничений, одинаково правильно работает как структура, приведенная выше, так и ее сжатый аналог:

[{"uuid":"27a854c8-8965-4d2a-a6fd-23e64dfdc825","name":"MrBadBoy","created":"2015-07-2320:13:51+0400","source":"operator","expires":"forever","reason":"нарушение правил сервера"},{"uuid":"7675832b-a75b-291c-fb09-3b1a043f35fa","name":"_SuPeR_NaGiBaToR_","created":"2015-08-1612:28:47+0400","source":"admin","expires":"forever","reason":"неадекватность"}]

Эта особенность позволяет использовать JSON как формат описания данных, передаваемых по сети, в частности, он активно используется в веб-технологиях (см. AJAX). Он же используется в запросах на моджанговские серверы, когда требуется, например, по UUID персонажа получить список его переименований.

И YML и JSON прекрасно парсятся стандартными средствами явы, на выходе получается древовидная структура, состоящая в основном из объектов Map<String,Object> либо массивов (списков) List<Object>, дальнейшая обработка которых при наличии минимальных навыков не представляет труда. Все это также работает и в обратную сторону: на выходе можно получить либо YML-файл либо JSON-строку.

В качестве примеров обоих форматов можете заглянуть в корневую папку своего сервера и обозреть там файлы server.properties, bukkit.yml, [spigot.yml - если есть], help.yml - YML формат. Или файлы banned-players.json, banned-ips.json, ops.json - как пример использования JSON-формата (если у вас сервер версии 1.7.10 и выше).

В заключение даю ссылку на отличный онлайн-валидатор (система проверки синтаксиса) для разных типов файлов (в том числе для YML и JSON): http://codebeautify.org/.

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