Formát NEON

NEON je v lidsky čitelný strukturovaný datový formát. V Nette se používá pro konfigurační soubory. Také se používá pro strukturovaná data, jako jsou nastavení, jazykové překlady atd. Vyzkoušejte si jej.

NEON je zkratka pro Nette Object Notation. Je méně složitý a nemotorný než XML nebo JSON, ale poskytuje podobné funkce. Je velmi podobný YAML. Hlavní přednost je tom, že NEON má takzvané entity, díky kterým je konfigurace DI služeb taky sexy. A umožňuje odsazovat tabulátory.

NEON je postaven od základů tak, aby byl snadno použitelný.

Integrace

NetBeans (má vestavěnou podporu)
PhpStorm (plugin)
Visual Studio Code (Nette Latte + Neon) nebo Nette for VS Code)
Sublime Text 3 (plugin)
Sublime Text 2 (plugin)
VIM (plugin)
Emacs (plugin)
Prism.js (integrovaný jazyk)

Syntaxe

Soubor psaný v NEON obvykle představuje pole nebo mapování.

Mapování

Mapování je sada párů klíč-hodnota, v PHP by se řeklo asociativní pole. Každá dvojice je zapsána jako key: value, mezera za : je nutná. Hodnotou může být cokoliv: řetězec, číslo, boolean, null, sekvence nebo jiné mapování.

street: 742 Evergreen Terrace
city: Springfield
country: USA

V PHP by se stejná struktura zapsala jako:

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

Tento zápis se označuje jako blokový, protože všechny položky jsou na samostatném řádku a mají stejné odsazení (v tomto případě žádné). NEON podporuje také inline reprezentaci mapování, která je uzavřená do závorek, odsazení nehraje žádnou roli a oddělovačem jednotlivých prvků je buď čárka, nebo nový řádek:

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

To stejné zapsané na více řádků (na odsazení nezáleží):

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

Místo : lze alternativně používat = a to jak v blokovém, tak v inline zápisu:

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

Sekvence

Sekvence jsou v PHP indexované pole. Zapisují se jako řádky začínající spojovníkem - následovaným mezerou. Hodnotou opět může být cokoliv: řetězec, číslo, boolean, null, sekvence nebo jiné mapování.

- Cat
- Dog
- Goldfish

V PHP by se stejná struktura zapsala jako:

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

Tento zápis se označuje jako blokový, protože všechny položky jsou na samostatném řádku a mají stejné odsazení (v tomto případě žádné). NEON podporuje také inline reprezentaci sekvence, která je uzavřená do závorek, odsazení nehraje žádnou roli a oddělovačem jednotlivých prvků je buď čárka, nebo nový řádek:

[Cat, Dog, Goldfish]

To stejné zapsané na více řádků (na odsazení nezáleží):

[
	Cat, Dog
		Goldfish
]

V inline reprezentaci nelze používat odsazující odrážky.

Kombinace

Hodnotami mapování a sekvencí mohou být jiné mapování a sekvence. Hlavní roli hraje úroveň odsazení. V následujícím příkladu má pomlčka použitá k označení položek sekvence větší odsazení než klíč pets, takže se položky stávají hodnotou prvního řádku:

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

V PHP by se stejná struktura zapsala jako:

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

Lze kombinovat blokový a inline zápis:

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

Uvnitř inline zápisu již nelze používat zápis blokový, tohle nefunguje:

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

V předchozím případě jsme zapsali mapovaní, jehož prvky byly sekvence, teď to zkusíme obráceně a vytvoříme sekvenci obsahující mapování:

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

Není nutné, aby odrážky byly na samostatných řádcích, lze je umístit i tímto způsobem:

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

Je na vás, jestli klíče zarovnáte do sloupce pomocí mezer nebo použijete tabulátor.

Protože v PHP se používá pro mapování i sekvence stejná struktura, tedy pole, lze obojí sloučit. Odsazení je tentokrát stejné:

- Cat
street: 742 Evergreen Terrace
- Goldfish

V PHP by se stejná struktura zapsala jako:

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

Řetězce

Řetězce v NEON lze uzavřít do jednoduchých i dvojitých uvozovek. Ale jak vidíte, mohou být také bez uvozovek.

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

Pokud řetězec obsahuje znaky # " ' , : = - [ ] { } ( ), které lze zaměnit s NEON syntaxí, je potřeba jej uzavřít do uvozovek. Doporučujeme použít jednoduché uvozovky, protože v nich se nepoužívá escapování. Pokud potřebujete v takovém řetězci zapsat uvozovku, zdvojte ji:

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

Dvojité uvozovky umožňují používat escape sekvence pro zápis speciálních znaků pomocí zpětných lomítek \. Podporovány jsou všechny escape sekvence jako u formátu JSON a navíc \_, což je nedělitelná mezera, tedy \u00A0.

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

Existují další případy, kdy je potřeba uzavřít řetězce do uvozovek:

začínají či končí mezerami
vypadají jako čísla, booleany, nebo null
NEON by je chápal jako datum

Víceřádkové řetězce

Víceřádkový řetězec začíná a končí trojitou uvozovkou na samostatných řádcích. Odsazení prvního řádku se ignoruje a to u všech řádků:

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

V PHP bychom totéž napsali jako:

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

Escapovací sekvence fungují jen u řetězců uvozených do dvojitých uvozovek místo apostrofů:

"""
	Copyright \u00A9
"""

Čísla

NEON rozumí číslům zapsaným v tzv. vědecké notaci a také číslům v binární, osmičkové a hexadecimální soustavě:

- 12         # celé číslo
- 12.3       # float
- +1.2e-34   # exponenciální číslo

- 0b11010    # binární číslo
- 0o666      # osmičkové číslo
- 0x7A       # hexa číslo

Nulls

Null lze v NEON vyjádřit pomocí null nebo neuvedením hodnoty. Povoleny jsou také varianty s velkým prvním nebo velkými všemi písmeny.

a: null
b:

Booleans

Logické hodnoty jsou v NEON vyjádřeny pomocí true / false nebo yes / no. Povoleny jsou také varianty s velkým prvním nebo velkými všemi písmeny.

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

Datum

NEON používá k vyjádření dat následující formáty a automaticky je převede na objekty 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 & zóna
- 2016-06-03 19:00:00 +02:00  # datum & čas & zóna

Entity

Entita je struktura, která připomíná volání funkce:

Column(type: int, nulls: yes)

V PHP se naparsuje jako objekt Nette\Neon\Entity:

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

Entity se mohou i zřetězit:

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

Což se v PHP se naparsuje tímto způsobem:

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

Uvnitř závorek platí pravidla pro inline zápis používaný u mapování a sekvencí, tedy může být klidně i víceřádkový a pak není nutné uvádět čárky:

Column(
	type: int
	nulls: yes
)

Komentáře

Komentáře začínají znakem # a všechny následující znaky napravo jsou ignorovány:

# this line will be ignored by the interpreter
street: 742 Evergreen Terrace
city: Springfield  # this is ignored too
country: USA

Neon versus JSON

JSON je podmnožinou NEONu. Každý JSON se dá proto parsovat jako NEON:

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

Co kdybychom vynechali uvozovky?

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

A složené závorky a čárky?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Nejsou seznamy s odrážkami lépe čitelné?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Přidáme komentáře?

# 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

Hurá, teď znáte syntaxi NEONu!

Nette Documentation Preview

Formát NEON

Integrace

Syntaxe

Mapování

Sekvence

Kombinace

Řetězce

Víceřádkové řetězce

Čísla

Nulls

Booleans

Datum

Entity

Komentáře

Neon versus JSON