Das NEON-Format

NEON ist ein menschenlesbares strukturiertes Datenformat. In Nette wird es für Konfigurationsdateien verwendet. Es wird auch für strukturierte Daten wie Einstellungen, Sprachübersetzungen usw. verwendet. Probieren Sie es aus.

NEON ist die Abkürzung für Nette Object Notation. Es ist weniger komplex und sperrig als XML oder JSON, bietet aber ähnliche Funktionen. Es ist YAML sehr ähnlich. Der Hauptvorteil ist, dass NEON sogenannte Entitäten hat, dank derer die Konfiguration von DI-Diensten auch sexy ist. Und es erlaubt die Einrückung mit Tabulatoren.

NEON wurde von Grund auf so konzipiert, dass es einfach zu verwenden ist.

Integration

Syntax

Eine in NEON geschriebene Datei stellt normalerweise ein Array oder eine Zuordnung dar.

Zuordnung (Mapping)

Eine Zuordnung ist eine Menge von Schlüssel-Wert-Paaren, in PHP würde man sagen assoziatives Array. Jedes Paar wird als key: value geschrieben, ein Leerzeichen nach : ist erforderlich. Der Wert kann alles sein: Zeichenkette, Zahl, Boolean, Null, Sequenz oder eine andere Zuordnung.

street: 742 Evergreen Terrace
city: Springfield
country: USA

In PHP würde dieselbe Struktur wie folgt geschrieben werden:

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

Diese Schreibweise wird als Block-Schreibweise bezeichnet, da alle Elemente auf einer separaten Zeile stehen und dieselbe Einrückung haben (in diesem Fall keine). NEON unterstützt auch eine Inline-Darstellung für Zuordnungen, die in Klammern {} eingeschlossen ist, die Einrückung spielt keine Rolle und das Trennzeichen für einzelne Elemente ist entweder ein Komma oder ein Zeilenumbruch:

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

Dasselbe auf mehrere Zeilen verteilt (Einrückung spielt keine Rolle):

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

Anstelle von : kann alternativ = verwendet werden, sowohl in der Block- als auch in der Inline-Schreibweise:

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

Sequenz

Sequenzen sind in PHP indizierte Arrays. Sie werden als Zeilen geschrieben, die mit einem Bindestrich - gefolgt von einem Leerzeichen beginnen. Der Wert kann wiederum alles sein: Zeichenkette, Zahl, Boolean, Null, Sequenz oder eine andere Zuordnung.

- Cat
- Dog
- Goldfish

In PHP würde dieselbe Struktur wie folgt geschrieben werden:

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

Diese Schreibweise wird als Block-Schreibweise bezeichnet, da alle Elemente auf einer separaten Zeile stehen und dieselbe Einrückung haben (in diesem Fall keine). NEON unterstützt auch eine Inline-Darstellung für Sequenzen, die in Klammern [] eingeschlossen ist, die Einrückung spielt keine Rolle und das Trennzeichen für einzelne Elemente ist entweder ein Komma oder ein Zeilenumbruch:

[Cat, Dog, Goldfish]

Dasselbe auf mehrere Zeilen verteilt (Einrückung spielt keine Rolle):

[
	Cat, Dog
		Goldfish
]

In der Inline-Darstellung können keine einrückenden Aufzählungszeichen (-) verwendet werden.

Kombinationen

Die Werte von Zuordnungen und Sequenzen können andere Zuordnungen und Sequenzen sein. Die Einrückungsebene spielt die Hauptrolle. Im folgenden Beispiel hat der Bindestrich, der zur Kennzeichnung von Sequenzelementen verwendet wird, eine größere Einrückung als der Schlüssel pets, sodass die Elemente zum Wert der ersten Zeile werden:

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

In PHP würde dieselbe Struktur wie folgt geschrieben werden:

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

Es ist möglich, Block- und Inline-Schreibweisen zu kombinieren:

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

Innerhalb der Inline-Schreibweise kann keine Block-Schreibweise mehr verwendet werden, dies funktioniert nicht:

item: [
	pets:
	 - Cat     # DAS IST NICHT MÖGLICH!!!
	 - Dog
]

Im vorherigen Fall haben wir eine Zuordnung geschrieben, deren Elemente Sequenzen waren, jetzt versuchen wir es umgekehrt und erstellen eine Sequenz, die Zuordnungen enthält:

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

Es ist nicht notwendig, dass die Aufzählungszeichen auf separaten Zeilen stehen, sie können auch wie folgt platziert werden:

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

Es liegt an Ihnen, ob Sie die Schlüssel mit Leerzeichen in eine Spalte ausrichten oder einen Tabulator verwenden.

Da in PHP für Zuordnungen und Sequenzen dieselbe Struktur verwendet wird, nämlich Arrays, können beide zusammengeführt werden. Die Einrückung ist diesmal dieselbe:

- Cat
street: 742 Evergreen Terrace
- Goldfish

In PHP würde dieselbe Struktur wie folgt geschrieben werden:

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

Zeichenketten

Zeichenketten in NEON können in einfache oder doppelte Anführungszeichen eingeschlossen werden. Aber wie Sie sehen, können sie auch ohne Anführungszeichen sein.

- Zeichenkette in NEON ohne Anführungszeichen
- 'Zeichenkette in NEON in einfachen Anführungszeichen'
- "Zeichenkette in NEON in doppelten Anführungszeichen"

Wenn die Zeichenkette Zeichen wie # " ' , : = - [ ] { } ( ) enthält, die mit der NEON-Syntax verwechselt werden könnten, muss sie in Anführungszeichen eingeschlossen werden. Wir empfehlen die Verwendung einfacher Anführungszeichen ('...'), da darin kein Escaping verwendet wird. Wenn Sie in einer solchen Zeichenkette ein einfaches Anführungszeichen schreiben müssen, verdoppeln Sie es (''):

'Anführungszeichen '' innerhalb einer Zeichenkette in einfachen Anführungszeichen'

Doppelte Anführungszeichen ("...") ermöglichen die Verwendung von Escape-Sequenzen zur Darstellung von Sonderzeichen mit Backslashes \. Alle Escape-Sequenzen wie im JSON-Format werden unterstützt, zusätzlich \_, was ein geschütztes Leerzeichen ist, also \u00A0.

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

Es gibt weitere Fälle, in denen Zeichenketten in Anführungszeichen eingeschlossen werden müssen:

  • sie beginnen oder enden mit Leerzeichen
  • sie sehen aus wie Zahlen, Booleans oder null
  • NEON würde sie als Datum verstehen

Mehrzeilige Zeichenketten

Eine mehrzeilige Zeichenkette beginnt und endet mit dreifachen Anführungszeichen (''' oder """) auf separaten Zeilen. Die Einrückung der ersten Zeile (nach den öffnenden Anführungszeichen) bestimmt die Basiseinrückung, die von allen folgenden Zeilen entfernt wird:

'''
	erste Zeile
		zweite Zeile
	dritte Zeile
	'''

In PHP würde dies als folgende Zeichenkette interpretiert:

"Erste Zeile\n\tZweite Zeile mit Einrückung\nDritte Zeile" // PHP

Escape-Sequenzen funktionieren nur bei Zeichenketten, die in doppelten Anführungszeichen statt Apostrophen eingeschlossen sind:

"""
	Copyright \u00A9
"""

Zahlen

NEON versteht Zahlen, die in sogenannter wissenschaftlicher Notation geschrieben sind, sowie Zahlen im Binär-, Oktal- und Hexadezimalsystem:

- 12         # ganze Zahl
- 12.3       # float
- +1.2e-34   # Exponentialzahl

- 0b11010    # Binärzahl
- 0o666      # Oktalzahl
- 0x7A       # Hexadezimalzahl

Nulls

Null kann in NEON mit null ausgedrückt werden oder durch Weglassen des Werts nach dem Doppelpunkt. Varianten mit großem Anfangsbuchstaben (Null) oder komplett in Großbuchstaben (NULL) sind ebenfalls erlaubt.

a: null
b:

Booleans

Logische Werte werden in NEON mit true / false oder yes / no ausgedrückt. Varianten mit großem Anfangsbuchstaben oder komplett in Großbuchstaben sind ebenfalls erlaubt.

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

Datum

NEON verwendet die folgenden Formate zur Darstellung von Daten und konvertiert sie automatisch in DateTimeImmutable-Objekte:

- 2016-06-03                  # Datum
- 2016-06-03 19:00:00         # Datum & Zeit
- 2016-06-03 19:00:00.1234    # Datum & Mikrozeit
- 2016-06-03 19:00:00 +0200   # Datum & Zeit & Zeitzone
- 2016-06-03 19:00:00 +02:00  # Datum & Zeit & Zeitzone

Entitäten

Eine Entität ist eine Struktur, die einem Funktionsaufruf ähnelt:

Column(type: int, nulls: yes)

In PHP wird dies als Objekt Nette\Neon\Entity geparst:

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

Entitäten können auch verkettet werden:

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

Was in PHP auf diese Weise geparst wird:

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

Innerhalb der Klammern gelten die Regeln für die Inline-Schreibweise, die bei Zuordnungen und Sequenzen verwendet wird, d. h., sie kann auch mehrzeilig sein, und dann müssen keine Kommas angegeben werden:

Column(
	type: int
	nulls: yes
)

Kommentare

Kommentare beginnen mit dem Zeichen #, und alle folgenden Zeichen rechts davon werden ignoriert:

# diese Zeile wird vom Interpreter ignoriert
street: 742 Evergreen Terrace
city: Springfield  # dies wird ebenfalls ignoriert
country: USA

Neon versus JSON

JSON ist eine Teilmenge von NEON. Jedes JSON kann daher als NEON geparst werden:

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

Was wäre, wenn wir die Anführungszeichen weglassen würden?

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

Und die geschweiften Klammern und Kommas?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Sind Listen mit Aufzählungszeichen nicht besser lesbar?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Fügen wir Kommentare hinzu?

# meine Webanwendungskonfiguration

php:
	date.timezone: Europe/Prague
	zlib.output_compression: true  # gzip verwenden

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Hurra, jetzt kennen Sie die Syntax von NEON!

  1. Dokumentation
  2. Arbeiten mit NEON
  3. Das NEON-Format
Version: 3.4