Формат NEON
***********

.[perex]
NEON - це структурований формат даних, що читається людиною. У Nette він використовується для файлів конфігурації. Він також використовується для структурованих даних, таких як налаштування, мовні переклади тощо. [Спробуйте його в пісочниці |https://ne-on.org].

NEON розшифровується як *Nette Object Notation*. Він менш складний і незграбний, ніж XML або JSON, але надає подібні можливості. Вона дуже схожа на YAML. Основна перевага - NEON має так звані [сутності |#entities], завдяки яким конфігурація сервісів ІР є [такою сексуальною |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. І дозволяє використовувати табуляцію для відступів.

NEON створений з нуля, щоб бути простим у використанні.


Інтеграція .[#toc-integration]
==============================

- NetBeans (має вбудовану підтримку)
- PhpStorm ([плагін |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([плагін |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte])
- Sublime Text 3 ([плагін |https://github.com/FilipStryk/Nette-Latte-Neon-for-Sublime-Text-3])
- Sublime Text 2 ([плагін |https://github.com/Michal-Mikolas/Nette-package-for-Sublime-Text-2])
- VIM ([плагін |https://github.com/fpob/nette.vim])
- Emacs ([плагін |https://github.com/Fuco1/neon-mode])
- Prism.js ([інтегрована мова |https://prismjs.com/#supported-languages])


- [NEON для PHP |@home]
- [NEON для JavaScript |https://github.com/matej21/neon-js]
- NEON [для Python |https://github.com/paveldedik/neon-py].


Синтаксис .[#toc-syntax]
========================

Файл, написаний на NEON, зазвичай складається з послідовності або відображення.


Зіставлення .[#toc-mappings]
----------------------------
Маппінг - це набір пар ключ-значення, у PHP це називається асоціативним масивом. Кожна пара записується як `key: value`, пробіл після `:` обов'язковий. Значення може бути будь-яким: рядок, число, булево, null, послідовність або інше відображення.

```neon
street: 742 Evergreen Terrace
city: Springfield
country: USA
```

У PHP та сама структура буде записана як:

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

Ця нотація називається блоковою, тому що всі елементи розташовані в окремому рядку та мають однаковий відступ (у цьому випадку він відсутній). NEON також підтримує порядкове представлення для відображення, яке укладено в дужки, відступи не відіграють жодної ролі, а роздільником кожного елемента є або кома, або новий рядок:

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

Це одне й те саме, написане на кількох рядках (відступ не має значення):

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

Як альтернативу можна використовувати `=` замість <code>: </code>, як у блоковій, так і в інлайн-нотації:

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


Послідовності .[#toc-sequences]
-------------------------------
Послідовності - це індексовані масиви в PHP. Вони записуються у вигляді рядків, що починаються з дефіса `-`, за яким слідує пробіл. Значення може бути будь-яким: рядок, число, булево, null, послідовність або інше відображення.

```neon
- Cat
- Dog
- Goldfish
```

У PHP та сама структура матиме такий вигляд:

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

Ця нотація називається блоковою, тому що всі елементи знаходяться на окремому рядку і мають однаковий відступ (у цьому випадку він відсутній). NEON також підтримує потокове представлення послідовностей, які укладаються в дужки, відступи не відіграють жодної ролі, а роздільником кожного елемента є або кома, або новий рядок:

```neon
[Cat, Dog, Goldfish]
```

Це одне й те саме, написане на кількох рядках (відступ не має значення):

```neon
[
	Cat, Dog
		Goldfish
]
```

Дефіси не можуть бути використані в інлайн-представленні.


Комбінація .[#toc-combination]
------------------------------
Значення відображень і послідовностей можуть бути іншими відображеннями і послідовностями. Рівень відступу відіграє важливу роль. У наступному прикладі дефіс, який використовується для позначення елементів послідовності, має більший відступ, ніж ключ `pets`, тому елементи стають значеннями першого рядка:

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

У PHP та сама структура була б записана як:

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

Можна комбінувати блокову та інлайн-нотацію:

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

Блокова нотація більше не може бути використана всередині рядкової нотації, це не працює:

```neon
item: [
	pets:
	 - Cat     # THIS IS NOT POSSIBLE!!!
	 - Dog
]
```

У попередньому випадку ми написали відображення, елементами якого були послідовності. Тепер давайте спробуємо зробити навпаки і створимо послідовність, що містить відображення:

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

Не обов'язково, щоб маркери були на окремих рядках, їх можна розмістити і таким чином:

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

Ви самі вирішуєте, як вирівнювати ключі в стовпчику - за допомогою пробілів чи табуляції.

Оскільки PHP використовує одну й ту саму структуру для відображення і послідовностей, тобто масиви, обидва варіанти можуть бути об'єднані. Цього разу відступи однакові:

```neon
- Cat
street: 742 Evergreen Terrace
- Goldfish
```

У PHP та сама структура буде записана як:

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


Рядки .[#toc-strings]
---------------------
Рядки в NEON можуть бути укладені в одинарні або подвійні лапки. Але, як ви бачите, вони можуть бути і без лапок.

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

Якщо рядок містить символи `# " ' , : = - [ ] { } ( )` які можна сплутати із синтаксисом NEON, він має бути укладений у лапки. Ми рекомендуємо використовувати одинарні лапки, оскільки вони не використовують екранування. Якщо вам потрібно укласти лапки в такому рядку, подвійте їх:

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

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

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

Існують й інші випадки, коли необхідно укладати рядки в лапки:
- вони починаються або закінчуються пробілами
- виглядають як числа, булеві або null.
- NEON буде розуміти їх як [дати |#Dates]


Багаторядкові рядки .[#toc-multiline-strings]
---------------------------------------------

Багаторядковий рядок починається і закінчується потрійною лапкою на окремих рядках. Відступ першого рядка ігнорується для всіх рядків:

```neon
'''
	first line
		second line
	third line
	'''
```

У PHP ми б написали те саме:

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

Послідовності екранування працюють тільки для рядків, укладених у подвійні лапки замість апострофів:

```neon
"""
	Copyright \u00A9
"""
```


Числа .[#toc-numbers]
---------------------
NEON розуміє числа, записані в так званій науковій нотації, а також числа в двійковій, вісімковій і шістнадцятковій системі числення:

```neon
- 12 # ціле число
- 12.3 # число з плаваючою комою
- +1.2e-34 # експоненціальне число

- 0b11010 # двійкове число
- 0o666 # вісімкове число
- 0x7A # шістнадцяткове число
```


Нулі .[#toc-nulls]
------------------
Нуль може бути виражений у NEON за допомогою `null` або без зазначення значення. Також допускаються варіанти із великою першою або всіма великими літерами.

```neon
a: null
b:
```


Булеві .[#toc-booleans]
-----------------------
Булеві значення виражаються в NEON за допомогою `true` / `false` або `yes` / `no`. Також допускаються варіанти із великою першою або всіма великими літерами.

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


Дати .[#toc-dates]
------------------
NEON використовує такі формати для вираження даних і автоматично перетворює їх на об'єкти `DateTimeImmutable`:

```neon
- 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 # дата, час та часовий пояс
```


Сутності .[#toc-entities]
-------------------------
Сутність - це структура, що нагадує виклик функції:

```neon
Column(type: int, nulls: yes)
```

У PHP вона розбирається як об'єкт [api:Nette\Neon\Entity]:

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

Сутності також можуть бути об'єднані в ланцюжок:

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

Що розбирається в PHP таким чином:

```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]),
])
```

Усередині круглих дужок застосовуються правила інлайн-нотації, які використовуються для відображення і послідовностей, тому його можна розділити на кілька рядків і немає необхідності додавати коми:

```neon
Column(
	type: int
	nulls: yes
)
```


Коментарі .[#toc-comments]
--------------------------
Коментарі починаються з `#` і всі наступні символи праворуч ігноруються:

```neon
# цей рядок буде проігноровано перекладачем
вулиця: 742 Вічнозелена тераса
місто: Спрінгфілд # цей рядок також ігнорується
країна: США
```


NEON проти JSON .[#toc-neon-versus-json]
========================================
JSON є підмножиною NEON. Тому кожен JSON може бути розібраний як NEON:

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

Що якби ми могли опустити лапки?

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

Як щодо дужок і ком?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]
```

Чи є кулі більш розбірливими?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Як щодо коментарів?

```neon
# 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!


{{description: NEON - це зручна для людини мова серіалізації даних. Вона схожа на YAML. Основна відмінність полягає в тому, що NEON підтримує "сутності" і символи табуляції для відступів.}}
{{leftbar: utils:@left-menu}}