Prickle

Мод Prickle для Minecraft — библиотека расширенного JSON для конфигов

Prickle — это мод-библиотека, которая внедряет в Minecraft формат конфигурационных файлов, расширяющий стандартный JSON. Она позволяет добавлять к свойствам комментарии и декораторы, описывающие значения по умолчанию, диапазоны или ссылки на документацию. Формат полностью обратно совместим с JSON, поддерживает подсветку синтаксиса и все существующие инструменты работы с JSON.

Что такое Prickle?

Prickle — это мод-библиотека, которая внедряет в Minecraft собственный формат конфигурационных файлов на основе JSON. Основная цель проекта — предоставить разработчикам инструментов для создания более понятных и удобных конфигов без потери совместимости со стандартными инструментами. Формат полностью обратно совместим с JSON: любой валидный JSON-файл также будет валидным файлом Prickle, что гарантирует работу со всеми существующими парсерами и редакторами кода.

Почему формат получил такое название?

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

Базовая структура и комментарии

В отличие от стандартного JSON, где комментарии игнорируются, Prickle позволяет хранить их внутри структуры файла. Значения свойств оборачиваются в объект, где ключ // зарезервирован специально для комментариев. Они могут быть одиночной строкой или массивом строк для многострочных заметок. Комментарии используются исключительно для контекста читателя и никогда не влияют на то, как файл будет разобран парсером. Это позволяет добавлять пояснения к настройкам, не нарушая синтаксис.

Пример использования комментариев

В стандартном JSON файл выглядит просто как набор пар ключ-значение. В Prickle то же значение дополняется объектом с метаданными:

```json
{
  "database_host": {
    "//": "IP-адрес базы данных для подключения.",
    "value": "192.168.1.222"
  }
}
```

Многострочные комментарии также поддерживаются через массив строк в ключе `//`, что удобно для описания сложных параметров или разделения логики на логические блоки.

Декораторы свойств

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

Примеры декораторов

В файлах Prickle можно встретить следующие типы декораторов:

- `//default` — указывает значение по умолчанию для свойства.
- `//reference` — ссылка на внешний ресурс, например страницу вики, для получения дополнительной информации.
- `//range` — определяет допустимый диапазон значений (например, `>=5`).
- `//regex` — регулярное выражение, которое должно соответствовать значению.
- `//empty-allowed` — разрешает ли свойство иметь пустое значение (по умолчанию `true`).

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

Отказ от других форматов

Автор проекта рассматривал альтернативные форматы конфигураций, такие как TOML, но отказался от них из-за недостатков в Java-реализациях. Многие альтернативные форматы часто имеют серьёзные баги, не поддерживаются разработчиками или лишены важных функций. Прелесть Prickle заключается в том, что он использует знакомый для большинства игроков и разработчиков JSON, который уже применяется в datapacks и командах Minecraft, сохраняя при этом все преимущества расширенной документации.

Автор: Darkhax · Лицензия: LGPL-2.1-only