NEON Formátum

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.

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ásai, amelyeknek köszönhetően a DI szolgáltatások konfigurálása is szexi. É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ó

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.

street: 742 Evergreen Terrace
city: Springfield
country: USA

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

[ // 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:

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

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

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

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

{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.

- Cat
- Dog
- Goldfish

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

[ // 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:

[Cat, Dog, Goldfish]

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

[
	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:

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

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

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

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

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:

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:

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

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

- Cat
street: 742 Evergreen Terrace
- Goldfish

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

[ // 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.

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

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

- "\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 é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:

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

PHP-ban ugyanezt így írnánk:

"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:

"""
	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:

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

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.

[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:

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

Column(type: int, nulls: yes)

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

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

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

// 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:

Column(
	type: int
	nulls: yes
)

Kommentek

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

# 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ő:

{
"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?

{
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?

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?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Hozzáadunk kommenteket?

# 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!

  1. Dokumentáció
  2. Munka a NEON-nal
  3. NEON Formátum
verzió: 3.4