Format NEON

NEON est un format de données structuré lisible par l'homme. Dans Nette, il est utilisé pour les fichiers de configuration. Il est également utilisé pour les données structurées telles que les paramètres, les traductions linguistiques, etc. Essayez-le dans le bac à sable.

NEON signifie Nette Object Notation. Cette notation est moins complexe et moins gracieuse que XML ou JSON, mais elle offre des possibilités similaires. Il est très similaire à YAML. Le principal avantage est que NEON possède ce que l'on appelle des entités, grâce auxquelles la configuration des services DI est si sexy. Il autorise également les tabulations pour l'indentation.

NEON a été conçu dès le départ pour être simple à utiliser.

Intégration

• NetBeans (a un support intégré)
• PhpStorm (plugin)
• Visual Studio Code (plugin)
• Sublime Text 3 (plugin)
• Sublime Text 2 (plugin)
• VIM (plugin)
• Emacs (plugin)
• Prism.js (langage intégré)

• NEON pour PHP
• NEON pour JavaScript
• NEON pour Python.

Syntaxe

Un fichier écrit en NEON se compose généralement d'une séquence ou d'un mappage.

Mappages

Le mappage est un ensemble de paires clé-valeur, en PHP on l'appellerait un tableau associatif. Chaque paire est écrite comme key: value, un espace après : est nécessaire. La valeur peut être n'importe quoi : chaîne de caractères, nombre, booléen, null, séquence, ou tout autre mappage.

street: 742 Evergreen Terrace
city: Springfield
country: USA

En PHP, la même structure serait écrite comme suit :

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

Cette notation est appelée notation en bloc car tous les éléments sont sur une ligne séparée et ont la même indentation (aucune dans ce cas). NEON prend également en charge la représentation en ligne pour la cartographie, qui est placée entre parenthèses, l'indentation ne joue aucun rôle, et le séparateur de chaque élément est soit une virgule, soit un saut de ligne :

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

Il s'agit de la même chose écrite sur plusieurs lignes (l'indentation ne joue aucun rôle) :

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

Alternativement, = peut être utilisé à la place de : dans la notation en bloc et en ligne :

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

Séquences

Les séquences sont des tableaux indexés en PHP. Elles sont écrites comme des lignes commençant par le trait d'union - suivi d'un espace. Encore une fois, la valeur peut être n'importe quoi : chaîne de caractères, nombre, booléen, null, séquence, ou autre correspondance.

- Cat
- Dog
- Goldfish

En PHP, la même structure serait écrite comme suit :

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

Cette notation est appelée notation en bloc car tous les éléments sont sur une ligne séparée et ont la même indentation (aucune dans ce cas). NEON prend également en charge la représentation en ligne des séquences, qui sont placées entre parenthèses, l'indentation ne joue aucun rôle, et le séparateur de chaque élément est soit une virgule, soit un saut de ligne :

[Cat, Dog, Goldfish]

Il s'agit de la même chose écrite sur plusieurs lignes (l'indentation ne joue aucun rôle) :

[
	Cat, Dog
		Goldfish
]

Les traits d'union ne peuvent pas être utilisés dans une représentation en ligne.

Combinaison

Les valeurs des mappings et des séquences peuvent être d'autres mappings et séquences. Le niveau d'indentation joue un rôle important. Dans l'exemple suivant, le trait d'union utilisé pour indiquer les éléments de la séquence a une indentation supérieure à celle de la touche pets, de sorte que les éléments deviennent la valeur de la première ligne :

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

En PHP, la même structure s'écrirait comme suit :

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

Il est possible de combiner la notation en bloc et en ligne :

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

La notation en bloc ne peut plus être utilisée à l'intérieur d'une notation en ligne, cela ne fonctionne pas :

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

Dans le cas précédent, nous avons écrit un mapping dont les éléments étaient des séquences. Essayons maintenant l'inverse et créons une séquence contenant des mappings :

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

Il n'est pas nécessaire que les puces soient sur des lignes séparées ; elles peuvent également être placées de cette manière :

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

Il vous appartient d'aligner les clés dans une colonne en utilisant des espaces ou une tabulation.

Parce que PHP utilise la même structure pour le mapping et les séquences, c'est-à-dire les tableaux, les deux peuvent être fusionnés. L'indentation est la même cette fois :

- Cat
street: 742 Evergreen Terrace
- Goldfish

En PHP, la même structure s'écrirait comme suit :

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

Chaînes de caractères

Les chaînes de caractères dans NEON peuvent être entourées de guillemets simples ou doubles. Mais comme vous pouvez le voir, elles peuvent aussi être sans guillemets.

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

Si la chaîne contient des caractères # " ' , : = - [ ] { } ( ) qui peuvent être confondus avec la syntaxe NEON, elle doit être placée entre guillemets. Nous vous recommandons d'utiliser des guillemets simples car ils n'utilisent pas d'échappement. Si vous devez placer un guillemet dans une telle chaîne, doublez-le :

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

Les guillemets doubles vous permettent d'utiliser des séquences d'échappement pour écrire des caractères spéciaux à l'aide de barres obliques inversées \. All escape sequences as in the JSON format are supported, plus \_, qui est un espace insécable, c'est-à-dire \u00A0.

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

Il existe d'autres cas où vous devez mettre des chaînes de caractères entre guillemets :

• elles commencent ou se terminent par des espaces
• ressemblent à des nombres, des booléens ou des nullités
• NEON les comprendrait comme des dates

Chaînes de caractères multilignes

Une chaîne de caractères multiligne commence et se termine par un guillemet triple sur des lignes séparées. L'indentation de la première ligne est ignorée pour toutes les lignes :

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

En PHP, nous écririons la même chose que :

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

Les séquences d'échappement ne fonctionnent que pour les chaînes de caractères entourées de guillemets doubles au lieu d'apostrophes :

"""
	Copyright \u00A9
"""

Chiffres

NEON comprend les nombres écrits en notation dite scientifique ainsi que les nombres en binaire, octal et hexadécimal :

- 12 # un nombre entier
- 12.3 # un flottant
- +1.2e-34 # un nombre exponentiel

- 0b11010 # nombre binaire
- 0o666 # nombre octal
- 0x7A # nombre hexa

Nulls

Les nuls peuvent être exprimés dans NEON en utilisant null ou en ne spécifiant pas de valeur. Les variantes avec une première majuscule ou toutes les lettres majuscules sont également autorisées.

a: null
b:

Booléens

Les valeurs booléennes sont exprimées dans NEON en utilisant true / false ou yes / no. Les variantes avec une première majuscule ou toutes les lettres majuscules sont également autorisées.

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

Dates

NEON utilise les formats suivants pour exprimer les données et les convertit automatiquement en objets DateTimeImmutable:

- 2016-06-03 # date
- 2016-06-03 19:00:00 # date et heure
- 2016-06-03 19:00:00.1234 # date & microtime
- 2016-06-03 19:00:00 +0200 # date & heure & fuseau horaire
- 2016-06-03 19:00:00 +02:00 # date & heure & fuseau horaire

Entités

Une entité est une structure qui ressemble à un appel de fonction :

Column(type: int, nulls: yes)

En PHP, elle est analysée comme un objet Nette\Neon\Entity:

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

Les entités peuvent également être enchaînées :

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

Ce qui est analysé en PHP comme suit :

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

À l'intérieur des parenthèses, les règles de notation en ligne utilisées pour le mappage et les séquences s'appliquent, il peut donc être divisé en plusieurs lignes et il n'est pas nécessaire d'ajouter des virgules :

Column(
	type: int
	nulls: yes
)

Commentaires

Les commentaires commencent par # et tous les caractères suivants à droite sont ignorés :

# cette ligne sera ignorée par l'interpréteur
street: 742 Evergreen Terrace
city: Springfield # cette ligne est également ignorée
country: USA

NEON Versus JSON

JSON est un sous-ensemble de NEON. Chaque JSON peut donc être analysé comme du NEON :

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

Et si nous pouvions omettre les guillemets ?

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

Pourquoi pas des accolades et des virgules ?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Les puces sont-elles plus lisibles ?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Et les commentaires ?

# la configuration de mon application web

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Vous avez trouvé la syntaxe NEON !