Formato NEON

NEON es un formato de datos estructurados legible por humanos. En Nette se utiliza para archivos de configuración. También se utiliza para datos estructurados, como configuraciones, traducciones de idiomas, etc. Pruébelo.

NEON es la abreviatura de Nette Object Notation. Es menos complejo y torpe que XML o JSON, pero proporciona funciones similares. Es muy similar a YAML. La principal ventaja es que NEON tiene las llamadas entidades, gracias a las cuales la configuración de los servicios DI es tan sexy. Y permite la indentación con tabuladores.

NEON está construido desde cero para ser fácil de usar.

Integración

• NetBeans (tiene soporte incorporado)
• PhpStorm (plugin)
• Visual Studio Code (Nette Latte + Neon) o Nette for VS Code)
• Sublime Text 3 (plugin)
• Sublime Text 2 (plugin)
• VIM (plugin)
• Emacs (plugin)
• Prism.js (lenguaje integrado)

• NEON for PHP
• NEON for JavaScript
• NEON for Python.

Sintaxis

Un archivo escrito en NEON generalmente representa un array o un mapeo.

Mapeo

Un mapeo es un conjunto de pares clave-valor, en PHP se diría un array asociativo. Cada par se escribe como key: value, el espacio después de : es necesario. El valor puede ser cualquier cosa: cadena, número, booleano, null, secuencia u otro mapeo.

street: 742 Evergreen Terrace
city: Springfield
country: USA

En PHP, la misma estructura se escribiría como:

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

Esta notación se llama de bloque, porque todos los elementos están en una línea separada y tienen la misma indentación (en este caso, ninguna). NEON también admite una representación en línea para mapeos, que está encerrada entre llaves, la indentación no juega ningún papel y el separador de elementos individuales es una coma o una nueva línea:

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

Lo mismo escrito en varias líneas (la indentación no importa):

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

En lugar de : también se puede usar = alternativamente, tanto en la notación de bloque como en línea:

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

Secuencia

Las secuencias son arrays indexados en PHP. Se escriben como líneas que comienzan con un guión - seguido de un espacio. El valor nuevamente puede ser cualquier cosa: cadena, número, booleano, null, secuencia u otro mapeo.

- Cat
- Dog
- Goldfish

En PHP, la misma estructura se escribiría como:

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

Esta notación se llama de bloque, porque todos los elementos están en una línea separada y tienen la misma indentación (en este caso, ninguna). NEON también admite una representación en línea para secuencias, que está encerrada entre corchetes, la indentación no juega ningún papel y el separador de elementos individuales es una coma o una nueva línea:

[Cat, Dog, Goldfish]

Lo mismo escrito en varias líneas (la indentación no importa):

[
	Cat, Dog
		Goldfish
]

En la representación en línea no se pueden usar guiones de indentación.

Combinaciones

Los valores de mapeos y secuencias pueden ser otros mapeos y secuencias. El nivel de indentación juega un papel principal. En el siguiente ejemplo, el guión utilizado para indicar los elementos de la secuencia tiene una indentación mayor que la clave pets, por lo que los elementos se convierten en el valor de la primera línea:

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

En PHP, la misma estructura se escribiría como:

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

Se puede combinar la notación de bloque y en línea:

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

Dentro de la notación en línea ya no se puede usar la notación de bloque, esto no funciona:

item: [
	pets:
	 - Cat     # ¡¡¡ESTO NO SE PUEDE!!!
	 - Dog
]

En el caso anterior, escribimos un mapeo cuyos elementos eran secuencias, ahora intentaremos lo contrario y crearemos una secuencia que contenga mapeos:

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

No es necesario que los guiones estén en líneas separadas, también se pueden colocar de esta manera:

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

Depende de usted si alinea las claves en una columna usando espacios o usa un tabulador.

Dado que en PHP se utiliza la misma estructura para mapeos y secuencias, es decir, arrays, se pueden fusionar ambos. La indentación esta vez es la misma:

- Cat
street: 742 Evergreen Terrace
- Goldfish

En PHP, la misma estructura se escribiría como:

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

Cadenas

Las cadenas en NEON se pueden encerrar entre comillas simples o dobles. Pero como puede ver, también pueden estar sin comillas.

- Cadena en NEON sin comillas
- 'Cadena en NEON en comillas simples'
- "Cadena en NEON en comillas dobles"

Si la cadena contiene los caracteres # " ' , : = - [ ] { } ( ), que pueden confundirse con la sintaxis NEON, debe encerrarse entre comillas. Recomendamos usar comillas simples, ya que en ellas no se usa el escapado. Si necesita escribir una comilla en dicha cadena, duplíquela:

'Comilla '' dentro de una cadena en comillas simples'

Las comillas dobles permiten usar secuencias de escape para escribir caracteres especiales usando barras invertidas \. Se admiten todas las secuencias de escape como en el formato JSON y además \_, que es un espacio indivisible, es decir, \u00A0.

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

Hay otros casos en los que es necesario encerrar las cadenas entre comillas:

• comienzan o terminan con espacios
• parecen números, booleanos o null
• NEON las entendería como fecha

Cadenas multilínea

Una cadena multilínea comienza y termina con comillas triples en líneas separadas. La indentación de la primera línea se ignora para todas las líneas:

'''
	primera línea
		segunda línea
	tercera línea
	'''

En PHP escribiríamos lo mismo como:

"primera línea\n\tsegunda línea\ntercera línea" // PHP

Las secuencias de escape solo funcionan en cadenas encerradas entre comillas dobles en lugar de apóstrofes:

"""
	Copyright \u00A9
"""

Números

NEON entiende los números escritos en la llamada notación científica y también los números en sistemas binario, octal y hexadecimal:

- 12         # entero
- 12.3       # float
- +1.2e-34   # número exponencial

- 0b11010    # número binario
- 0o666      # número octal
- 0x7A       # número hexadecimal

Nulos

Null se puede expresar en NEON usando null o no especificando un valor. También se permiten variantes con la primera letra en mayúscula o todas las letras en mayúscula.

a: null
b:

Booleanos

Los valores lógicos se expresan en NEON usando true / false o yes / no. También se permiten variantes con la primera letra en mayúscula o todas las letras en mayúscula.

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

Fecha

NEON utiliza los siguientes formatos para expresar fechas y los convierte automáticamente en objetos DateTimeImmutable:

- 2016-06-03                  # fecha
- 2016-06-03 19:00:00         # fecha y hora
- 2016-06-03 19:00:00.1234    # fecha y microsegundos
- 2016-06-03 19:00:00 +0200   # fecha y hora y zona
- 2016-06-03 19:00:00 +02:00  # fecha y hora y zona

Entidades

Una entidad es una estructura que se asemeja a una llamada a función:

Column(type: int, nulls: yes)

En PHP se analiza como un objeto Nette\Neon\Entity:

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

Las entidades también se pueden encadenar:

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

Lo cual se analiza en PHP de esta manera:

// 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 de los paréntesis se aplican las reglas para la notación en línea utilizada para mapeos y secuencias, por lo que también puede ser multilínea y entonces no es necesario indicar comas:

Column(
	type: int
	nulls: yes
)

Comentarios

Los comentarios comienzan con el carácter # y todos los caracteres siguientes a la derecha son ignorados:

# esta línea será ignorada por el intérprete
street: 742 Evergreen Terrace
city: Springfield  # esto también se ignora
country: USA

Neon versus JSON

JSON es un subconjunto de NEON. Por lo tanto, cada JSON se puede analizar como NEON:

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

¿Qué pasaría si omitiéramos las comillas?

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

¿Y las llaves y las comas?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

¿No son las listas con guiones más legibles?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

¿Añadimos comentarios?

# configuración de mi aplicación web

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

¡Hurra, ahora conoces la sintaxis de NEON!