NEON Formátum
*************

.[perex]
A NEON egy ember által olvasható, strukturált adatformátum. A Nette-ben konfigurációs fájlokhoz használják. Strukturált adatokhoz is használják, mint például beállítások, nyelvi fordítások stb. [Próbálja ki|https://ne-on.org].

A NEON a *Nette Object Notation* rövidítése. Kevésbé bonyolult és nehézkes, mint az XML vagy a JSON, de hasonló funkciókat biztosít. Nagyon hasonlít a YAML-hez. A fő előnye az, hogy a NEON-nak vannak úgynevezett [entity |#Entitások] entitásai, amelyeknek köszönhetően a DI szolgáltatások konfigurálása [is szexi |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. És lehetővé teszi a tabulátorokkal történő behúzást.

A NEON-t az alapoktól kezdve úgy tervezték, hogy könnyen használható legyen.


Integráció
==========

- NetBeans (beépített támogatással rendelkezik)
- PhpStorm ([plugin |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([Nette Latte + Neon |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte]) vagy [Nette for VS Code |https://marketplace.visualstudio.com/items?itemName=franken-ui.nette-for-vscode])
- 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 ([integrált nyelv |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].


Szintaxis
=========

Egy NEON-ban írt fájl általában egy tömböt vagy egy leképezést (mapping) reprezentál.


Leképezés (Mapping)
-------------------
A leképezés kulcs-érték párok halmaza, PHP-ban asszociatív tömbnek mondanánk. Minden pár `key: value` formában van írva, a `:` utáni szóköz kötelező. Az érték bármi lehet: string, szám, boolean, null, szekvencia vagy másik leképezés.

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

PHP-ban ugyanez a struktúra így íródna:

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

Ezt a jelölést blokk jelölésnek nevezik, mert minden elem külön sorban van, és ugyanazzal a behúzással rendelkezik (ebben az esetben nincs behúzás). A NEON támogatja a leképezések inline reprezentációját is, amely zárójelekbe van zárva, a behúzás nem játszik szerepet, és az egyes elemek elválasztója vagy vessző, vagy új sor:

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

Ugyanez több sorba írva (a behúzás nem számít):

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

A <code>: </code> helyett alternatívaként használható az `=` is, mind a blokk, mind az inline jelölésben:

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


Szekvencia
----------
A szekvenciák PHP-ban indexelt tömbök. Kötőjellel `-` kezdődő sorokként íródnak, amelyet szóköz követ. Az érték ismét bármi lehet: string, szám, boolean, null, szekvencia vagy másik leképezés.

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

PHP-ban ugyanez a struktúra így íródna:

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

Ezt a jelölést blokk jelölésnek nevezik, mert minden elem külön sorban van, és ugyanazzal a behúzással rendelkezik (ebben az esetben nincs behúzás). A NEON támogatja a szekvenciák inline reprezentációját is, amely zárójelekbe van zárva, a behúzás nem játszik szerepet, és az egyes elemek elválasztója vagy vessző, vagy új sor:

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

Ugyanez több sorba írva (a behúzás nem számít):

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

Az inline reprezentációban nem használhatók behúzó kötőjelek (`-`).


Kombinációk
-----------
A leképezések és szekvenciák értékei lehetnek más leképezések és szekvenciák. A fő szerepet a behúzás szintje játssza. A következő példában a szekvencia elemeinek jelölésére használt kötőjel nagyobb behúzással rendelkezik, mint a `pets` kulcs, így az elemek az első sor értékévé válnak:

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

PHP-ban ugyanez a struktúra így íródna:

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

Lehet kombinálni a blokk és az inline jelölést:

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

Az inline jelölésen belül már nem használható blokk jelölés, ez nem működik:

```neon
item: [
	pets:
	 - Cat     # EZ NEM LEHET!!!
	 - Dog
]
```

Az előző esetben egy leképezést írtunk, amelynek elemei szekvenciák voltak, most próbáljuk meg fordítva, és hozzunk létre egy szekvenciát, amely leképezéseket tartalmaz:

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

Nem szükséges, hogy a kötőjelek külön sorokban legyenek, így is elhelyezhetők:

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

Ön dönti el, hogy a kulcsokat szóközökkel igazítja-e oszlopba, vagy tabulátort használ.

Mivel a PHP-ban a leképezésekhez és a szekvenciákhoz is ugyanazt a struktúrát, azaz a tömböt használják, mindkettőt össze lehet vonni. A behúzás ezúttal ugyanaz:

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

PHP-ban ugyanez a struktúra így íródna:

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


Stringek
--------
A NEON stringeket szimpla és dupla idézőjelek közé lehet zárni. De ahogy látja, idézőjelek nélkül is lehetnek.

```neon
- String NEON-ban idézőjelek nélkül
- 'String NEON-ban szimpla idézőjelekben'
- "String NEON-ban dupla idézőjelekben"
```

Ha a string tartalmaz `# " ' , : = - [ ] { } ( )` karaktereket, amelyeket össze lehet téveszteni a NEON szintaxissal, akkor idézőjelek közé kell zárni. Javasoljuk a szimpla idézőjelek használatát, mert azokban nem használatos az escapelés. Ha egy ilyen stringben idézőjelet kell írnia, duplázza meg:

```neon
'Idézőjel '' egy stringen belül szimpla idézőjelekben'
```

A dupla idézőjelek lehetővé teszik escape szekvenciák használatát speciális karakterek írására fordított perjelek `\` segítségével. Minden escape szekvencia támogatott, mint a JSON formátumban, plusz a `\_`, ami egy nem törhető szóköz, azaz `\u00A0`.

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

Vannak további esetek, amikor a stringeket idézőjelek közé kell zárni:
- szóközökkel kezdődnek vagy végződnek
- számoknak, booleaneknek vagy nullnak tűnnek
- a NEON [dátumként |#Dátum] értelmezné őket


Többsoros stringek
------------------

A többsoros string háromszoros idézőjellel kezdődik és végződik külön sorokban. Az első sor behúzása figyelmen kívül marad, és ez minden sorra vonatkozik:

```neon
'''
	első sor
		második sor
	harmadik sor
	'''
```

PHP-ban ugyanezt így írnánk:

```php
"első sor\n\tmásodik sor\nharmadik sor" // PHP
```

Az escapelési szekvenciák csak az aposztrófok helyett dupla idézőjelekkel (`"""`) bevezetett stringeknél működnek:

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


Számok
------
A NEON érti a tudományos jelöléssel írt számokat, valamint a bináris, oktális és hexadecimális rendszerben írt számokat:

```neon
- 12         # egész szám
- 12.3       # float
- +1.2e-34   # exponenciális szám

- 0b11010    # bináris szám
- 0o666      # oktális szám
- 0x7A       # hexa szám
```


Null értékek
------------
A null értéket a NEON-ban `null`-lal vagy az érték megadásának elhagyásával lehet kifejezni. Engedélyezettek a nagy kezdőbetűs vagy csupa nagybetűs változatok is.

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


Boole értékek
-------------
A logikai értékeket a NEON-ban `true` / `false` vagy `yes` / `no` segítségével fejezzük ki. Engedélyezettek a nagy kezdőbetűs vagy csupa nagybetűs változatok is.

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


Dátum
-----
A NEON a következő formátumokat használja a dátumok kifejezésére, és automatikusan `DateTimeImmutable` objektumokká konvertálja őket:

```neon
- 2016-06-03                  # dátum
- 2016-06-03 19:00:00         # dátum & idő
- 2016-06-03 19:00:00.1234    # dátum & mikro idő
- 2016-06-03 19:00:00 +0200   # dátum & idő & zóna
- 2016-06-03 19:00:00 +02:00  # dátum & idő & zóna
```


Entitások
---------
Az entitás egy olyan struktúra, amely egy függvényhívásra emlékeztet:

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

PHP-ban ez [api:Nette\Neon\Entity] objektumként kerül elemzésre:

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

Az entitások láncolhatók is:

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

Ami PHP-ban így kerül elemzésre:

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

A zárójeleken belül az inline jelölés szabályai érvényesek, amelyeket a leképezéseknél és szekvenciáknál használnak, tehát lehet többsoros is, és akkor nem szükséges vesszőket megadni:

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


Kommentek
---------
A kommentek `#` jellel kezdődnek, és az összes következő karakter jobbra figyelmen kívül marad:

```neon
# ezt a sort az értelmező figyelmen kívül hagyja
street: 742 Evergreen Terrace
city: Springfield  # ezt is figyelmen kívül hagyja
country: USA
```


Neon versus JSON
================
A JSON a NEON részhalmaza. Minden JSON ezért NEON-ként is elemezhető:

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

Mi lenne, ha elhagynánk az idézőjeleket?

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

És a kapcsos zárójeleket és vesszőket?

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

database:
	driver: mysql
	username: root
	password: beruska92

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

Nem olvashatóbbak a listák kötőjelekkel?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Hozzáadunk kommenteket?

```neon
# a webalkalmazásom konfigurációja

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # gzip használata

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Hurrá, most már ismeri a NEON szintaxisát!


{{description: A NEON egy könnyen olvasható formátum az adatok szerializálására. Hasonló a YAML-hez. A fő különbség az, hogy a NEON támogatja az „entitásokat”, és a behúzáshoz használhatunk szóközöket és tabulátorokat is.}}
{{leftbar: utils:@left-menu}}