Format NEON

NEON je človeško berljiv strukturiran podatkovni format. V Nette se uporablja za konfiguracijske datoteke. Uporablja se tudi za strukturirane podatke, kot so nastavitve, jezikovni prevodi itd. Preizkusite ga.

NEON je okrajšava za Nette Object Notation. Je manj zapleten in okoren kot XML ali JSON, vendar zagotavlja podobne funkcije. Je zelo podoben YAML. Glavna prednost je v tem, da ima NEON tako imenovane Entitete, zahvaljujoč katerim je konfiguracija DI storitev tudi seksi. In omogoča zamikanje s tabulatorji.

NEON je zgrajen od temeljev tako, da je enostaven za uporabo.

Integracija

Sintaksa

Datoteka, napisana v NEON, običajno predstavlja polje ali preslikavo.

Preslikava / Mapiranje

Preslikava je niz parov ključ-vrednost, v PHP bi rekli asociativno polje. Vsak par je zapisan kot key: value, presledek za : je nujen. Vrednost je lahko karkoli: niz, število, logična vrednost, null, zaporedje ali druga preslikava.

street: 742 Evergreen Terrace
city: Springfield
country: USA

V PHP bi se enaka struktura zapisala kot:

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

Ta zapis se označuje kot blokovni, ker so vsi elementi na samostojni vrstici in imajo enak zamik (v tem primeru nobenega). NEON podpira tudi inline predstavitev preslikave, ki je zaprta v oklepaje, zamik ne igra nobene vloge in ločilo posameznih elementov je ali vejica ali nova vrstica:

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

Enako zapisano v več vrsticah (na zamik ni pomembno):

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

Namesto : ` lahko alternativno uporabljate `= in to tako v blokovnem kot v inline zapisu:

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

Zaporedja / Sekvence

Zaporedja so v PHP indeksirana polja. Zapisujejo se kot vrstice, ki se začnejo z vezajem -, ki mu sledi presledek. Vrednost je spet lahko karkoli: niz, število, logična vrednost, null, zaporedje ali druga preslikava.

- Cat
- Dog
- Goldfish

V PHP bi se enaka struktura zapisala kot:

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

Ta zapis se označuje kot blokovni, ker so vsi elementi na samostojni vrstici in imajo enak zamik (v tem primeru nobenega). NEON podpira tudi inline predstavitev zaporedja, ki je zaprta v oklepaje, zamik ne igra nobene vloge in ločilo posameznih elementov je ali vejica ali nova vrstica:

[Cat, Dog, Goldfish]

Enako zapisano v več vrsticah (na zamik ni pomembno):

[
	Cat, Dog
		Goldfish
]

V inline predstavitvi ni mogoče uporabljati zamikajočih alinej.

Kombinacije

Vrednosti preslikav in zaporedij so lahko druge preslikave in zaporedja. Glavno vlogo igra raven zamika. V naslednjem primeru ima pomišljaj, uporabljen za označevanje elementov zaporedja, večji zamik kot ključ pets, zato elementi postanejo vrednost prve vrstice:

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

V PHP bi se enaka struktura zapisala kot:

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

Lahko kombinirate blokovni in inline zapis:

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

Znotraj inline zapisa ni več mogoče uporabljati blokovnega zapisa, tole ne deluje:

item: [
	pets:
	 - Cat     # TOLE NI MOGOČE!!!
	 - Dog
]

V prejšnjem primeru smo zapisali preslikavo, katere elementi so bila zaporedja, zdaj pa poskusimo obratno in ustvarimo zaporedje, ki vsebuje preslikave:

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

Ni nujno, da so alineje na samostojnih vrsticah, lahko jih postavite tudi na ta način:

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

Od vas je odvisno, ali boste ključe poravnali v stolpec s presledki ali uporabili tabulator.

Ker se v PHP uporablja za preslikave in zaporedja enaka struktura, torej polje, je mogoče oboje združiti. Zamik je tokrat enak:

- Cat
street: 742 Evergreen Terrace
- Goldfish

V PHP bi se enaka struktura zapisala kot:

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

Nizi

Nizi v NEON so lahko zaprti v enojne ali dvojne narekovaje. Ampak kot vidite, so lahko tudi brez narekovajev.

- Niz v NEON brez narekovajev
- 'Niz v NEON v enojnih narekovajih'
- "Niz v NEON v dvojnih narekovajih"

Če niz vsebuje znake # " ' , : = - [ ] { } ( ), ki jih je mogoče zamenjati s sintakso NEON, ga je treba zapreti v narekovaje. Priporočamo uporabo enojnih narekovajev, ker se v njih ne uporablja ubežanje znakov. Če morate v takem nizu zapisati narekovaj, ga podvojite:

'Narekovaj '' znotraj niza v enojnih narekovajih'

Dvojni narekovaji omogočajo uporabo ubežnih zaporedij za zapis posebnih znakov s pomočjo poševnic nazaj \. Podprta so vsa ubežna zaporedja kot pri formatu JSON in poleg tega \_, kar je nedeljiv presledek, torej \u00A0.

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

Obstajajo drugi primeri, ko je treba nize zapreti v narekovaje:

  • se začnejo ali končajo s presledki
  • izgledajo kot števila, logične vrednosti ali null
  • NEON bi jih razumel kot Datum

Večvrstični nizi

Večvrstični niz se začne in konča s trojnim narekovajem na samostojnih vrsticah. Zamik prve vrstice se ignorira in to pri vseh vrsticah:

'''
	prva vrstica
		druga vrstica
	tretja vrstica
	'''

V PHP bi enako napisali kot:

"prva vrstica\n\tdruga vrstica\ntretja vrstica" // PHP

Ubežna zaporedja delujejo le pri nizih, zaprtih v dvojne narekovaje namesto apostrofov:

"""
	Copyright \u00A9
"""

Števila

NEON razume števila, zapisana v t.i. znanstveni notaciji, in tudi števila v dvojiškem, osmiškem in šestnajstiškem sistemu:

- 12         # celo število
- 12.3       # float
- +1.2e-34   # eksponentno število

- 0b11010    # dvojiško število
- 0o666      # osmiško število
- 0x7A       # šestnajstiško število

Null vrednosti

Null lahko v NEON izrazite s pomočjo null ali z ne-navedbo vrednosti. Dovoljene so tudi različice z veliko prvo ali velikimi vsemi črkami.

a: null
b:

Logične vrednosti / Booleans

Logične vrednosti so v NEON izražene s pomočjo true / false ali yes / no. Dovoljene so tudi različice z veliko prvo ali velikimi vsemi črkami.

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

Datum

NEON uporablja za izražanje datumov naslednje formate in jih samodejno pretvori v objekte DateTimeImmutable:

- 2016-06-03                  # datum
- 2016-06-03 19:00:00         # datum & čas
- 2016-06-03 19:00:00.1234    # datum & mikročas
- 2016-06-03 19:00:00 +0200   # datum & čas & časovni pas
- 2016-06-03 19:00:00 +02:00  # datum & čas & časovni pas

Entitete

Entiteta je struktura, ki spominja na klic funkcije:

Column(type: int, nulls: yes)

V PHP se razčleni kot objekt Nette\Neon\Entity:

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

Entitete se lahko tudi združijo:

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

Kar se v PHP razčleni na ta način:

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

Znotraj oklepajev veljajo pravila za inline zapis, uporabljen pri preslikavah in zaporedjih, torej je lahko mirno tudi večvrstičen in potem ni treba navajati vejic:

Column(
	type: int
	nulls: yes
)

Komentarji

Komentarji se začnejo z znakom # in vsi naslednji znaki na desno so ignorirani:

# ta vrstica bo ignorirana s strani interpreterja
street: 742 Evergreen Terrace
city: Springfield  # to je tudi ignorirano
country: USA

Neon proti JSON

JSON je podmnožica NEON-a. Vsak JSON se da zato razčleniti kot NEON:

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

Kaj če bi izpustili narekovaje?

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

In zavite oklepaje in vejice?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Ali niso seznami z alinejami bolje berljivi?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Dodamo komentarje?

# konfiguracija moje spletne aplikacije

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # uporabi gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Hura, zdaj poznate sintakso NEON-a!

  1. Dokumentacija
  2. Delo z NEON
  3. Format NEON
različica: 3.4