NEON-Format

NEON ist ein von Menschen lesbares 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 in der Sandbox aus.

NEON steht für Nette Object Notation. Sie ist weniger komplex und unhandlich als XML oder JSON, bietet aber ähnliche Möglichkeiten. Sie ist sehr ähnlich zu YAML. Der Hauptvorteil ist, dass NEON sogenannte Entitäten hat, dank derer die Konfiguration von DI-Diensten so sexy ist. Und es erlaubt Tabs für die Einrückung.

NEON ist von Grund auf so aufgebaut, dass es einfach zu benutzen ist.

Einbindung

NetBeans (hat integrierte Unterstützung)
PhpStorm (Plugin)
Visual Studio Code(Nette Latte + Neon) oder Nette für VS Code)
Sublime Text 3 (Erweiterungsmodul)
Sublime Text 2 (Erweiterungsmodul)
VIM (Zusatzmodul)
Emacs (Zusatz programm)
Prism.js (integrierte Sprache)

Syntax

Eine in NEON geschriebene Datei besteht normalerweise aus einer Sequenz oder einem Mapping.

Mappings

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

street: 742 Evergreen Terrace
city: Springfield
country: USA

In PHP würde die gleiche Struktur wie folgt geschrieben werden:

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

Diese Notation wird als Blocknotation bezeichnet, da alle Elemente in einer separaten Zeile stehen und die gleiche Einrückung haben (in diesem Fall keine). NEON unterstützt auch die Inline-Darstellung für das Mapping, die in Klammern eingeschlossen ist, wobei die Einrückung keine Rolle spielt und das Trennzeichen jedes Elements entweder ein Komma oder ein Zeilenumbruch ist:

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

Dies ist das Gleiche in mehreren Zeilen geschrieben (Einrückung spielt keine Rolle):

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

Alternativ kann auch `=" anstelle von verwendet werden : sowohl in Block- als auch in Inline-Schreibweise verwendet werden:

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

Sequenzen

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

- Cat
- Dog
- Goldfish

In PHP würde die gleiche Struktur wie folgt geschrieben werden:

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

Diese Notation wird als Blocknotation bezeichnet, weil alle Elemente in einer separaten Zeile stehen und die gleiche Einrückung haben (in diesem Fall keine). NEON unterstützt auch die Inline-Darstellung für Sequenzen, die in eckige Klammern eingeschlossen ist, wobei die Einrückung keine Rolle spielt und das Trennzeichen jedes Elements entweder ein Komma oder ein Zeilenumbruch ist:

[Cat, Dog, Goldfish]

Dies ist das Gleiche auf mehreren Zeilen geschrieben (Einrückung spielt keine Rolle):

[
	Cat, Dog
		Goldfish
]

Bindestriche können in einer Inline-Darstellung nicht verwendet werden.

Kombination

Werte von Mappings und Sequenzen können andere Mappings und Sequenzen sein. Der Grad der Einrückung spielt eine wichtige Rolle. Im folgenden Beispiel hat der Bindestrich zur Kennzeichnung von Sequenzelementen einen größeren Einzug als die Taste pets, so dass die Elemente zum Wert der ersten Zeile werden:

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

In PHP würde die gleiche Struktur wie folgt geschrieben werden:

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

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

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

Die Blockschreibweise kann nicht mehr innerhalb einer Inline-Schreibweise verwendet werden, dies funktioniert nicht:

item: [
	pets:
	 - Cat     # THIS IS NOT POSSIBLE!!!
	 - Dog
]

Im vorherigen Fall haben wir eine Abbildung geschrieben, deren Elemente Sequenzen waren. Versuchen wir es nun andersherum und erstellen eine Sequenz, die Mappings enthält:

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

Die Aufzählungspunkte müssen nicht unbedingt in separaten Zeilen stehen, sondern können auch auf diese Weise platziert werden:

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

Es bleibt Ihnen überlassen, ob Sie die Tasten in einer Spalte mit Leerzeichen oder mit einem Tabulator ausrichten.

Da PHP die gleiche Struktur für Mapping und Sequenzen verwendet, nämlich Arrays, können beide zusammengeführt werden. Die Einrückung ist dieses Mal die gleiche:

- Cat
street: 742 Evergreen Terrace
- Goldfish

In PHP würde die gleiche 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.

- A unquoted string in NEON
- 'A singled-quoted string in NEON'
- "A double-quoted string in NEON"

Wenn die Zeichenkette Zeichen enthält # " ' , : = - [ ] { } ( ) enthält, die mit der NEON-Syntax verwechselt werden können, muss sie in Anführungszeichen gesetzt werden. Es wird empfohlen, einfache Anführungszeichen zu verwenden, da diese keine Umgehungszeichen verwenden. Wenn Sie ein Anführungszeichen in eine solche Zeichenfolge einschließen müssen, verdoppeln Sie es:

'A single quote '' inside a single-quoted string'

Mit doppelten Anführungszeichen können Sie Escape-Sequenzen verwenden, um Sonderzeichen mit Backslashes \. All escape sequences as in the JSON format are supported, plus \_ zu schreiben, d. h. mit einem nicht umbrechenden Leerzeichen \u00A0.

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

Es gibt noch andere Fälle, in denen Sie Zeichenketten in Anführungszeichen einschließen müssen:

wenn sie mit Leerzeichen beginnen oder enden
sie sehen aus wie Zahlen, Boolesche Werte oder Null
NEON würde sie als Datenverstehen

Mehrzeilige Zeichenketten

Eine mehrzeilige Zeichenkette beginnt und endet mit einem dreifachen Anführungszeichen in separaten Zeilen. Der Einzug der ersten Zeile wird für alle Zeilen ignoriert:

'''
	first line
		second line
	third line
	'''

In PHP würden wir das Gleiche wie folgt schreiben:

"first line\n\tsecond line\nthird line" // PHP

Escaping-Sequenzen funktionieren nur für Strings, die in doppelte Anführungszeichen statt in Apostrophe eingeschlossen sind:

"""
	Copyright \u00A9
"""

Zahlen

NEON versteht Zahlen in der so genannten wissenschaftlichen Notation sowie Zahlen in binärer, oktaler und hexadezimaler Schreibweise:

- 12 # eine ganze Zahl
- 12.3 # eine Gleitkommazahl
- +1.2e-34 # eine Exponentialzahl

- 0b11010 # Binärzahl
- 0o666 # Oktalzahl
- 0x7A # Hexa-Zahl

Nullen

Nullen können in NEON durch die Verwendung von null oder durch die Nichtangabe eines Wertes ausgedrückt werden. Varianten mit einem großen Anfangsbuchstaben oder nur Großbuchstaben sind ebenfalls erlaubt.

a: null
b:

Boolesche Werte

Boolesche Werte werden in NEON durch true / false oder yes / no ausgedrückt. Varianten mit einem großen Anfangsbuchstaben oder Großbuchstaben sind ebenfalls zulässig.

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

Daten

NEON verwendet die folgenden Formate, um Daten auszudrücken und konvertiert sie automatisch in DateTimeImmutable Objekte:

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

Entitäten

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

Column(type: int, nulls: yes)

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

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

Dies wird in PHP wie folgt geparst:

// 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-Notation, die für Mapping und Sequenzen verwendet werden, so dass sie in mehrere Zeilen aufgeteilt werden können und keine Kommas hinzugefügt werden müssen:

Column(
	type: int
	nulls: yes
)

Kommentare

Kommentare beginnen mit # und alle folgenden Zeichen auf der rechten Seite werden ignoriert:

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

NEON Versus JSON

JSON ist eine Untermenge 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 könnten?

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

Wie wäre es mit Klammern und Kommas?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Sind Aufzählungszeichen besser lesbar?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Wie sieht es mit Kommentaren aus?

# meine Webanwendungskonfiguration

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Sie haben die NEON-Syntax gefunden!

Nette Documentation Preview

NEON-Format

Einbindung

Syntax

Mappings

Sequenzen

Kombination

Zeichenketten

Mehrzeilige Zeichenketten

Zahlen

Nullen

Boolesche Werte

Daten

Entitäten

Kommentare

NEON Versus JSON