Format NEON

NEON est un format de données structurées 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.

NEON est l'acronyme de Nette Object Notation. Il est moins complexe et lourd que XML ou JSON, mais offre des fonctionnalités similaires. Il est très similaire à YAML. Le principal avantage est que NEON possède ce qu'on appelle des #entités, grâce auxquelles la configuration des services DI est aussi sexy. Et il permet d'indenter avec des tabulations.

NEON est construit dès le départ pour être facile à utiliser.

Intégration

• NetBeans (support intégré)
• PhpStorm (plugin)
• Visual Studio Code (Nette Latte + Neon) ou Nette for VS Code)
• 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 représente généralement un tableau ou un mapping.

Mapping

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

street: 742 Evergreen Terrace
city: Springfield
country: USA

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

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

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

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

La même chose écrite sur plusieurs lignes (l'indentation n'a pas d'importance) :

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

Au lieu de : , on peut alternativement utiliser = et ce, aussi bien en notation bloc qu'en ligne :

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

Séquence

Les séquences sont des tableaux indexés en PHP. Elles sont écrites comme des lignes commençant par un tiret - suivi d'un espace. La valeur peut à nouveau être n'importe quoi : chaîne, nombre, booléen, null, séquence ou autre mapping.

- Cat
- Dog
- Goldfish

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

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

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

[Cat, Dog, Goldfish]

La même chose écrite sur plusieurs lignes (l'indentation n'a pas d'importance) :

[
	Cat, Dog
		Goldfish
]

Dans la représentation en ligne, on ne peut pas utiliser les tirets d'indentation.

Combinaisons

Les valeurs des mappings et des séquences peuvent être d'autres mappings et séquences. Le niveau d'indentation joue un rôle principal. Dans l'exemple suivant, le tiret utilisé pour marquer les éléments de la séquence a une indentation plus grande que la clé 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 serait écrite comme :

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

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

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

À l'intérieur de la notation en ligne, on ne peut plus utiliser la notation bloc, ceci ne fonctionne pas :

item: [
	pets:
	 - Cat     # CECI N'EST PAS 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 tirets soient sur des lignes distinctes, on peut aussi les placer de cette manière :

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

C'est à vous de décider si vous alignez les clés en colonne à l'aide d'espaces ou si vous utilisez une tabulation.

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

- Cat
street: 742 Evergreen Terrace
- Goldfish

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

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

Chaînes de caractères

Les chaînes en NEON peuvent être enfermées entre guillemets simples ou doubles. Mais comme vous pouvez le voir, elles peuvent aussi être sans guillemets.

- Chaîne en NEON sans guillemets
- 'Chaîne en NEON entre guillemets simples'
- "Chaîne en NEON entre guillemets doubles"

Si la chaîne contient les caractères # " ' , : = - [ ] { } ( ), qui peuvent être confondus avec la syntaxe NEON, il faut l'enfermer entre guillemets. Nous recommandons d'utiliser des guillemets simples, car ils n'utilisent pas d'échappement. Si vous avez besoin d'écrire un guillemet dans une telle chaîne, doublez-le :

'Guillemet '' à l''intérieur d''une chaîne entre guillemets simples'

Les guillemets doubles permettent d'utiliser des séquences d'échappement pour écrire des caractères spéciaux à l'aide de barres obliques inverses \. Toutes les séquences d'échappement comme pour le format JSON sont prises en charge, ainsi que \_, qui est une espace insécable, c'est-à-dire \u00A0.

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

Il existe d'autres cas où il est nécessaire d'enfermer les chaînes entre guillemets :

• elles commencent ou se terminent par des espaces
• elles ressemblent à des nombres, des booléens ou null
• NEON les comprendrait comme une #date

Chaînes multilignes

Une chaîne multiligne commence et se termine par trois guillemets sur des lignes distinctes. L'indentation de la première ligne est ignorée, et ce pour toutes les lignes :

'''
	première ligne
		deuxième ligne
	troisième ligne
	'''

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

"première ligne\n\tdeuxième ligne\ntroisième ligne" // PHP

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

"""
	Copyright \u00A9
"""

Nombres

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

- 12         # entier
- 12.3       # float
- +1.2e-34   # nombre exponentiel

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

Nulls

Null peut être exprimé en NEON à l'aide de null ou en n'indiquant pas de valeur. Les variantes avec la première lettre en majuscule ou toutes les lettres en majuscules sont également autorisées.

a: null
b:

Booléens

Les valeurs logiques sont exprimées en NEON à l'aide de true / false ou yes / no. Les variantes avec la première lettre en majuscule ou toutes les lettres en majuscules sont également autorisées.

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

Date

NEON utilise les formats suivants pour exprimer les dates et les convertit automatiquement en objets DateTimeImmutable :

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

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 chaînées :

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

Ce qui est analysé en PHP de cette manière :

// 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 la notation en ligne utilisées pour les mappings et les séquences s'appliquent, c'est-à-dire qu'elle peut être sur plusieurs lignes et il n'est alors pas nécessaire d'indiquer les virgules :

Column(
	type: int
	nulls: yes
)

Commentaires

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

# this line will be ignored by the interpreter
street: 742 Evergreen Terrace
city: Springfield  # this is ignored too
country: USA

Neon versus JSON

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

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

Et si nous omettions les guillemets ?

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

Et les accolades et les virgules ?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Les listes avec des tirets ne sont-elles pas plus lisibles ?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Ajoutons des commentaires ?

# 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

Hourra, vous connaissez maintenant la syntaxe NEON !