Formato NEON

NEON è un formato di dati strutturati leggibile dall'uomo. In Nette viene utilizzato per i file di configurazione. Viene utilizzato anche per dati strutturati come impostazioni, traduzioni linguistiche, ecc. Provatelo.

NEON è l'acronimo di Nette Object Notation. È meno complesso e goffo di XML o JSON, ma fornisce funzionalità 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 consente l'indentazione con tabulazioni.

NEON è costruito da zero per essere facile da usare.

Integrazione

Sintassi

Un file scritto in NEON di solito rappresenta un array o una mappa.

Mapping

Un mapping è un insieme di coppie chiave-valore, in PHP si direbbe array associativo. Ogni coppia è scritta come key: value, lo spazio dopo : è necessario. Il valore può essere qualsiasi cosa: stringa, numero, booleano, null, sequenza o un altro mapping.

street: 742 Evergreen Terrace
city: Springfield
country: USA

In PHP, la stessa struttura sarebbe scritta come:

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

Questa notazione è detta a blocchi, perché tutti gli elementi sono su righe separate e hanno la stessa indentazione (in questo caso nessuna). NEON supporta anche una rappresentazione inline dei mapping, che è racchiusa tra parentesi graffe, l'indentazione non gioca alcun ruolo e il separatore tra i singoli elementi è una virgola o un ritorno a capo:

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

Lo stesso scritto su più righe (l'indentazione non ha importanza):

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

In alternativa a : si può usare = sia nella notazione a blocchi che in quella inline:

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

Sequenze

Le sequenze sono array indicizzati in PHP. Sono scritte come righe che iniziano con un trattino - seguito da uno spazio. Il valore può essere di nuovo qualsiasi cosa: stringa, numero, booleano, null, sequenza o un altro mapping.

- Cat
- Dog
- Goldfish

In PHP, la stessa struttura sarebbe scritta come:

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

Questa notazione è detta a blocchi, perché tutti gli elementi sono su righe separate e hanno la stessa indentazione (in questo caso nessuna). NEON supporta anche una rappresentazione inline delle sequenze, che è racchiusa tra parentesi quadre, l'indentazione non gioca alcun ruolo e il separatore tra i singoli elementi è una virgola o un ritorno a capo:

[Cat, Dog, Goldfish]

Lo stesso scritto su più righe (l'indentazione non ha importanza):

[
	Cat, Dog
		Goldfish
]

Nella rappresentazione inline non è possibile utilizzare trattini indentati.

Combinazioni

I valori dei mapping e delle sequenze possono essere altri mapping e sequenze. Il ruolo principale è giocato dal livello di indentazione. Nell'esempio seguente, il trattino utilizzato per indicare gli elementi della sequenza ha un'indentazione maggiore rispetto alla chiave pets, quindi gli elementi diventano il valore della prima riga:

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

In PHP, la stessa struttura sarebbe scritta come:

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

È possibile combinare la notazione a blocchi e inline:

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

All'interno della notazione inline non è più possibile utilizzare la notazione a blocchi, questo non funziona:

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

Nel caso precedente abbiamo scritto un mapping i cui elementi erano sequenze, ora proviamo il contrario e creiamo una sequenza contenente mapping:

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

Non è necessario che i trattini siano su righe separate, possono essere posizionati anche in questo modo:

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

Sta a voi decidere se allineare le chiavi in colonne usando spazi o usare una tabulazione.

Poiché in PHP si usa la stessa struttura sia per i mapping che per le sequenze, cioè gli array, è possibile unire entrambi. L'indentazione questa volta è la stessa:

- Cat
street: 742 Evergreen Terrace
- Goldfish

In PHP, la stessa struttura sarebbe scritta come:

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

Stringhe

Le stringhe in NEON possono essere racchiuse tra virgolette singole o doppie. Ma come potete vedere, possono anche essere senza virgolette.

- Stringa in NEON senza virgolette
- 'Stringa in NEON tra virgolette singole'
- "Stringa in NEON tra virgolette doppie"

Se una stringa contiene i caratteri # " ' , : = - [ ] { } ( ), che possono essere confusi con la sintassi NEON, è necessario racchiuderla tra virgolette. Si consiglia di utilizzare le virgolette singole, perché in esse non viene utilizzato l'escaping. Se è necessario scrivere una virgoletta in una tale stringa, raddoppiatela:

'Virgoletta '' all\'interno di una stringa tra virgolette singole'

Le virgolette doppie consentono di utilizzare sequenze di escape per scrivere caratteri speciali usando le barre rovesciate \. Sono supportate tutte le sequenze di escape come nel formato JSON e inoltre \_, che è uno spazio indivisibile, cioè \u00A0.

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

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

  • iniziano o terminano con spazi
  • sembrano numeri, booleani o null
  • NEON li interpreterebbe come data

Stringhe multiriga

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

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

In PHP scriveremmo lo stesso come:

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

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

"""
	Copyright \u00A9
"""

Numeri

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

- 12         # intero
- 12.3       # float
- +1.2e-34   # numero esponenziale

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

Nulls

Null può essere espresso in NEON usando null o non specificando un valore. Sono consentite anche varianti con la prima lettera maiuscola o tutte le lettere maiuscole.

a: null
b:

Booleans

I valori logici sono espressi in NEON usando true / false o yes / no. Sono consentite anche varianti con la prima lettera maiuscola o tutte le lettere maiuscole.

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

Data

NEON utilizza i seguenti formati per esprimere le date e li converte automaticamente in oggetti DateTimeImmutable:

- 2016-06-03                  # data
- 2016-06-03 19:00:00         # data & ora
- 2016-06-03 19:00:00.1234    # data & microtempo
- 2016-06-03 19:00:00 +0200   # data & ora & zona
- 2016-06-03 19:00:00 +02:00  # data & ora & zona

Entità

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

Column(type: int, nulls: yes)

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

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

Le entità possono anche essere concatenate:

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

Il che viene analizzato in PHP in questo modo:

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

All'interno delle parentesi valgono le regole per la notazione inline utilizzata per mapping e sequenze, quindi può essere anche multiriga e in tal caso non è necessario specificare le virgole:

Column(
	type: int
	nulls: yes
)

Commenti

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

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

Neon versus JSON

JSON è un sottoinsieme di NEON. Ogni JSON può quindi essere analizzato come NEON:

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

E se omettessimo le virgolette?

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

E le parentesi graffe e le virgole?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Le liste con i trattini non sono più leggibili?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Aggiungiamo i commenti?

# 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

Evvai, ora conoscete la sintassi di NEON!

  1. Documentazione
  2. Lavorare con NEON
  3. Formato NEON
versione: 3.4