Formatul NEON
*************

.[perex]
NEON este un format de date structurate lizibile de către om. În Nette, acesta este utilizat pentru fișierele de configurare. De asemenea, este utilizat pentru date structurate, cum ar fi setările, traducerile de limbă etc. [Încercați-l în sandbox |https://ne-on.org].

NEON este acronimul de la *Nette Object Notation*. Este mai puțin complexă și mai neîndemânatică decât XML sau JSON, dar oferă capacități similare. Este foarte asemănătoare cu YAML. Principalul avantaj este că NEON are așa-numitele [entități |#entities], datorită cărora configurarea serviciilor DI este [atât de sexy |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. Și permite tabulări pentru indentare.

NEON este construit de la zero pentru a fi simplu de utilizat.


Integrare .[#toc-integration]
=============================

- NetBeans (are suport integrat)
- PhpStorm ([plugin |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([plugin |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte])
- Sublime Text 3 ([plugin |https://github.com/FilipStryk/Nette-Latte-Neon-for-Sublime-Text-3])
- Sublime Text 2 ([plugin |https://github.com/Michal-Mikolas/Nette-package-for-Sublime-Text-2])
- VIM ([plugin |https://github.com/fpob/nette.vim])
- Emacs ([plugin |https://github.com/Fuco1/neon-mode])
- Prism.js ([limbaj integrat |https://prismjs.com/#supported-languages])


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


Sintaxa .[#toc-syntax]
======================

Un fișier scris în NEON constă, de obicei, într-o secvență sau o cartografiere.


Mapări .[#toc-mappings]
-----------------------
Mapping-ul este un set de perechi cheie-valoare, în PHP s-ar numi un array asociativ. Fiecare pereche se scrie ca `key: value`, fiind necesar un spațiu după `:`. Valoarea poate fi orice: șir de caractere, număr, boolean, null, secvență sau altă mapare.

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

În PHP, aceeași structură ar fi scrisă ca:

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

Această notație se numește notație de bloc, deoarece toate elementele se află pe o linie separată și au aceeași indentare (niciuna în acest caz). NEON acceptă, de asemenea, reprezentarea în linie pentru cartografiere, care este închisă între paranteze, indentarea nu joacă niciun rol, iar separatorul fiecărui element este fie o virgulă, fie o linie nouă:

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

Acesta este același lucru scris pe mai multe linii (indentarea nu are importanță):

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

Alternativ, se poate folosi `=` în loc de <code>: </code>, atât în notație bloc, cât și în notație inline:

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


Secvențe .[#toc-sequences]
--------------------------
Secvențele sunt array-uri indexate în PHP. Acestea sunt scrise ca linii care încep cu cratima `-` urmată de un spațiu. Din nou, valoarea poate fi orice: șir de caractere, număr, boolean, null, secvență sau altă cartografiere.

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

În PHP, aceeași structură ar fi scrisă astfel:

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

Această notație se numește notație de bloc, deoarece toate elementele se află pe o linie separată și au aceeași indentare (niciuna în acest caz). NEON acceptă, de asemenea, reprezentarea în linie pentru secvențe, care este cuprinsă între paranteze, indentarea nu joacă niciun rol, iar separatorul fiecărui element este fie o virgulă, fie o linie nouă:

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

Este vorba de același lucru scris pe mai multe linii (indentarea nu are importanță):

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

Nu se pot folosi cratime într-o reprezentare în linie.


Combinație .[#toc-combination]
------------------------------
Valorile maparelor și secvențelor pot fi alte mape și secvențe. Nivelul de indentare joacă un rol important. În exemplul următor, cratima utilizată pentru a indica elementele secvenței are o indentare mai mare decât tasta `pets`, astfel încât elementele devin valoarea primului rând:

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

În PHP, aceeași structură ar fi scrisă astfel::

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

Este posibil să se combine notarea în bloc și în linie:

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

Notarea în bloc nu mai poate fi utilizată în interiorul unei notații inline, deoarece nu funcționează:

```neon
item: [
	pets:
	 - Cat     # ACEST LUCRU NU ESTE POSIBIL!!!
	 - Dog
]
```

În cazul anterior, am scris o hartă ale cărei elemente erau secvențe. Acum, să încercăm invers și să creăm o secvență care să conțină mapare:

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

Nu este necesar ca punctele să fie pe linii separate; ele pot fi plasate și în acest mod:

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

Depinde de dvs. dacă aliniați cheile într-o coloană folosind spații sau o tabulație.

Deoarece PHP utilizează aceeași structură pentru cartografiere și secvențe, adică array-uri, ambele pot fi îmbinate. Indentarea este aceeași de această dată:

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

În PHP, aceeași structură ar fi scrisă ca:

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


Șiruri de caractere .[#toc-strings]
-----------------------------------
Șirurile de caractere în NEON pot fi incluse în ghilimele simple sau duble. Dar, după cum puteți vedea, ele pot fi și fără ghilimele.

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

În cazul în care șirul conține caractere `# " ' , : = - [ ] { } ( )` care pot fi confundate cu sintaxa NEON, acesta trebuie să fie inclus în ghilimele. Vă recomandăm să folosiți ghilimele simple, deoarece acestea nu utilizează scăpări. Dacă trebuie să includeți un ghilimele într-un astfel de șir, dublați-l:

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

Ghilimelele duble vă permit să folosiți secvențe de evadare pentru a scrie caractere speciale folosind backslash-uri `\`. All escape sequences as in the JSON format are supported, plus `\_`, care este un spațiu fără întrerupere, adică `\u00A0`.

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

Există și alte cazuri în care este necesar să închideți șirurile de caractere în ghilimele:
- acestea încep sau se termină cu spații
- seamănă cu numere, booleeni sau nul
- NEON le va înțelege ca fiind [date |#dates]


Șiruri de caractere cu mai multe linii .[#toc-multiline-strings]
----------------------------------------------------------------

Un șir de caractere multiliniar începe și se termină cu un ghilimele triplu pe linii separate. Indentarea primei linii este ignorată pentru toate liniile:

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

În PHP, am scrie același lucru ca:

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

Secvențele de scăpare funcționează numai pentru șirurile de caractere încadrate în ghilimele duble în loc de apostrofuri:

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


Numere .[#toc-numbers]
----------------------
NEON înțelege numerele scrise în așa-numita notație științifică, precum și numerele în binar, octal și hexazecimal:

```neon
- 12         # un număr întreg
- 12.3       # un float
- +1.2e-34   # un număr exponențial

- 0b11010    # număr binar
- 0o666      # număr octal
- 0x7A       # număr hexa
```


Nuli .[#toc-nulls]
------------------
Null poate fi exprimat în NEON prin utilizarea `null` sau prin nespecificarea unei valori. De asemenea, sunt permise variantele cu majusculă sau cu toate literele majuscule.

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


Booleeni .[#toc-booleans]
-------------------------
Valorile booleene sunt exprimate în NEON folosind `true` / `false` sau `yes` / `no`. Sunt permise, de asemenea, variante cu majusculă sau cu toate literele majuscule.

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


Date .[#toc-dates]
------------------
NEON utilizează următoarele formate pentru a exprima datele și le convertește automat în obiecte `DateTimeImmutable`:

```neon
- 2016-06-03                  # data
- 2016-06-03 19:00:00         # data și ora
- 2016-06-03 19:00:00.1234    # data și microora
- 2016-06-03 19:00:00 +0200   # dată & oră & fus orar
- 2016-06-03 19:00:00 +02:00  # dată & oră & fus orar
```


Entități .[#toc-entities]
-------------------------
O entitate este o structură care seamănă cu un apel de funcție:

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

În PHP, aceasta este analizată ca un obiect [api:Nette\Neon\Entity]:

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

Entitățile pot fi, de asemenea, înlănțuite:

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

Care este analizat în PHP după cum urmează:

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

În interiorul parantezelor, se aplică regulile de notație în linie utilizate pentru cartografiere și secvențe, astfel încât poate fi împărțită în mai multe linii și nu este necesar să se adauge virgule:

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


Comentarii .[#toc-comments]
---------------------------
Comentariile încep cu `#`, iar toate caracterele care urmează în dreapta sunt ignorate:

```neon
# această linie va fi ignorată de către interpretor
street: 742 Evergreen Terrace
city: Springfield  # și aceasta este ignorată
country: USA
```


NEON față de JSON .[#toc-neon-versus-json]
==========================================
JSON este un subset al NEON. Prin urmare, fiecare JSON poate fi analizat ca NEON:

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

Ce s-ar întâmpla dacă am putea omite ghilimelele?

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

Ce zici de paranteze și virgule?

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

database:
	driver: mysql
	username: root
	password: beruska92

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

Punctele sunt mai lizibile?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Dar comentariile?

```neon
# configurația aplicației mele web

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # folosiți gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Ați găsit sintaxa NEON!


{{description: NEON este un limbaj de serializare a datelor ușor de utilizat. Este similar cu YAML. Principala diferență este că NEON suportă "entități" și caractere de tabulare pentru indentare.}}
{{leftbar: utils:@left-menu}}