Формат NEON

NEON — это человекочитаемый формат структурированных данных. В Nette он используется для конфигурационных файлов. Он также используется для структурированных данных, таких как настройки, языковые переводы и т. д. Попробуйте его.

NEON — это аббревиатура от Nette Object Notation. Он менее сложен и громоздок, чем XML или JSON, но предоставляет схожие функции. Он очень похож на YAML. Главное преимущество заключается в том, что NEON имеет так называемые сущности, благодаря которым конфигурация DI-сервисов тоже сексуальна. И позволяет использовать табуляцию для отступов.

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

Интеграция

NetBeans (имеет встроенную поддержку)
PhpStorm (плагин)
Visual Studio Code (Nette Latte + Neon) или Nette for VS Code)
Sublime Text 3 (плагин)
Sublime Text 2 (плагин)
VIM (плагин)
Emacs (плагин)
Prism.js (встроенный язык)

Синтаксис

Файл, написанный в NEON, обычно представляет собой массив или отображение.

Отображение

Отображение — это набор пар ключ-значение, в PHP это называется ассоциативным массивом. Каждая пара записывается как key: value, пробел после : обязателен. Значением может быть что угодно: строка, число, булево значение, null, последовательность или другое отображение.

street: 742 Evergreen Terrace
city: Springfield
country: USA

В PHP та же структура была бы записана так:

[ // PHP
	'street' => '742 Evergreen Terrace',
	'city' => 'Springfield',
	'country' => 'USA',
]

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

{street: 742 Evergreen Terrace, city: Springfield, country: USA}

То же самое, записанное на нескольких строках (отступ не имеет значения):

{
	street: 742 Evergreen Terrace
		city: Springfield, country: USA
}

Вместо : можно альтернативно использовать =, как в блочной, так и в инлайн-записи:

{street=742 Evergreen Terrace, city=Springfield, country=USA}

Последовательность

Последовательности в PHP — это индексированные массивы. Они записываются как строки, начинающиеся с дефиса -, за которым следует пробел. Значением опять же может быть что угодно: строка, число, булево значение, null, последовательность или другое отображение.

- Cat
- Dog
- Goldfish

В PHP та же структура была бы записана так:

[ // PHP
	'Cat',
	'Dog',
	'Goldfish',
]

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

[Cat, Dog, Goldfish]

То же самое, записанное на нескольких строках (отступ не имеет значения):

[
	Cat, Dog
		Goldfish
]

В инлайн-представлении нельзя использовать отступы с дефисами.

Комбинации

Значениями отображений и последовательностей могут быть другие отображения и последовательности. Главную роль играет уровень отступа. В следующем примере дефис, используемый для обозначения элементов последовательности, имеет больший отступ, чем ключ pets, поэтому элементы становятся значением первой строки:

pets:
   - Cat
   - Dog
cars:
   - Volvo
   - Skoda

В PHP та же структура была бы записана так:

[ // PHP
	'pets' => [
		'Cat',
		'Dog',
	],
	'cars' => [
		'Volvo',
		'Skoda',
	],
]

Можно комбинировать блочную и инлайн-запись:

pets: [Cat, Dog]
cars: [
	Volvo,
	Skoda,
]

Внутри инлайн-записи уже нельзя использовать блочную запись, это не работает:

item: [
	pets:
	 - Cat     # ЭТО НЕВОЗМОЖНО!!!
	 - Dog
]

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

-
	name: John
	age: 35
-
	name: Peter
	age: 28

Не обязательно, чтобы дефисы были на отдельных строках, их можно разместить и таким образом:

- name: John
  age: 35
- name: Peter
  age: 28

Вам решать, выравнивать ли ключи в столбец с помощью пробелов или использовать табуляцию.

Поскольку в PHP для отображений и последовательностей используется одна и та же структура, то есть массив, их можно объединить. Отступ на этот раз одинаковый:

- Cat
street: 742 Evergreen Terrace
- Goldfish

В PHP та же структура была бы записана так:

[ // PHP
	'Cat',
	'street' => '742 Evergreen Terrace',
	'Goldfish',
]

Строки

Строки в NEON можно заключать в одинарные или двойные кавычки. Но, как вы видите, они могут быть и без кавычек.

- Строка в NEON без кавычек
- 'Строка в NEON в одинарных кавычках'
- "Строка в NEON в двойных кавычках"

Если строка содержит символы # " ' , : = - [ ] { } ( ), которые можно спутать с синтаксисом NEON, ее необходимо заключить в кавычки. Рекомендуется использовать одинарные кавычки, так как в них не используется экранирование. Если вам нужно записать кавычку в такой строке, удвойте ее:

'Кавычка '' внутри строки в одинарных кавычках'

Двойные кавычки позволяют использовать escape-последовательности для записи специальных символов с помощью обратных слешей \. Поддерживаются все escape-последовательности, как в формате JSON, а также \_, что является неразрывным пробелом, то есть \u00A0.

- "\t \n \r \f \b \" \\ \/ \_"
- "\u00A9"

Существуют и другие случаи, когда необходимо заключать строки в кавычки:

они начинаются или заканчиваются пробелами
они выглядят как числа, булевы значения или null
NEON воспринял бы их как дату

Многострочные строки

Многострочная строка начинается и заканчивается тройными кавычками на отдельных строках. Отступ первой строки игнорируется, и это касается всех строк:

'''
	первая строка
		вторая строка
	третья строка
	'''

В PHP мы бы написали то же самое так:

"первая строка\n\tвторая строка\nтретья строка" // PHP

Escape-последовательности работают только для строк, заключенных в двойные кавычки вместо апострофов:

"""
	Copyright \u00A9
"""

Числа

NEON понимает числа, записанные в так называемой научной нотации, а также числа в двоичной, восьмеричной и шестнадцатеричной системах счисления:

- 12         # целое число
- 12.3       # float
- +1.2e-34   # экспоненциальное число

- 0b11010    # двоичное число
- 0o666      # восьмеричное число
- 0x7A       # шестнадцатеричное число

Nulls

Null в NEON можно выразить с помощью null или не указывая значение. Разрешены также варианты с большой первой или всеми большими буквами.

a: null
b:

Логические значения

Логические значения в NEON выражаются с помощью true / false или yes / no. Разрешены также варианты с большой первой или всеми большими буквами.

[true, TRUE, True, false, yes, no]

Дата

NEON использует для выражения дат следующие форматы и автоматически преобразует их в объекты DateTimeImmutable:

- 2016-06-03                  # дата
- 2016-06-03 19:00:00         # дата и время
- 2016-06-03 19:00:00.1234    # дата и микровремя
- 2016-06-03 19:00:00 +0200   # дата и время и зона
- 2016-06-03 19:00:00 +02:00  # дата и время и зона

Сущности

Сущность — это структура, напоминающая вызов функции:

Column(type: int, nulls: yes)

В PHP она парсится как объект Nette\Neon\Entity:

// PHP
new Nette\Neon\Entity('Column', ['type' => 'int', 'nulls' => true])

Сущности также могут быть объединены в цепочку:

Column(type: int, nulls: yes) Field(id: 1)

Что в PHP парсится следующим образом:

// PHP
new Nette\Neon\Entity(Nette\Neon\Neon::Chain, [
	new Nette\Neon\Entity('Column', ['type' => 'int', 'nulls' => true]),
	new Nette\Neon\Entity('Field', ['id' => 1]),
])

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

Column(
	type: int
	nulls: yes
)

Neon против JSON

JSON является подмножеством NEON. Поэтому любой JSON можно распарсить как NEON:

{
"php": {
	"date.timezone": "Europe\/Prague",
	"zlib.output_compression": true
},
"database": {
	"driver": "mysql",
	"username": "root",
	"password": "beruska92"
},
"users": [
	"Dave", "Kryten", "Rimmer"
]
}

Что, если мы уберем кавычки?

{
php: {
	date.timezone: Europe/Prague,
	zlib.output_compression: true
},
database: {
	driver: mysql,
	username: root,
	password: beruska92
},
users: [
	Dave, Kryten, Rimmer
]
}

А фигурные скобки и запятые?

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Не лучше ли читаются списки с дефисами?

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Добавим комментарии?

# конфигурация моего веб-приложения

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # использовать gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Ура, теперь вы знаете синтаксис NEON!

Формат NEON

Интеграция

Синтаксис

Отображение

Последовательность

Комбинации

Строки

Многострочные строки

Числа

Nulls

Логические значения

Дата

Сущности

Комментарии

Neon против JSON