Formato NEON

NEON è un formato di dati strutturati leggibili dall'uomo. In Nette viene utilizzato per i file di configurazione. Viene utilizzato anche per i dati strutturati, come le impostazioni, le traduzioni delle lingue, ecc. Provatelo nella sandbox.

NEON è l'acronimo di Nette Object Notation. È meno complessa e sgraziata di XML o JSON, ma offre 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 permette di usare le tabulazioni per l'indentazione.

NEON è costruito da zero per essere semplice da usare.

Integrazione

• NetBeans (ha un supporto integrato)
• PhpStorm (plugin)
• Visual Studio Code (plugin)
• Sublime Text 3 (plugin)
• Sublime Text 2 (plugin)
• VIM (plugin)
• Emacs (plugin)
• Prism.js (linguaggio integrato)

• NEON per PHP
• NEON per JavaScript
• NEON per Python.

Sintassi

Un file scritto in NEON consiste solitamente in una sequenza o in una mappatura.

Mappature

La mappatura è un insieme di coppie chiave-valore, in PHP si chiamerebbe array associativo. Ogni coppia è scritta come key: value, è richiesto uno spazio dopo :. Il valore può essere qualsiasi cosa: stringa, numero, booleano, null, sequenza o altra mappatura.

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 una riga separata e hanno la stessa indentazione (nessuna in questo caso). NEON supporta anche la rappresentazione in linea per la mappatura, che è racchiusa tra parentesi, l'indentazione non gioca alcun ruolo e il separatore di ogni elemento è una virgola o una newline:

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

Si tratta dello stesso testo scritto su più righe (l'indentazione non ha importanza):

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

In alternativa, = può essere usato al posto di : , 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 il trattino - seguito da uno spazio. Anche in questo caso, il valore può essere qualsiasi cosa: stringa, numero, booleano, null, sequenza o altra mappatura.

- 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 una riga separata e hanno la stessa indentazione (nessuna in questo caso). NEON supporta anche la rappresentazione in linea per le sequenze, che sono racchiuse tra parentesi, l'indentazione non gioca alcun ruolo e il separatore di ogni elemento è una virgola o una newline:

[Cat, Dog, Goldfish]

Si tratta della stessa scrittura su più righe (l'indentazione non ha importanza):

[
	Cat, Dog
		Goldfish
]

I trattini non possono essere usati in una rappresentazione in linea.

Combinazione

I valori delle mappature e delle sequenze possono essere altre mappature e sequenze. Il livello di rientro gioca un ruolo importante. Nell'esempio seguente, il trattino usato per indicare gli elementi della sequenza ha un rientro maggiore rispetto al tasto 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 quella in linea:

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

La notazione a blocchi non può più essere utilizzata all'interno di una notazione in linea, non funziona:

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

Nel caso precedente, abbiamo scritto una mappatura i cui elementi erano sequenze. Proviamo ora a fare il contrario e a creare una sequenza contenente delle mappature:

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

Non è necessario che i punti elenco siano su righe separate; possono anche essere disposti in questo modo:

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

Sta a voi decidere se allineare i tasti in una colonna usando spazi o tabulazioni.

Poiché PHP utilizza la stessa struttura per le mappature e le sequenze, cioè gli array, entrambi possono essere uniti. L'indentazione è la stessa questa volta:

- 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 apici singoli o doppi. Ma, come si può vedere, possono anche essere senza apici.

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

Se la stringa contiene caratteri # " ' , : = - [ ] { } ( ) che possono essere confusi con la sintassi NEON, deve essere racchiusa tra virgolette. Si consiglia di utilizzare le virgolette singole perché non utilizzano l'escape. Se è necessario racchiudere una virgoletta in una stringa di questo tipo, raddoppiarla:

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

Le virgolette doppie consentono di utilizzare le sequenze di escape per scrivere caratteri speciali utilizzando i backslash \. All escape sequences as in the JSON format are supported, plus \_, ovvero uno spazio non spezzato, cioè \u00A0.

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

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

• iniziano o finiscono con spazi
• assomigliano a numeri, booleani o null
• NEON le interpreta come date

Stringhe multilinea

Una stringa multilinea inizia e termina con una tripla virgoletta su righe separate. Il rientro della prima riga viene ignorato per tutte le righe:

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

In PHP si scriverebbe come:

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

Le sequenze di escape funzionano solo per le stringhe racchiuse tra doppi apici anziché tra apostrofi:

"""
	Copyright \u00A9
"""

Numeri

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

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

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

Nulli

I null possono essere espressi in NEON utilizzando null o non specificando un valore. Sono ammesse anche varianti con la prima lettera maiuscola o con tutte le lettere maiuscole.

a: null
b:

Booleani

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

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

Date

NEON utilizza i seguenti formati per esprimere i dati e li 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 microtempo
- 2016-06-03 19:00:00 +0200 # data e ora e fuso orario
- 2016-06-03 19:00:00 +02:00 # data, ora e fuso orario

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)

Che viene analizzato in PHP come segue:

// 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, si applicano le regole di notazione inline utilizzate per le mappature e le sequenze, quindi può essere suddiviso in più righe e non è necessario aggiungere virgole:

Column(
	type: int
	nulls: yes
)

Commenti

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

# questa riga sarà ignorata dall'interprete
via: 742 Evergreen Terrace
città: Springfield # anche questa viene ignorata
paese: USA

NEON contro 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 potessimo omettere le virgolette?

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

Che ne dite di parentesi e virgole?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

I punti sono più leggibili?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

E 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

Avete trovato la sintassi NEON!