Nette Documentation Preview

syntax 
Format NEON
***********

.[perex]
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 |https://ne-on.org].

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 |#entities], zaradi katerih je konfiguracija storitev DI [tako seksi |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. In dovoljuje tabulatorje za alineje.

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


Integracija .[#toc-integration]
===============================

- NetBeans (ima vgrajeno podporo)
- PhpStorm ([vtičnik |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([vtičnik |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte])
- Sublime Text 3 ([vtičnik |https://github.com/FilipStryk/Nette-Latte-Neon-for-Sublime-Text-3])
- Sublime Text 2 ([vtičnik |https://github.com/Michal-Mikolas/Nette-package-for-Sublime-Text-2])
- VIM ([vtičnik |https://github.com/fpob/nette.vim])
- Emacs ([vtičnik |https://github.com/Fuco1/neon-mode])
- Prism.js ([integrirani jezik |https://prismjs.com/#supported-languages])


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


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

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


Zemljevidi .[#toc-mappings]
---------------------------
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.

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

V jeziku PHP bi bila enaka struktura zapisana kot:

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

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

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

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

Namesto tega lahko namesto <code>: </code>, tako v blokovnem kot v vrstičnem zapisu:

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


Zaporedja .[#toc-sequences]
---------------------------
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.

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

V PHP bi bila enaka struktura zapisana kot:

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

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

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

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

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


Kombinacija .[#toc-combination]
-------------------------------
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:

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

V jeziku PHP bi bila ista struktura zapisana kot:

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

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

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

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

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

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

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

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

V PHP bi bila ista struktura zapisana kot:

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


. .[#toc-strings]
-----------------
Nizi v NEON-u so lahko zaprti v enojne ali dvojne narekovaje. Kot lahko vidite, so lahko tudi brez narekovajev.

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

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

```neon
- "\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 |#dates]


Večvrstični nizi .[#toc-multiline-strings]
------------------------------------------

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:

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

V jeziku PHP bi zapisali enako kot:

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

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

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


Številke .[#toc-numbers]
------------------------
NEON razume števila, zapisana v tako imenovanem znanstvenem zapisu, in tudi števila v dvojiškem, osmeriškem in šestnajstiškem zapisu:

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

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


Ničle .[#toc-nulls]
-------------------
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.

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


Logične vrednosti .[#toc-booleans]
----------------------------------
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.

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


Datumi .[#toc-dates]
--------------------
NEON uporablja naslednje formate za izražanje podatkov in jih samodejno pretvori v objekte `DateTimeImmutable`:

```neon
- 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 .[#toc-entities]
-------------------------
Entiteta je struktura, ki je podobna funkcijskemu klicu:

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

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

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

Entitete je mogoče tudi verižiti:

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

To se v PHP razčleni na naslednji način:

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

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:

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


Komentarji .[#toc-comments]
---------------------------
Komentarji se začnejo z `#` in vsi naslednji znaki na desni strani se ne upoštevajo:

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


NEON proti JSON .[#toc-neon-versus-json]
========================================
JSON je podmnožica NEON. Vsak JSON je zato mogoče razčleniti kot NEON:

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

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

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

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Kaj pa komentarji?

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


{{description: NEON je človeku prijazen jezik za serializacijo podatkov. Podoben je jeziku YAML. Glavna razlika je v tem, da NEON podpira "entitete" in znake tabulatorja za alinejo.}}
{{leftbar: utils:@left-menu}}

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

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!