Формат 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     # THIS IS NOT POSSIBLE!!!
	 - 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 могут быть заключены в одинарные или двойные кавычки. Но, как вы видите, они могут быть и без кавычек.

- A unquoted string in NEON
- 'A singled-quoted string in NEON'
- "A double-quoted string in NEON"

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

'A single quote '' inside a single-quoted string'

Двойные кавычки позволяют использовать экранирующие последовательности для записи специальных символов, используя обратные косые черты \. All escape sequences as in the JSON format are supported, plus \_, которые представляют собой неразрывный пробел, т.е. \u00A0.

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

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

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

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

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

'''
	first line
		second line
	third line
	'''

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

"first line\n\tsecond line\nthird line" // PHP

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

"""
	Copyright \u00A9
"""

Числа

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

- 12         # an integer
- 12.3       # a float
- +1.2e-34   # an exponential number

- 0b11010    # binary number
- 0o666      # octal number
- 0x7A       # hexa number

Нули

Нуль может быть выражен в NEON с помощью null или без указания значения. Также допускаются варианты с заглавной первой или всеми прописными буквами.

a: null
b:

Булевы

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

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

Даты

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

- 2016-06-03                  # date
- 2016-06-03 19:00:00         # date & time
- 2016-06-03 19:00:00.1234    # date & microtime
- 2016-06-03 19:00:00 +0200   # date & time & timezone
- 2016-06-03 19:00:00 +02:00  # date & time & timezone

Сущности

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

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

Как насчет комментариев?

# my web application config

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # use gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Вы нашли синтаксис NEON!

Nette Documentation Preview