Format NEON

NEON to czytelny dla człowieka format danych strukturalnych. W Nette jest używany do plików konfiguracyjnych. Jest również używany do danych strukturalnych, takich jak ustawienia, tłumaczenia językowe itp. Wypróbuj go.

NEON to skrót od Nette Object Notation. Jest mniej skomplikowany i nieporęczny niż XML czy JSON, ale zapewnia podobne funkcje. Jest bardzo podobny do YAML. Główną zaletą jest to, że NEON ma tak zwane encje, dzięki którym konfiguracja usług DI jest również seksowna. I pozwala na wcięcia za pomocą tabulatorów.

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

Integracja

Składnia

Plik napisany w NEON zwykle reprezentuje tablicę lub mapowanie.

Mapowanie

Mapowanie to zbiór par klucz-wartość, w PHP powiedzielibyśmy tablica asocjacyjna. Każda para jest zapisana jako key: value, spacja po : jest wymagana. Wartością może być cokolwiek: ciąg znaków, liczba, boolean, null, sekwencja lub inne mapowanie.

street: 742 Evergreen Terrace
city: Springfield
country: USA

W PHP ta sama struktura zostałaby zapisana jako:

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

Ten zapis nazywa się blokowym, ponieważ wszystkie elementy znajdują się w osobnych wierszach i mają takie samo wcięcie (w tym przypadku żadne). NEON obsługuje również reprezentację inline mapowania, która jest zamknięta w nawiasach, wcięcie nie odgrywa żadnej roli, a separatorem poszczególnych elementów jest przecinek lub nowy wiersz:

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

To samo zapisane w wielu wierszach (wcięcie nie ma znaczenia):

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

Zamiast : można alternatywnie używać = zarówno w zapisie blokowym, jak i inline:

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

Sekwencje

Sekwencje to w PHP tablice indeksowane. Zapisuje się je jako wiersze zaczynające się od myślnika - poprzedzonego spacją. Wartością ponownie może być cokolwiek: ciąg znaków, liczba, boolean, null, sekwencja lub inne mapowanie.

- Cat
- Dog
- Goldfish

W PHP ta sama struktura zostałaby zapisana jako:

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

Ten zapis nazywa się blokowym, ponieważ wszystkie elementy znajdują się w osobnych wierszach i mają takie samo wcięcie (w tym przypadku żadne). NEON obsługuje również reprezentację inline sekwencji, która jest zamknięta w nawiasach, wcięcie nie odgrywa żadnej roli, a separatorem poszczególnych elementów jest przecinek lub nowy wiersz:

[Cat, Dog, Goldfish]

To samo zapisane w wielu wierszach (wcięcie nie ma znaczenia):

[
	Cat, Dog
		Goldfish
]

W reprezentacji inline nie można używać myślników z wcięciem.

Kombinacje

Wartościami mapowań i sekwencji mogą być inne mapowania i sekwencje. Główną rolę odgrywa poziom wcięcia. W poniższym przykładzie myślnik użyty do oznaczenia elementów sekwencji ma większe wcięcie niż klucz pets, więc elementy stają się wartością pierwszego wiersza:

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

W PHP ta sama struktura zostałaby zapisana jako:

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

Można łączyć zapis blokowy i inline:

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

Wewnątrz zapisu inline nie można już używać zapisu blokowego, to nie zadziała:

item: [
	pets:
	 - Cat     # TO JEST NIEDOZWOLONE!!!
	 - Dog
]

W poprzednim przypadku zapisaliśmy mapowanie, którego elementami były sekwencje, teraz spróbujemy odwrotnie i utworzymy sekwencję zawierającą mapowania:

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

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

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

To od ciebie zależy, czy wyrównasz klucze w kolumnie za pomocą spacji, czy użyjesz tabulatora.

Ponieważ w PHP używa się tej samej struktury zarówno dla mapowań, jak i sekwencji, czyli tablic, można je obie połączyć. Wcięcie jest tym razem takie samo:

- Cat
street: 742 Evergreen Terrace
- Goldfish

W PHP ta sama struktura zostałaby zapisana jako:

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

Ciągi / Stringi

Ciągi znaków w NEON można umieszczać w pojedynczych lub podwójnych cudzysłowach. Ale jak widać, mogą być również bez cudzysłowów.

- Ciąg w NEON bez cudzysłowów
- 'Ciąg w NEON w pojedynczych cudzysłowach'
- "Ciąg w NEON w podwójnych cudzysłowach"

Jeśli ciąg zawiera znaki # " ' , : = - [ ] { } ( ), które można pomylić ze składnią NEON, należy go umieścić w cudzysłowach. Zalecamy użycie pojedynczych cudzysłowów, ponieważ w nich nie stosuje się escapowania. Jeśli potrzebujesz zapisać cudzysłów w takim ciągu, podwój go:

'Cudzysłów '' wewnątrz ciągu w pojedynczych cudzysłowach'

Podwójne cudzysłowy umożliwiają używanie sekwencji ucieczki do zapisu znaków specjalnych za pomocą odwrotnych ukośników \. Obsługiwane są wszystkie sekwencje ucieczki jak w formacie JSON oraz dodatkowo \_, co jest spacją niełamliwą, czyli \u00A0.

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

Istnieją inne przypadki, w których należy umieścić ciągi znaków w cudzysłowach:

  • zaczynają się lub kończą spacjami
  • wyglądają jak liczby, wartości logiczne lub null
  • NEON zrozumiałby je jako Daty

Ciągi wieloliniowe

Ciąg wieloliniowy zaczyna się i kończy potrójnym cudzysłowem w osobnych wierszach. Wcięcie pierwszego wiersza jest ignorowane dla wszystkich wierszy:

'''
	pierwsza linia
		druga linia
	trzecia linia
	'''

W PHP to samo napisalibyśmy jako:

"pierwsza linia\n\tdruga linia\ntrzecia linia" // PHP

Sekwencje ucieczki działają tylko w ciągach ujętych w podwójne cudzysłowy zamiast apostrofów:

"""
	Copyright \u00A9
"""

Liczby

NEON rozumie liczby zapisane w tzw. notacji naukowej, a także liczby w systemie binarnym, ósemkowym i szesnastkowym:

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

- 0b11010    # liczba binarna
- 0o666      # liczba ósemkowa
- 0x7A       # liczba szesnastkowa

Null

Null można w NEON wyrazić za pomocą null lub przez pominięcie wartości. Dozwolone są również warianty z wielką pierwszą literą lub wszystkimi wielkimi literami.

a: null
b:

Wartości logiczne

Wartości logiczne są w NEON wyrażane za pomocą true / false lub yes / no. Dozwolone są również warianty z wielką pierwszą literą lub wszystkimi wielkimi literami.

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

Daty

NEON używa do wyrażania dat następujących formatów i automatycznie konwertuje je na obiekty DateTimeImmutable:

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

Encje

Encja to struktura przypominająca wywołanie funkcji:

Column(type: int, nulls: yes)

W PHP jest parsowana jako obiekt Nette\Neon\Entity:

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

Encje można również łączyć w łańcuchy:

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

Co w PHP jest parsowane w ten sposób:

// 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 zapisu inline używane dla mapowań i sekwencji, więc może być również wieloliniowy i wtedy nie trzeba podawać przecinków:

Column(
	type: int
	nulls: yes
)

Komentarze

Komentarze zaczynają się od znaku #, a wszystkie następujące znaki po prawej stronie są ignorowane:

# ta linia zostanie zignorowana przez interpreter
street: 742 Evergreen Terrace
city: Springfield  # to również jest ignorowane
country: USA

Neon kontra JSON

JSON jest podzbiorem NEONu. Każdy JSON można więc sparsować jako NEON:

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

Co gdybyśmy pominęli cudzysłowy?

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

A nawiasy klamrowe i przecinki?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Czy listy z myślnikami nie są bardziej czytelne?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Dodamy komentarze?

# konfiguracja mojej aplikacji internetowej

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # użyj gzip

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Hurra, teraz znasz składnię NEONu!

  1. Dokumentacja
  2. Praca z NEON
  3. Format NEON
wersja: 3.4