Nette Documentation Preview

syntax 
NEON formátum
*************

.[perex]
A NEON egy ember által olvasható strukturált adatformátum. A Nette-ben konfigurációs fájlokra használják. Strukturált adatok, például beállítások, nyelvi fordítások stb. tárolására is használják. [Próbálja ki a homokozóban |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ó képességekkel rendelkezik. Nagyon hasonlít a YAML-hez. A fő előnye, hogy a NEON rendelkezik úgynevezett [entitásokkal |#entities], amelyeknek köszönhetően a DI szolgáltatások konfigurálása [olyan szexi |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. És lehetővé teszi a tabulátorokat a behúzáshoz.

A NEON az alapoktól kezdve úgy lett felépítve, hogy egyszerűen használható legyen.


Integráció .[#toc-integration]
==============================

- NetBeans (beépített támogatással rendelkezik)
- 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 ([integrált nyelv |https://prismjs.com/#supported-languages])


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


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

Egy NEON-ban írt fájl általában egy szekvenciából vagy leképezésből áll.


Leképezések .[#toc-mappings]
----------------------------
A leképezés kulcs-érték párok halmaza, PHP-ben asszociatív tömbnek neveznénk. Minden pár a `key: value` formában íródik, a `:` után szóköz szükséges. Az érték bármi lehet: string, szám, boolean, null, szekvencia vagy más leképezés.

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

PHP-ben ugyanez a struktúra a következőképpen lenne leírva:

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

Ezt a jelölést blokkjelölésnek nevezzük, mivel minden elem külön sorban van, és ugyanolyan behúzással rendelkezik (ebben az esetben nincs). A NEON támogatja az inline ábrázolást is a leképezéshez, amely zárójelekbe van zárva, a behúzás nem játszik szerepet, és az egyes elemek elválasztója vagy egy vessző vagy egy újsor:

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

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

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

Alternatívaként a `=` is használható a <code>: </code>, mind blokkos, mind soron belüli jelölésben:

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


Sequences .[#toc-sequences]
---------------------------
A szekvenciák indexelt tömbök a PHP-ban. A szekvenciák a `-` kötőjellel kezdődő sorok, majd egy szóköz követi őket. Az érték itt is bármi lehet: karakterlánc, szám, boolean, null, szekvencia vagy más leképezés.

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

PHP-ben ugyanez a struktúra a következőképpen lenne leírva:

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

Ezt a jelölést blokkjelölésnek nevezzük, mivel minden elem külön sorban van, és ugyanolyan behúzással rendelkezik (ebben az esetben nincs). A NEON támogatja a sorozatok inline ábrázolásá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 egy vessző vagy egy újsor:

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

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

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

Kötőjelek nem használhatók soron belüli ábrázolásban.


Kombináció .[#toc-combination]
------------------------------
A leképezések és szekvenciák értékei lehetnek más leképezések és szekvenciák. A behúzás szintje nagy szerepet játszik. A következő példában a szekvenciaelemek 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-ben ugyanezt a struktúrát így írnánk le:

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

Lehetőség van a blokk és az inline jelölés kombinálására:

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

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

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

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

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

Nem szükséges, hogy a felsoroláspontok külön sorokban legyenek; így is elhelyezhetjük őket:

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

Öntől függ, hogy a kulcsokat szóközökkel vagy tabulátorral igazítja-e egy oszlopba.

Mivel a PHP ugyanazt a struktúrát használja a leképezéshez és a szekvenciákhoz, azaz a tömböket, mindkettő összevonható. A behúzás ezúttal is ugyanaz:

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

PHP-ben ugyanazt a struktúrát így írnánk:

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


Strings .[#toc-strings]
-----------------------
A karakterláncok a NEON-ban szimpla vagy dupla idézőjelek közé zárhatók. De mint láthatjuk, idézőjelek nélkül is lehetnek.

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

Ha a karakterlánc karaktereket tartalmaz `# " ' , : = - [ ] { } ( )` amelyek összetéveszthetők a NEON szintaxissal, akkor idézőjelek közé kell zárni. Javasoljuk az egyszeres idézőjelek használatát, mivel ezek nem használnak eszkábálást. Ha ilyen karakterláncba idézőjelet kell zárni, akkor duplázza meg azt:

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

A kettős idézőjelek lehetővé teszik, hogy escape szekvenciákat használjon speciális karakterek írásához, a backslashes `\`. All escape sequences as in the JSON format are supported, plus `\_`, ami egy nem szaggatott szóköz, azaz `\u00A0`.

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

Vannak más esetek is, amikor karakterláncokat kell idézőjelekbe zárni:
- szóközzel kezdődnek vagy végződnek
- számoknak, booléknak vagy nullának tűnnek
- A NEON [dátumként |#dates] értelmezné őket


Többsoros karakterláncok .[#toc-multiline-strings]
--------------------------------------------------

A többsoros karakterlánc háromszoros idézőjellel kezdődik és végződik külön sorokban. Az első sor behúzását az összes sor esetében figyelmen kívül hagyjuk:

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

PHP-ben ugyanezt így írnánk:

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

A szekvenciák csak aposztrófok helyett dupla idézőjelekbe zárt karakterláncok esetében működnek:

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


Számok .[#toc-numbers]
----------------------
A NEON megérti az úgynevezett tudományos jelöléssel írt számokat, valamint a bináris, oktális és hexadecimális számokat is:

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

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


Nullák .[#toc-nulls]
--------------------
A null a NEON-ban a `null` használatával vagy érték meg nem adásával fejezhető ki. A nagy kezdőbetűvel vagy csupa nagybetűvel írt változatok is megengedettek.

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


Booleans .[#toc-booleans]
-------------------------
A Boolean értékeket a NEON-ban a `true` / `false` vagy a `yes` / `no` segítségével fejezzük ki. A nagy kezdőbetűvel vagy csupa nagybetűvel írt változatok is megengedettek.

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


Dátumok .[#toc-dates]
---------------------
A NEON a következő formátumokat használja az adatok kifejezésére, és automatikusan átalakítja őket `DateTimeImmutable` objektumokká:

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


Entitások .[#toc-entities]
--------------------------
Az entitás olyan struktúra, amely hasonlít egy függvényhívásra:

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

A PHP-ben objektumként elemzik [api:Nette\Neon\Entity]:

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

Amit a PHP a következőképpen elemez:

```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 a leképezéshez és a szekvenciákhoz használt inline jelölés szabályai érvényesek, így több sorra osztható, és nem szükséges vesszőt tenni:

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


Megjegyzések .[#toc-comments]
-----------------------------
A megjegyzések `#`-gal kezdődnek, és a jobb oldalt következő karaktereket figyelmen kívül hagyjuk:

```neon
# ezt a sort az értelmező figyelmen kívül hagyja.
utca: 742 Evergreen Terrace
város: # ezt is figyelmen kívül hagyja
ország: USA
```


NEON Versus JSON .[#toc-neon-versus-json]
=========================================
A JSON a NEON egy részhalmaza. Ezért minden JSON elemezhető NEON-ként:

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

Mi lenne, ha elhagyhatná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
]
}
```

Mit szólnánk a zárójelekhez és a vesszőkhöz?

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

database:
	driver: mysql
	username: root
	password: beruska92

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

A felsorolásjelek olvashatóbbak?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Mi a helyzet a megjegyzésekkel?

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

Megtaláltad a NEON szintaxist!


{{description: A NEON egy emberbarát adatszerializációs nyelv. Hasonló a YAML-hez. A fő különbség az, hogy a NEON támogatja az "entitásokat" és a tabulátor karaktereket a behúzáshoz.}}
{{leftbar: utils:@left-menu}}

NEON formátum

A NEON egy ember által olvasható strukturált adatformátum. A Nette-ben konfigurációs fájlokra használják. Strukturált adatok, például beállítások, nyelvi fordítások stb. tárolására is használják. Próbálja ki a homokozóban.

A NEON a Nette Object Notation rövidítése. Kevésbé bonyolult és nehézkes, mint az XML vagy a JSON, de hasonló képességekkel rendelkezik. Nagyon hasonlít a YAML-hez. A fő előnye, hogy a NEON rendelkezik úgynevezett entitásokkal, amelyeknek köszönhetően a DI szolgáltatások konfigurálása olyan szexi. És lehetővé teszi a tabulátorokat a behúzáshoz.

A NEON az alapoktól kezdve úgy lett felépítve, hogy egyszerűen használható legyen.

Integráció

Szintaxis

Egy NEON-ban írt fájl általában egy szekvenciából vagy leképezésből áll.

Leképezések

A leképezés kulcs-érték párok halmaza, PHP-ben asszociatív tömbnek neveznénk. Minden pár a key: value formában íródik, a : után szóköz szükséges. Az érték bármi lehet: string, szám, boolean, null, szekvencia vagy más leképezés.

street: 742 Evergreen Terrace
city: Springfield
country: USA

PHP-ben ugyanez a struktúra a következőképpen lenne leírva:

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

Ezt a jelölést blokkjelölésnek nevezzük, mivel minden elem külön sorban van, és ugyanolyan behúzással rendelkezik (ebben az esetben nincs). A NEON támogatja az inline ábrázolást is a leképezéshez, amely zárójelekbe van zárva, a behúzás nem játszik szerepet, és az egyes elemek elválasztója vagy egy vessző vagy egy újsor:

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

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

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

Alternatívaként a = is használható a : , mind blokkos, mind soron belüli jelölésben:

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

Sequences

A szekvenciák indexelt tömbök a PHP-ban. A szekvenciák a - kötőjellel kezdődő sorok, majd egy szóköz követi őket. Az érték itt is bármi lehet: karakterlánc, szám, boolean, null, szekvencia vagy más leképezés.

- Cat
- Dog
- Goldfish

PHP-ben ugyanez a struktúra a következőképpen lenne leírva:

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

Ezt a jelölést blokkjelölésnek nevezzük, mivel minden elem külön sorban van, és ugyanolyan behúzással rendelkezik (ebben az esetben nincs). A NEON támogatja a sorozatok inline ábrázolásá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 egy vessző vagy egy újsor:

[Cat, Dog, Goldfish]

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

[
	Cat, Dog
		Goldfish
]

Kötőjelek nem használhatók soron belüli ábrázolásban.

Kombináció

A leképezések és szekvenciák értékei lehetnek más leképezések és szekvenciák. A behúzás szintje nagy szerepet játszik. A következő példában a szekvenciaelemek 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:

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

PHP-ben ugyanezt a struktúrát így írnánk le:

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

Lehetőség van a blokk és az inline jelölés kombinálására:

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

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

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

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

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

Nem szükséges, hogy a felsoroláspontok külön sorokban legyenek; így is elhelyezhetjük őket:

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

Öntől függ, hogy a kulcsokat szóközökkel vagy tabulátorral igazítja-e egy oszlopba.

Mivel a PHP ugyanazt a struktúrát használja a leképezéshez és a szekvenciákhoz, azaz a tömböket, mindkettő összevonható. A behúzás ezúttal is ugyanaz:

- Cat
street: 742 Evergreen Terrace
- Goldfish

PHP-ben ugyanazt a struktúrát így írnánk:

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

Strings

A karakterláncok a NEON-ban szimpla vagy dupla idézőjelek közé zárhatók. De mint láthatjuk, idézőjelek nélkül is lehetnek.

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

Ha a karakterlánc karaktereket tartalmaz # " ' , : = - [ ] { } ( ) amelyek összetéveszthetők a NEON szintaxissal, akkor idézőjelek közé kell zárni. Javasoljuk az egyszeres idézőjelek használatát, mivel ezek nem használnak eszkábálást. Ha ilyen karakterláncba idézőjelet kell zárni, akkor duplázza meg azt:

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

A kettős idézőjelek lehetővé teszik, hogy escape szekvenciákat használjon speciális karakterek írásához, a backslashes \. All escape sequences as in the JSON format are supported, plus \_, ami egy nem szaggatott szóköz, azaz \u00A0.

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

Vannak más esetek is, amikor karakterláncokat kell idézőjelekbe zárni:

  • szóközzel kezdődnek vagy végződnek
  • számoknak, booléknak vagy nullának tűnnek
  • A NEON dátumként értelmezné őket

Többsoros karakterláncok

A többsoros karakterlánc háromszoros idézőjellel kezdődik és végződik külön sorokban. Az első sor behúzását az összes sor esetében figyelmen kívül hagyjuk:

'''
	first line
		second line
	third line
	'''

PHP-ben ugyanezt így írnánk:

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

A szekvenciák csak aposztrófok helyett dupla idézőjelekbe zárt karakterláncok esetében működnek:

"""
	Copyright \u00A9
"""

Számok

A NEON megérti az úgynevezett tudományos jelöléssel írt számokat, valamint a bináris, oktális és hexadecimális számokat is:

- 12 # egész szám
- 12.3 # egy lebegő
- +1.2e-34 # exponenciális szám

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

Nullák

A null a NEON-ban a null használatával vagy érték meg nem adásával fejezhető ki. A nagy kezdőbetűvel vagy csupa nagybetűvel írt változatok is megengedettek.

a: null
b:

Booleans

A Boolean értékeket a NEON-ban a true / false vagy a yes / no segítségével fejezzük ki. A nagy kezdőbetűvel vagy csupa nagybetűvel írt változatok is megengedettek.

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

Dátumok

A NEON a következő formátumokat használja az adatok kifejezésére, és automatikusan átalakítja őket DateTimeImmutable objektumokká:

- 2016-06-03 # dátum
- 2016-06-03 19:00:00 # dátum és idő
- 2016-06-03 19:00:00.1234 # dátum és mikroidő
- 2016-06-03 19:00:00 +0200 # dátum & idő & időzóna
- 2016-06-03 19:00:00 +02:00 # dátum & idő & időzóna

Entitások

Az entitás olyan struktúra, amely hasonlít egy függvényhívásra:

Column(type: int, nulls: yes)

A PHP-ben objektumként elemzik Nette\Neon\Entity:

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

Az entitások láncolhatók is:

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

Amit a PHP a következőképpen elemez:

// 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 a leképezéshez és a szekvenciákhoz használt inline jelölés szabályai érvényesek, így több sorra osztható, és nem szükséges vesszőt tenni:

Column(
	type: int
	nulls: yes
)

Megjegyzések

A megjegyzések #-gal kezdődnek, és a jobb oldalt következő karaktereket figyelmen kívül hagyjuk:

# ezt a sort az értelmező figyelmen kívül hagyja.
utca: 742 Evergreen Terrace
város: # ezt is figyelmen kívül hagyja
ország: USA

NEON Versus JSON

A JSON a NEON egy részhalmaza. Ezért minden JSON elemezhető NEON-ként:

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

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

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

Mit szólnánk a zárójelekhez és a vesszőkhöz?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

A felsorolásjelek olvashatóbbak?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Mi a helyzet a megjegyzésekkel?

# 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

Megtaláltad a NEON szintaxist!