Format NEON
***********

.[perex]
NEON jest formatem danych strukturalnych czytelnym dla człowieka. W Nette jest on wykorzystywany do plików konfiguracyjnych. Jest również używany do danych strukturalnych, takich jak ustawienia, tłumaczenia językowe itp. [Spróbuj |https://ne-on.org].

NEON to skrót od *Nette Object Notation*. Jest ona mniej złożona i nieporęczna niż XML czy JSON, ale zapewnia podobne możliwości. Jest bardzo podobny do YAML. Główną zaletą jest to, że NEON ma tak zwane [encje |#entities], dzięki którym konfiguracja usług DI jest [tak seksowna |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. I pozwala na tabulatory dla wcięć.

NEON jest zbudowany od podstaw tak, aby był łatwy w użyciu.


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

- NetBeans (ma wbudowane wsparcie)
- 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 ([język zintegrowany |https://prismjs.com/#supported-languages])


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


Składnia .[#toc-syntax]
=======================

Plik napisany w NEONie zwykle reprezentuje tablicę lub odwzorowanie.


Mapowanie .[#toc-mappings]
--------------------------
Mapowanie to zestaw par klucz-wartość, w PHP byłoby to nazywane tablicą asocjacyjną. Każda para zapisana jest jako `key: value`, wymagana jest spacja po `:`. Wartość może być czymkolwiek: ciągiem, liczbą, booleanem, null, ciągiem lub dowolnym innym odwzorowaniem.

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

W PHP ta sama struktura zostałaby zapisana jako:

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

Notacja ta jest określana jako notacja blokowa, ponieważ wszystkie elementy znajdują się w osobnej linii i mają takie samo wcięcie (w tym przypadku brak). NEON obsługuje również reprezentację inline mapowania, która jest zamknięta w nawiasach, wcięcie nie odgrywa żadnej roli, a separatorem dla każdego elementu jest przecinek lub nowa linia:

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

To samo wpisane w wielu liniach (wcięcie nie ma znaczenia):

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

Alternatywnie, `=` może być używany zamiast <code>: </code> zarówno w notacji blokowej jak i inline:

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


Sekwencja .[#toc-sequences]
---------------------------
Sekwencje są w PHP tablicami indeksowanymi. Są one zapisane jako linie zaczynające się od myślnika `-`, po którym następuje spacja. Ponownie, wartość może być czymkolwiek: ciągiem, liczbą, booleanem, null, ciągiem lub dowolnym innym odwzorowaniem.

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

W PHP ta sama struktura zostałaby zapisana jako:

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

Notacja ta jest określana jako notacja blokowa, ponieważ wszystkie elementy znajdują się w osobnej linii i mają takie samo wcięcie (w tym przypadku brak). NEON obsługuje również reprezentację inline sekwencji, która jest zamknięta w nawiasach, wcięcie nie odgrywa żadnej roli, a separatorem dla każdego elementu jest przecinek lub nowa linia:

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

To samo wpisane w wielu liniach (wcięcie nie ma znaczenia):

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

Nie można używać wcięcia w reprezentacji inline.


Kombinacja .[#toc-combination]
------------------------------
Wartości mapowania i sekwencji mogą być innymi mapowaniami i sekwencjami. Dużą rolę odgrywa poziom wcięcia. W poniższym przykładzie myślnik użyty do wskazania wpisów sekwencji ma większe wcięcie niż klawisz `pets`, więc wpisy te stają się wartościami pierwszego wiersza:

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

W PHP ta sama struktura zostałaby zapisana jako:

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

Notacja blokowa i inline mogą być łączone:

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

Nie można już używać notacji blokowej wewnątrz notacji inline, to nie działa:

```neon
item: [
	pets:
	 - Cat     # TOHLE NELZE!!!
	 - Dog
]
```

W poprzednim przypadku napisaliśmy mapowanie, którego elementami były sekwencje. Teraz spróbujmy zrobić to na odwrót i stworzyć sekwencję zawierającą mapowania:

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

Nie jest konieczne, aby wypunktowania znajdowały się w osobnych wierszach; można je również umieścić w ten sposób:

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

Od Ciebie zależy, czy wyrównasz klawisze w kolumnie za pomocą spacji czy tabulatora.

Ponieważ PHP używa tej samej struktury dla mapowania i sekwencji, czyli tablic, można je połączyć. Tym razem wcięcie jest takie samo:

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

W PHP ta sama struktura zostałaby zapisana jako:

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


Struny .[#toc-strings]
----------------------
Łańcuchy NEON mogą być ujęte w pojedyncze lub podwójne cudzysłowy. Ale jak widać, mogą być też nienotowane.

```neon
- Řetězec v NEON bez uvozovek
- 'Řetězec v NEON v jednoduchých uvozovkách'
- "Řetězec v NEON ve dvojitých uvozovkách"
```

Jeśli ciąg zawiera znaki `# " ' , : = - [ ] { } ( )`który może być mylony ze składnią NEON, musi być zamknięty w cudzysłowie. Zaleca się używanie pojedynczych cytatów, ponieważ nie używają one ucieczki. Jeśli w takim ciągu trzeba zawrzeć cudzysłów, należy go podwoić:

```neon
'Uvozovka '' uvnitř řetezce v jednoduchých uvozovkách'
```

Podwójne cudzysłowy pozwalają na używanie sekwencji ucieczki do pisania znaków specjalnych za pomocą backslashes `\`. Podporovány jsou všechny escape sekvence jako u formátu JSON a navíc `\_`, czyli niepodzielonej spacji, czyli `\u00A0`.

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

Istnieją inne przypadki, w których musisz zamknąć ciągi w cudzysłowach:
- zaczynające się lub kończące spacjami
- wyglądają jak liczby, booleans, lub null
- NEON zinterpretowałby je jako [datę |#Dates]


Ciągi wieloliniowe .[#toc-multiline-strings]
--------------------------------------------

Łańcuch wieloliniowy zaczyna się i kończy potrójnym cytatem w oddzielnych liniach. Wcięcie pierwszej linii jest ignorowane we wszystkich liniach:

```neon
'''
	první řádek
		druhý řádek
	třetí řádek
	'''
```

W PHP napisalibyśmy to samo jako:

```php
"první řádek\n\tdruhý řádek\ntřetí řádek" // PHP
```

Sekwencje ucieczki działają tylko dla łańcuchów ujętych w podwójne cudzysłowy zamiast apostrofów:

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


Numery .[#toc-numbers]
----------------------
NEON rozumie liczby zapisane w notacji naukowej, a także liczby w notacji binarnej, ósemkowej i szesnastkowej:

```neon
- 12 # liczba całkowita
- 12.3 # float
- +1.2e-34 # liczba wykładnicza

- 0b11010 # liczba binarna
- 0o666 # liczba oktalna
- 0x7A # liczba heksadecymalna
```


Nulle .[#toc-nulls]
-------------------
Null może być wyrażony w NEON za pomocą `null` lub poprzez nieokreślenie wartości. Dozwolone są również warianty z wielką literą lub pierwszą literą.

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


Booleans .[#toc-booleans]
-------------------------
Wyrażenia logiczne są wyrażane w NEON za pomocą `true` / `false` lub `yes` / `no`. Dozwolone są również warianty z dużymi lub wszystkimi literami.

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


Data .[#toc-dates]
------------------
NEON używa następujących formatów do wyrażania danych i automatycznie konwertuje je na obiekty `DateTimeImmutable`:

```neon
- 2016-06-03 # data
- 2016-06-03 19:00:00 # data i czas
- 2016-06-03 19:00:00.1234 # data i czas
- 2016-06-03 19:00:00 +0200 # data & czas & strefa
- 2016-06-03 19:00:00 +02:00 # data & czas & strefa
```


Podmioty .[#toc-entities]
-------------------------
Encja to struktura przypominająca wywołanie funkcji:

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

W PHP jest on zapisany jako obiekt [api:Nette\Neon\Entity]:

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

Podmioty mogą być również łączone w łańcuchy:

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

Który w PHP jest parsowany w ten sposób:

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

Wewnątrz nawiasów obowiązują zasady notacji inline stosowane dla mapek i sekwencji, a więc może być ona wielowierszowa i wtedy nie ma potrzeby dołączania przecinków:

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


Uwagi .[#toc-comments]
----------------------
Komentarze zaczynają się od `#` i wszystkie kolejne znaki po prawej stronie są ignorowane:

```neon
# ta linia będzie ignorowana przez tłumacza
ulica: 742 Evergreen Terrace
miasto: Springfield # to też jest ignorowane
kraj: USA
```


Neon kontra JSON .[#toc-neon-versus-json]
=========================================
JSON jest podzbiorem NEON. Dlatego każdy JSON może być parsowany jako NEON:

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

A co jeśli pominiemy cudzysłów?

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

A nawiasy złożone i przecinki?

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

database:
	driver: mysql
	username: root
	password: beruska92

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

Czy listy wypunktowane nie są łatwiejsze do czytania?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Czy mamy dodawać komentarze?

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

Hura, teraz znasz składnię NEON!


{{description: NEON to łatwy do odczytania format do serializacji danych. Jest on podobny do YAML. Główną różnicą jest to, że NEON obsługuje "encje" i możemy używać zarówno spacji, jak i tabulatorów do wcięcia.}}
{{leftbar: utils:@left-menu}}