Formato NEON

NEON é um formato de dados estruturados legível por humanos. Em Nette, ele é usado para arquivos de configuração. Também é usado para dados estruturados, tais como configurações, traduções de idiomas, etc. Experimente-o na caixa de areia.

NEON é a sigla de Nette Object Notation (Notação de Objetos NEON). Ele é menos complexo e pouco prático do que XML ou JSON, mas oferece recursos semelhantes. É muito semelhante ao YAML. A principal vantagem é que o NEON tem as chamadas entidades, graças às quais a configuração dos serviços de DI é muito atraente. E permite tabulações para indentação.

NEON é construído desde o início para ser simples de usar.

Integração

• NetBeans (tem suporte integrado)
• PhpStorm (plugin)
• Visual Studio Code(Nette Latte + Neon) ou Nette para VS Code)
• Texto Sublime 3 (plugin)
• Texto Sublime 2 (plugin)
• VIM (plugin)
• Emacs (plugin)
• Prism.js (linguagem integrada)

• NEON para PHP
• NEON para JavaScript
• NEON para Python.

Sintaxe

Um arquivo escrito em NEON geralmente consiste de uma seqüência ou mapeamento.

Mappings

O mapeamento é um conjunto de pares de valores-chave, em PHP seria chamado de matriz associativa. Cada par é escrito como key: value, um espaço após : é necessário. O valor pode ser qualquer coisa: string, número, booleano, nulo, seqüência, ou outro mapeamento.

street: 742 Evergreen Terrace
city: Springfield
country: USA

Em PHP, a mesma estrutura seria escrita como:

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

Esta notação é chamada de notação de bloco porque todos os itens estão em uma linha separada e têm o mesmo recuo (neste caso, nenhum). NEON também suporta a representação em linha para o mapeamento, que está entre parênteses, o recuo não tem nenhum papel, e o separador de cada elemento é ou uma vírgula ou uma nova linha:

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

Esta é a mesma escrita em várias linhas (indentação não importa):

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

Alternativamente, = pode ser utilizado em vez de : tanto na notação em bloco como na notação em linha:

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

Seqüências

As sequências são arrays indexados em PHP. Elas são escritas como linhas começando com o hífen - seguido por um espaço. Novamente, o valor pode ser qualquer coisa: string, número, booleano, nulo, seqüência, ou outro mapeamento.

- Cat
- Dog
- Goldfish

Em PHP, a mesma estrutura seria escrita como:

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

Esta notação é chamada de notação de bloco porque todos os itens estão em uma linha separada e têm o mesmo recuo (neste caso, nenhum). NEON também suporta a representação em linha para seqüências, que está entre parênteses, o recuo não tem nenhum papel, e o separador de cada elemento é ou uma vírgula ou uma nova linha:

[Cat, Dog, Goldfish]

Esta é a mesma escrita em várias linhas (indentação não importa):

[
	Cat, Dog
		Goldfish
]

Os hífens não podem ser usados em uma representação em linha.

Combinação

Os valores de mapeamentos e seqüências podem ser outros mapeamentos e seqüências. O nível de indentação tem um papel importante. No exemplo a seguir, o hífen usado para indicar itens de seqüência tem um traço maior do que a chave pets, de modo que os itens se tornam o valor da primeira linha:

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

Em PHP, a mesma estrutura seria escrita como:

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

É possível combinar a notação de bloco e em linha:

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

A notação de bloco não pode mais ser usada dentro de uma notação em linha, isto não funciona:

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

No caso anterior, escrevemos um mapeamento cujos elementos eram sequências. Agora, vamos tentar o contrário e criar uma sequência contendo mapeamentos:

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

Não é necessário que os marcadores estejam em linhas separadas; eles também podem ser colocados dessa maneira:

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

Fica a seu critério alinhar as chaves em uma coluna usando espaços ou tabulação.

Porque PHP usa a mesma estrutura para mapeamento e seqüências, ou seja, arrays, ambos podem ser fundidos. A indentação é a mesma desta vez:

- Cat
street: 742 Evergreen Terrace
- Goldfish

Em PHP, a mesma estrutura seria escrita como:

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

Cordas

As cordas em NEON podem ser colocadas entre aspas simples ou duplas. Mas, como você pode ver, elas também podem ser sem aspas.

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

Se o fio contiver caracteres # " ' , : = - [ ] { } ( ) que pode ser confundida com a sintaxe NEON, ela deve ser delimitada entre aspas. Recomendamos o uso de aspas simples, pois elas não utilizam fugas. Se você precisar incluir uma aspas em tal seqüência, duplique-a:

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

As citações duplas permitem utilizar sequências de escape para escrever caracteres especiais utilizando barras invertidas \. All escape sequences as in the JSON format are supported, plus \_, que é um espaço não quebrável, ou seja \u00A0.

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

Há outros casos em que é necessário colocar as cordas entre aspas:

• elas começam ou terminam com espaços
• parecem números, booleanos, ou nulos
• NEON as entenderia como datas

Cordas Multilíngües

Uma cadeia de várias linhas começa e termina com uma aspas triplas em linhas separadas. O traço da primeira linha é ignorado para todas as linhas:

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

Em PHP, nós escreveríamos o mesmo que:

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

As seqüências de fuga só funcionam para cordas fechadas em aspas duplas em vez de apóstrofes:

"""
	Copyright \u00A9
"""

Números

NEON entende números escritos na chamada notação científica e também números em binário, octal e hexadecimal:

- 12 # um número inteiro
- 12.3 # um carro alegórico
- +1.2e-34 # um número exponencial

- 0b11010 # número binário
- 0o666 # número de octal
- 0x7A # número hexa

Nulls

Nulo pode ser expresso em NEON usando null ou não especificando um valor. Também são permitidas variantes com letras maiúsculas em primeiro lugar ou todas as letras maiúsculas.

a: null
b:

Booleans

Os valores booleanos são expressos em NEON usando true / false ou yes / no. Também são permitidas variantes com letras maiúsculas em primeiro lugar ou todas as letras maiúsculas.

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

Datas

NEON usa os seguintes formatos para expressar dados e os converte automaticamente para DateTimeImmutable objetos:

- 2016-06-03 # data
- 2016-06-03 19:00:00 # data e hora
- 2016-06-03 19:00:00.1234 # data e microtempo
- 2016-06-03 19:00:00 +0200 # data & hora & fuso horário
- 2016-06-03 19:00:00 +02:00 # data & hora & fuso horário

Entidades

Uma entidade é uma estrutura que se assemelha a uma chamada de função:

Column(type: int, nulls: yes)

Em PHP, ele é analisado como um objeto Nette\Neon\Entity:

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

As entidades também podem ser encadeadas:

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

Que é analisado em PHP da seguinte forma:

// 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 dos parênteses, aplicam-se as regras de notação em linha utilizadas para o mapeamento e seqüências, de modo que pode ser dividida em várias linhas e não é necessário acrescentar vírgulas:

Column(
	type: int
	nulls: yes
)

Comentários

Os comentários começam com # e todos os caracteres a seguir à direita são ignorados:

# esta linha será ignorada pelo intérprete
rua: 742 Evergreen Terrace
cidade: Springfield # isto também é ignorado
país: EUA

NEON Versus JSON

O JSON é um subconjunto do NEON. Cada JSON pode, portanto, ser analisado como NEON:

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

E se pudéssemos omitir citações?

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

Que tal aparelhos e vírgulas?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

As balas são mais legíveis?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Que tal comentários?

# 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

Você encontrou a sintaxe NEON!