Nette Documentation Preview

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

.[perex]
NEON е формат за структурирани данни, който може да се чете от човек. В Nette той се използва за конфигурационни файлове. Той се използва и за структурирани данни, като настройки, езикови преводи и др. [Изпробвайте го в пясъчника |https://ne-on.org].

NEON е съкращение от *Nette Object Notation*. Тя не е толкова сложна и елементарна, колкото XML или JSON, но предоставя подобни възможности. Много е подобен на YAML. Основното предимство е, че NEON разполага с т.нар. [същности |#entities], благодарение на които конфигурирането на DI услугите е [толкова секси |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`, като интервалът след `:` е задължителен. Стойността може да бъде всякаква: низ, число, булева, нула, последователност или друго съпоставяне.

```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. Те се записват като низове, започващи с дефис `-`, последван от интервал. Стойността може да бъде всякаква: низ, число, булева, нула, последователност или друго съпоставяне.

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

Двойните кавички ви позволяват да използвате escape последователности за записване на специални символи с помощта на обратни наклонени черти `\`. 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 Evergreen Terrace
град: Спрингфийлд # този текст също се игнорира
държава: САЩ
```


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}}

Формат NEON

NEON е формат за структурирани данни, който може да се чете от човек. В Nette той се използва за конфигурационни файлове. Той се използва и за структурирани данни, като настройки, езикови преводи и др. Изпробвайте го в пясъчника.

NEON е съкращение от Nette Object Notation. Тя не е толкова сложна и елементарна, колкото XML или JSON, но предоставя подобни възможности. Много е подобен на YAML. Основното предимство е, че NEON разполага с т.нар. същности, благодарение на които конфигурирането на DI услугите е толкова секси. И позволява табулации за отстъпление.

NEON е проектиран от самото начало, за да бъде лесен за използване.

Интеграция

Синтаксис

Файлът, написан в NEON, обикновено се състои от последователност или съпоставяне.

Сравнения

Съпоставянето е набор от двойки ключ-стойност, който в PHP се нарича асоциативен масив. Всяка двойка се записва като key: value, като интервалът след : е задължителен. Стойността може да бъде всякаква: низ, число, булева, нула, последователност или друго съпоставяне.

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. Те се записват като низове, започващи с дефис -, последван от интервал. Стойността може да бъде всякаква: низ, число, булева, нула, последователност или друго съпоставяне.

- 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'

Двойните кавички ви позволяват да използвате escape последователности за записване на специални символи с помощта на обратни наклонени черти \. 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       # цяло число
- 12.3     # плаващо число
- +1.2e-34 # експоненциално число

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

Нули

Нулите могат да бъдат изразени в 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
)

Коментар

Коментарите започват с # и всички следващи символи надясно се игнорират:

# този ред ще бъде игнориран от интерпретатора
улица: 742 Evergreen Terrace
град: Спрингфийлд # този текст също се игнорира
държава: САЩ

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!