Formato NEON

NEON è un formato di dati strutturati leggibile dalle persone. In Nette si usa per i file di configurazione. Si usa anche per dati strutturati come impostazioni, traduzioni linguistiche ecc. Provatelo nella sandbox.

NEON sta per Nette Object Notation. È meno complesso e macchinoso di XML o JSON, ma offre possibilità simili. È molto simile a YAML. Il vantaggio principale è che NEON ha le cosiddette entità, grazie alle quali la configurazione dei servizi DI è così sexy. E permette le tabulazioni per l'indentazione.

NEON è costruito fin dalle fondamenta per essere facile da usare.

Integrazione

Sintassi

Un file scritto in NEON rappresenta di solito una sequenza o una mappatura.

Mappature

Una mappatura è un insieme di coppie chiave-valore; in PHP si chiamerebbe array associativo. Ogni coppia si scrive come chiave: valore, lo spazio dopo : è obbligatorio. Il valore può essere qualsiasi cosa: stringa, numero, booleano, null, sequenza oppure un'altra mappatura.

street: 742 Evergreen Terrace
city: Springfield
country: USA

In PHP la stessa struttura si scriverebbe così:

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

Questa notazione si chiama notazione a blocchi, perché tutti gli elementi stanno su righe separate e hanno la stessa indentazione (in questo caso nessuna). NEON supporta per le mappature anche una rappresentazione inline, che si racchiude tra parentesi graffe, in cui l'indentazione non ha alcun ruolo e il separatore degli elementi è la virgola oppure il fine riga:

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

La stessa cosa scritta su più righe (l'indentazione non conta):

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

In alternativa si può usare = al posto di : , sia nella notazione a blocchi sia in quella inline:

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

Sequenze

Le sequenze sono gli array indicizzati di PHP. Si scrivono come righe che iniziano con un trattino - seguito da uno spazio. Anche qui il valore può essere qualsiasi cosa: stringa, numero, booleano, null, sequenza oppure un'altra mappatura.

- Cat
- Dog
- Goldfish

In PHP la stessa struttura si scriverebbe così:

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

Questa notazione si chiama notazione a blocchi, perché tutti gli elementi stanno su righe separate e hanno la stessa indentazione (in questo caso nessuna). NEON supporta per le sequenze anche una rappresentazione inline, che si racchiude tra parentesi quadre, in cui l'indentazione non ha alcun ruolo e il separatore degli elementi è la virgola oppure il fine riga:

[Cat, Dog, Goldfish]

La stessa cosa scritta su più righe (l'indentazione non conta):

[
	Cat, Dog
		Goldfish
]

Nella rappresentazione inline non si possono usare i trattini (i puntini elenco).

Combinazioni

I valori delle mappature e delle sequenze possono essere altre mappature e sequenze. Il livello di indentazione ha un ruolo fondamentale. Nell'esempio seguente il trattino che indica gli elementi della sequenza ha un'indentazione maggiore della chiave pets, quindi gli elementi diventano il valore della prima riga:

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

In PHP la stessa struttura si scriverebbe così:

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

Si possono combinare la notazione a blocchi e quella inline:

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

La notazione a blocchi non si può usare dentro una notazione inline; questo non funziona:

item: [
	pets:
	 - Cat     # QUESTO NON È POSSIBILE!!!
	 - Dog
]

Nel caso precedente abbiamo scritto una mappatura i cui elementi erano sequenze. Proviamo ora il contrario e creiamo una sequenza che contiene mappature:

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

Non è necessario che i trattini stiano su righe separate, si possono anche disporre così:

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

Sta a voi decidere se allineare le chiavi in colonna con gli spazi oppure usare un carattere di tabulazione.

Poiché PHP usa la stessa struttura per le mappature e le sequenze (cioè gli array), le due cose si possono fondere. Questa volta l'indentazione è la stessa:

- Cat
street: 742 Evergreen Terrace
- Goldfish

In PHP la stessa struttura si scriverebbe così:

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

Stringhe

Le stringhe in NEON si possono racchiudere tra apici singoli o doppi. Ma, come vedete, possono anche stare senza virgolette.

- Una stringa senza virgolette in NEON
- 'Una stringa tra apici singoli in NEON'
- "Una stringa tra virgolette doppie in NEON"

Se la stringa contiene i caratteri ` # " ' ` , : = - [ ] { } ( ) `, che si potrebbero confondere con la sintassi di NEON, va racchiusa tra virgolette. Consigliamo gli apici singoli, perché non usano l'escaping. Se dovete inserire un apice in una stringa del genere, raddoppiatelo:

'Un apice singolo '' dentro una stringa tra apici singoli'

Le virgolette doppie permettono di usare le sequenze di escape per scrivere caratteri speciali con la barra rovesciata \. Sono supportate tutte le sequenze di escape supportate dal formato JSON, più \_, che rappresenta uno spazio non separabile, cioè \u00A0.

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

Ci sono altri casi in cui bisogna racchiudere le stringhe tra virgolette:

  • iniziano o finiscono con degli spazi
  • sembrano numeri, booleani o null
  • NEON le interpreterebbe come date

Stringhe su più righe

Una stringa su più righe inizia e finisce con tre apici su righe separate. L'indentazione della prima riga viene ignorata per tutte le righe:

'''
	prima riga
		seconda riga
	terza riga
	'''

In PHP scriveremmo la stessa cosa così:

"prima riga\n\tseconda riga\nterza riga" // PHP

Le sequenze di escape funzionano solo per le stringhe racchiuse tra virgolette doppie invece che tra apici:

"""
	Copyright \u00A9
"""

Numeri

NEON comprende i numeri scritti in notazione scientifica e anche i numeri in base binaria, ottale ed esadecimale:

- 12         # numero intero
- 12.3       # numero in virgola mobile
- +1.2e-34   # numero esponenziale

- 0b11010    # numero binario
- 0o666      # numero ottale
- 0x7A       # numero esadecimale

Null

Null si può esprimere in NEON con null oppure omettendo il valore. Sono consentite anche le varianti con la prima lettera maiuscola o tutte maiuscole (Null, NULL).

a: null
b:

Booleani

I valori booleani si esprimono in NEON con true / false oppure yes / no. Sono consentite anche le varianti con la prima lettera maiuscola o tutte maiuscole (True, TRUE, False, FALSE, Yes, YES, No, NO).

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

Date

NEON usa questi formati per esprimere le date e le converte automaticamente in oggetti DateTimeImmutable:

- 2016-06-03                  # data
- 2016-06-03 19:00:00         # data e ora
- 2016-06-03 19:00:00.1234    # data e ora con microsecondi
- 2016-06-03 19:00:00 +0200   # data, ora e fuso orario
- 2016-06-03 19:00:00 +02:00  # data, ora e fuso orario

Entità

Un'entità è una struttura che assomiglia alla chiamata di una funzione:

Column(type: int, nulls: yes)

In PHP viene analizzata come oggetto Nette\Neon\Entity:

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

Le entità si possono anche concatenare:

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

Il che in PHP viene analizzato così:

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

Dentro le parentesi valgono le regole della notazione inline usata per mappature e sequenze, quindi si può andare su più righe e le virgole non sono necessarie:

Column(
	type: int
	nulls: yes
)

Commenti

I commenti iniziano con # e tutti i caratteri successivi a destra vengono ignorati:

# questa riga verrà ignorata dall'interprete
street: 742 Evergreen Terrace
city: Springfield  # anche questo viene ignorato
country: USA

NEON e JSON a confronto

JSON è un sottoinsieme di NEON. Qualsiasi JSON si può quindi analizzare come NEON:

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

E se omettessimo le virgolette?

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

E che ne dite delle parentesi e delle virgole?

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

database:
	driver: mysql
	username: root
	password: password123

users: [
	Dave, Kryten, Rimmer
]

Gli elenchi con i puntini non sono più leggibili?

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

database:
	driver: mysql
	username: root
	password: password123

users:
	- Dave
	- Kryten
	- Rimmer

Aggiungiamo dei commenti?

# configurazione della mia applicazione web

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

database:
	driver: mysql
	username: root
	password: password123

users:
	- Dave
	- Kryten
	- Rimmer

Evviva, ora conoscete la sintassi di NEON!

  1. Documentazione
  2. Nette NEON
  3. Formato NEON
versione: 3.x