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

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

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

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


Інтеграція
==========

- NetBeans (має вбудовану підтримку)
- PhpStorm ([плагін |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([Nette Latte + Neon |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte]) або [Nette for VS Code |https://marketplace.visualstudio.com/items?itemName=franken-ui.nette-for-vscode])
- 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 for PHP |@home]
- [NEON for JavaScript |https://github.com/matej21/neon-js]
- [NEON for Python |https://github.com/paveldedik/neon-py].


Синтаксис
=========

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


Мапування
---------
Мапування — це набір пар ключ-значення, у 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}
```


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

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

У PHP та ж структура записувалася б так:

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

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

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

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

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

В інлайн-представленні не можна використовувати відступи з маркерами списку.


Комбінації
----------
Значеннями мапувань і послідовностей можуть бути інші мапування та послідовності. Головну роль відіграє рівень відступу. У наступному прикладі дефіс, використаний для позначення елементів послідовності, має більший відступ, ніж ключ `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     # ЦЕ НЕ МОЖНА!!!
	 - 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',
]
```


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

```neon
- Рядок у NEON без лапок
- 'Рядок у NEON в одинарних лапках'
- "Рядок у NEON у подвійних лапках"
```

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

```neon
'Лапка '' всередині рядка в одинарних лапках'
```

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

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

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


Багаторядкові рядки
-------------------

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

```neon
'''
	перший рядок
		другий рядок
	третій рядок
	'''
```

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

```php
"перший рядок\n\tdругий рядок\nтретій рядок" // PHP
```

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

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


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

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

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


Nulls
-----
Null в NEON можна виразити за допомогою `null` або невказанням значення. Дозволені також варіанти з великою першою літерою або всіма великими літерами.

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


Логічні значення
----------------
Логічні значення в NEON виражаються за допомогою `true` / `false` або `yes` / `no`. Дозволені також варіанти з великою першою літерою або всіма великими літерами.

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


Дата
----
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  # дата і час і зона
```


Сутності
--------
Сутність — це структура, яка нагадує виклик функції:

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


Коментарі
---------
Коментарі починаються символом `#`, і всі наступні символи праворуч ігноруються:

```neon
# цей рядок буде проігноровано інтерпретатором
street: 742 Evergreen Terrace
city: Springfield  # це також ігнорується
country: USA
```


Neon проти 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
# конфігурація мого веб-додатку

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # використовувати gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

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


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