Format NEON

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.

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, dzięki którym konfiguracja usług DI jest tak seksowna. I pozwala na tabulatory dla wcięć.

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

Integracja

Składnia

Plik napisany w NEONie zwykle reprezentuje tablicę lub odwzorowanie.

Mapowanie

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.

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',
]

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:

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

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

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

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

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

Sekwencja

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.

- Cat
- Dog
- Goldfish

W PHP ta sama struktura zostałaby zapisana jako:

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

[Cat, Dog, Goldfish]

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

[
	Cat, Dog
		Goldfish
]

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

Kombinacja

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:

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

W PHP ta sama struktura zostałaby zapisana jako:

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

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

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

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

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:

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

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

- Cat
street: 742 Evergreen Terrace
- Goldfish

W PHP ta sama struktura zostałaby zapisana jako:

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

Struny

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

- Ř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ć:

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

- "\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ę

Ciągi wieloliniowe

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

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

W PHP napisalibyśmy to samo jako:

"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:

"""
	Copyright \u00A9
"""

Numery

NEON rozumie liczby zapisane w notacji naukowej, a także liczby w notacji binarnej, ósemkowej i szesnastkowej:

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

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

Nulle

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ą.

a: null
b:

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.

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

Data

NEON używa następujących formatów do wyrażania danych 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 czas
- 2016-06-03 19:00:00 +0200 # data & czas & strefa
- 2016-06-03 19:00:00 +02:00 # data & czas & strefa

Podmioty

Encja to struktura przypominająca wywołanie funkcji:

Column(type: int, nulls: yes)

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

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

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

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

Który w PHP jest parsowany 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 notacji inline stosowane dla mapek i sekwencji, a więc może być ona wielowierszowa i wtedy nie ma potrzeby dołączania przecinków:

Column(
	type: int
	nulls: yes
)

Uwagi

Komentarze zaczynają się od # i wszystkie kolejne znaki po prawej stronie są ignorowane:

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

Neon kontra JSON

JSON jest podzbiorem NEON. Dlatego każdy JSON może być parsowany jako 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?

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

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?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Czy mamy dodawać komentarze?

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

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