Format NEON

NEON je človeku berljiv strukturiran podatkovni format. V omrežju Nette se uporablja za konfiguracijske datoteke. Uporablja se tudi za strukturirane podatke, kot so nastavitve, jezikovni prevodi itd. Preizkusite ga v peskovniku.

NEON je kratica za Nette Object Notation. Je manj zapleten in okoren kot XML ali JSON, vendar zagotavlja podobne zmogljivosti. Zelo je podoben jeziku YAML. Glavna prednost je, da ima NEON tako imenovane entitete, zaradi katerih je konfiguracija storitev DI tako seksi. In dovoljuje tabulatorje za alineje.

Sistem NEON je od začetka zgrajen tako, da je preprost za uporabo.

Integracija

NetBeans (ima vgrajeno podporo)
PhpStorm (vtičnik)
Visual Studio Code(Nette Latte + Neon) ali Nette za VS Code)
Sublime Text 3 (vtičnik)
Sublime Text 2 (vtičnik)
VIM (vtičnik)
Emacs (vtičnik)
Prism.js (integrirani jezik)

Sintaksa

Datoteka, zapisana v NEON, je običajno sestavljena iz zaporedja ali preslikave.

Zemljevidi

Mapiranje je niz parov ključ-vrednost, v jeziku PHP bi ga imenovali asociativno polje. Vsak par je zapisan kot key: value, za : je potreben presledek. Vrednost je lahko karkoli: niz, število, logična vrednost, ničla, zaporedje ali drugo kartiranje.

street: 742 Evergreen Terrace
city: Springfield
country: USA

V jeziku PHP bi bila enaka struktura zapisana kot:

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

Ta zapis se imenuje blokovni zapis, ker so vsi elementi v ločeni vrstici in imajo enako alinejo (v tem primeru je ni). NEON podpira tudi vrstnično predstavitev za preslikavo, ki je zaprta v oklepajih, alineja nima vloge, ločilo vsakega elementa pa je bodisi vejica bodisi nova vrstica:

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

To je isto, kar je zapisano v več vrsticah (alineja ni pomembna):

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

Namesto tega lahko namesto : , tako v blokovnem kot v vrstičnem zapisu:

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

Zaporedja

Zaporedja so indeksirana polja v PHP. Zapisane so kot vrstice, ki se začnejo s pomišljajem -, ki mu sledi presledek. Tudi v tem primeru je lahko vrednost kar koli: niz, število, logična vrednost, ničla, zaporedje ali drugo prikazovanje.

- Cat
- Dog
- Goldfish

V PHP bi bila enaka struktura zapisana kot:

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

Ta zapis se imenuje blokovni zapis, ker so vsi elementi v ločeni vrstici in imajo enako alinejo (v tem primeru je ni). NEON podpira tudi vrstilni zapis za zaporedja, ki so zaprta v oklepajih, alineja nima vloge, ločilo vsakega elementa pa je bodisi vejica bodisi nova vrstica:

[Cat, Dog, Goldfish]

To je enako zapisano v več vrsticah (alineja ni pomembna):

[
	Cat, Dog
		Goldfish
]

V vrstični predstavitvi ni mogoče uporabljati veznikov.

Kombinacija

Vrednosti preslikav in zaporedij so lahko druge preslikave in zaporedja. Pomembno vlogo ima stopnja odmikanja. V naslednjem primeru ima pomišljaj, ki se uporablja za označevanje elementov zaporedja, večjo alinejo kot ključ pets, zato elementi postanejo vrednost prve vrstice:

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

V jeziku PHP bi bila ista struktura zapisana kot:

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

Mogoče je kombinirati blokovni in vrstnični zapis:

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

Blokovnega zapisa ni več mogoče uporabiti znotraj vrstilnega zapisa, saj to ne deluje:

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

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

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

Ni nujno, da so točke na ločenih vrsticah; lahko jih postavimo tudi na ta način:

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

Od vas je odvisno, ali jih boste v stolpcu poravnali s presledki ali tabulatorjem.

Ker PHP uporablja enako strukturo za preslikave in zaporedja, tj. polja, je mogoče oboje združiti. Vstavljanje je tokrat enako:

- Cat
street: 742 Evergreen Terrace
- Goldfish

V PHP bi bila ista struktura zapisana kot:

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

.

Nizi v NEON-u so lahko zaprti v enojne ali dvojne narekovaje. Kot lahko vidite, so lahko tudi brez narekovajev.

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

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

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

Dvojni narekovaji omogočajo uporabo pobeglih zaporedij za zapis posebnih znakov z uporabo povratnega lomljenja \. All escape sequences as in the JSON format are supported, plus \_, ki je neprekinjen presledek, tj. \u00A0.

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

Obstajajo tudi drugi primeri, ko morate nize zapreti v narekovaje:

se začnejo ali končajo s presledki
so videti kot številke, logični znaki ali ničelne vrednosti
NEON bi jih razumel kot datume

Večvrstični nizi

Večvrstični niz se začne in konča s trojnim narekovajom v ločenih vrsticah. Odmik prve vrstice se pri vseh vrsticah ne upošteva:

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

V jeziku PHP bi zapisali enako kot:

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

Zaporedja za pobeg delujejo le za nize, ki so namesto z apostrofi zaprti z dvojnimi narekovaji:

"""
	Copyright \u00A9
"""

Številke

NEON razume števila, zapisana v tako imenovanem znanstvenem zapisu, in tudi števila v dvojiškem, osmeriškem in šestnajstiškem zapisu:

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

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

Ničle

Ničlo lahko v NEON-u izrazimo z uporabo null ali tako, da ne navedemo vrednosti. Dovoljene so tudi različice z veliko začetnico ali vsemi velikimi črkami.

a: null
b:

Logične vrednosti

Logične vrednosti so v NEON-u izražene z uporabo true / false ali yes / no. Dovoljene so tudi različice z veliko začetnico ali vsemi velikimi črkami.

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

Datumi

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

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

Entitete

Entiteta je struktura, ki je podobna funkcijskemu klicu:

Column(type: int, nulls: yes)

V jeziku PHP se analizira kot objekt Nette\Neon\Entity:

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

Entitete je mogoče tudi verižiti:

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

To se v PHP razčleni na naslednji 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 vrstični zapis, ki se uporabljajo za preslikave in zaporedja, zato se lahko razdeli na več vrstic in ni treba dodajati vejic:

Column(
	type: int
	nulls: yes
)

Komentarji

Komentarji se začnejo z # in vsi naslednji znaki na desni strani se ne upoštevajo:

# tolmač bo to vrstico ignoriral
street: 742 Evergreen Terrace
city: Springfield  # tudi to se ne upošteva
country: USA

NEON proti JSON

JSON je podmnožica NEON. Vsak JSON je zato mogoče 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 pa, če bi lahko izpustili narekovaje?

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

Kaj pa oklepaji in vejice?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Ali so zaporedja bolj čitljiva?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Kaj pa komentarji?

# konfiguracija moje spletne aplikacije

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Našli ste sintakso NEON!

Nette Documentation Preview