Nette Documentation Preview

syntax 
Формат NEON
***********

.[perex]
NEON - это человекочитаемый структурированный формат данных. В Nette он используется для файлов конфигурации. Он также используется для структурированных данных, таких как настройки, языковые переводы и т.д. [Попробуйте его в песочнице |https://ne-on.org].

NEON расшифровывается как *Nette Object Notation*. Она менее сложна и непритязательна, чем XML или JSON, но предоставляет аналогичные возможности. Он очень похож на YAML. Основное преимущество заключается в том, что NEON имеет так называемые [сущности |#entities], благодаря которым конфигурирование DI-сервисов [так сексуально |https://gist.github.com/dg/26baf3ce8f29d0f751e9dddfaa06504f]. И позволяет использовать табуляцию для отступов.

NEON создан с нуля, чтобы быть простым в использовании.


Интеграция .[#toc-integration]
==============================

- NetBeans (имеет встроенную поддержку)
- PhpStorm ([плагин |https://plugins.jetbrains.com/plugin/7060?pr])
- Visual Studio Code ([плагин |https://marketplace.visualstudio.com/items?itemName=Kasik96.latte])
- Sublime Text 3 ([плагин |https://github.com/FilipStryk/Nette-Latte-Neon-for-Sublime-Text-3])
- Sublime Text 2 ([плагин |https://github.com/Michal-Mikolas/Nette-package-for-Sublime-Text-2])
- VIM ([плагин |https://github.com/fpob/nette.vim])
- Emacs ([плагин |https://github.com/Fuco1/neon-mode])
- Prism.js ([интегрированный язык |https://prismjs.com/#supported-languages])


- [NEON для PHP |@home]
- [NEON для JavaScript |https://github.com/matej21/neon-js]
- [NEON для Python |https://github.com/paveldedik/neon-py].


Синтаксис .[#toc-syntax]
========================

Файл, написанный на NEON, обычно состоит из последовательности или отображения.


Сопоставления .[#toc-mappings]
------------------------------
Маппинг - это набор пар ключ-значение, в PHP это называется ассоциативным массивом. Каждая пара записывается как `key: value`, пробел после `:` обязателен. Значение может быть любым: строка, число, булево, null, последовательность или другое отображение.

```neon
street: 742 Evergreen Terrace
city: Springfield
country: USA
```

В PHP та же структура будет записана как:

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

Эта нотация называется блочной, потому что все элементы находятся на отдельной строке и имеют одинаковый отступ (в данном случае он отсутствует). NEON также поддерживает построчное представление для отображения, которое заключено в скобки, отступы не играют никакой роли, а разделителем каждого элемента является либо запятая, либо новая строка:

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

Это одно и то же, написанное на нескольких строках (отступ не имеет значения):

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

В качестве альтернативы можно использовать `=` вместо <code>: </code>, как в блочной, так и в инлайн-нотации:

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


Последовательности .[#toc-sequences]
------------------------------------
Последовательности - это индексированные массивы в PHP. Они записываются в виде строк, начинающихся с дефиса `-`, за которым следует пробел. Значение может быть любым: строка, число, булево, null, последовательность или другое отображение.

```neon
- Cat
- Dog
- Goldfish
```

В PHP та же структура будет выглядеть следующим образом:

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

Эта нотация называется блочной, потому что все элементы находятся на отдельной строке и имеют одинаковый отступ (в данном случае он отсутствует). NEON также поддерживает поточное представление последовательностей, которые заключаются в скобки, отступы не играют никакой роли, а разделителем каждого элемента является либо запятая, либо новая строка:

```neon
[Cat, Dog, Goldfish]
```

Это одно и то же, написанное на нескольких строках (отступ не имеет значения):

```neon
[
	Cat, Dog
		Goldfish
]
```

Дефисы не могут быть использованы в инлайн-представлении.


Комбинация .[#toc-combination]
------------------------------
Значения отображений и последовательностей могут быть другими отображениями и последовательностями. Уровень отступа играет важную роль. В следующем примере дефис, используемый для обозначения элементов последовательности, имеет больший отступ, чем ключ `pets`, поэтому элементы становятся значениями первой строки:

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

В PHP та же структура была бы записана как:

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

Можно комбинировать блочную и инлайн-нотацию:

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

Блочная нотация больше не может быть использована внутри строчной нотации, это не работает:

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

В предыдущем случае мы написали отображение, элементами которого были последовательности. Теперь попробуем сделать все наоборот и создать последовательность, содержащую отображения:

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

Не обязательно, чтобы пункты были расположены на отдельных строках, их можно расположить и таким образом:

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

Выравнивать ли ключи в колонке с помощью пробелов или табуляции - решать вам.

Поскольку PHP использует одну и ту же структуру для отображения и последовательностей, то есть массивы, оба варианта могут быть объединены. На этот раз отступы одинаковы:

```neon
- Cat
street: 742 Evergreen Terrace
- Goldfish
```

В PHP та же структура будет записана как:

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


Строки .[#toc-strings]
----------------------
Строки в NEON могут быть заключены в одинарные или двойные кавычки. Но, как вы видите, они могут быть и без кавычек.

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

Если строка содержит символы `# " ' , : = - [ ] { } ( )` которые можно спутать с синтаксисом NEON, она должна быть заключена в кавычки. Мы рекомендуем использовать одинарные кавычки, поскольку они не используют экранирование. Если вам нужно заключить кавычки в такой строке, удвойте их:

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

Двойные кавычки позволяют использовать экранирующие последовательности для записи специальных символов, используя обратные косые черты `\`. All escape sequences as in the JSON format are supported, plus `\_`, которые представляют собой неразрывный пробел, т.е. `\u00A0`.

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

Существуют и другие случаи, когда необходимо заключать строки в кавычки:
- они начинаются или заканчиваются пробелами
- выглядят как числа, булевы или null.
- NEON будет понимать их как [даты |#Dates]


Многострочные строки .[#toc-multiline-strings]
----------------------------------------------

Многострочная строка начинается и заканчивается тройной кавычкой на отдельных строках. Отступ первой строки игнорируется для всех строк:

```neon
'''
	first line
		second line
	third line
	'''
```

В PHP мы бы написали то же самое:

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

Последовательности экранирования работают только для строк, заключенных в двойные кавычки вместо апострофов:

```neon
"""
	Copyright \u00A9
"""
```


Числа .[#toc-numbers]
---------------------
NEON понимает числа, записанные в так называемой научной нотации, а также числа в двоичной, восьмеричной и шестнадцатеричной системе счисления:

```neon
- 12         # an integer
- 12.3       # a float
- +1.2e-34   # an exponential number

- 0b11010    # binary number
- 0o666      # octal number
- 0x7A       # hexa number
```


Нули .[#toc-nulls]
------------------
Нуль может быть выражен в NEON с помощью `null` или без указания значения. Также допускаются варианты с заглавной первой или всеми прописными буквами.

```neon
a: null
b:
```


Булевы .[#toc-booleans]
-----------------------
Булевы значения выражаются в NEON с помощью `true` / `false` или `yes` / `no`. Также допускаются варианты с заглавной первой или всеми прописными буквами.

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


Даты .[#toc-dates]
------------------
NEON использует следующие форматы для выражения данных и автоматически преобразует их в объекты `DateTimeImmutable`:

```neon
- 2016-06-03                  # date
- 2016-06-03 19:00:00         # date & time
- 2016-06-03 19:00:00.1234    # date & microtime
- 2016-06-03 19:00:00 +0200   # date & time & timezone
- 2016-06-03 19:00:00 +02:00  # date & time & timezone
```


Сущности .[#toc-entities]
-------------------------
Сущность - это структура, напоминающая вызов функции:

```neon
Column(type: int, nulls: yes)
```

В PHP она разбирается как объект [api:Nette\Neon\Entity]:

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

Сущности также могут быть объединены в цепочку:

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

Что разбирается в PHP следующим образом:

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

Внутри круглых скобок применяются правила инлайн-нотации, используемые для отображения и последовательностей, поэтому его можно разделить на несколько строк и нет необходимости добавлять запятые:

```neon
Column(
	type: int
	nulls: yes
)
```


Комментарии .[#toc-comments]
----------------------------
Комментарии начинаются с `#` и все последующие символы справа игнорируются:

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


NEON против JSON .[#toc-neon-versus-json]
=========================================
JSON является подмножеством NEON. Поэтому каждый JSON может быть разобран как NEON:

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

Что если бы мы могли опустить кавычки?

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

Как насчет скобок и запятых?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]
```

Являются ли пули более разборчивыми?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer
```

Как насчет комментариев?

```neon
# 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
```

Вы нашли синтаксис NEON!


{{description: NEON - это удобный для человека язык сериализации данных. Он похож на YAML. Основное отличие заключается в том, что NEON поддерживает "сущности" и символы табуляции для отступов.}}
{{leftbar: utils:@left-menu}}

Формат NEON

NEON – это человекочитаемый структурированный формат данных. В Nette он используется для файлов конфигурации. Он также используется для структурированных данных, таких как настройки, языковые переводы и т.д. Попробуйте его в песочнице.

NEON расшифровывается как Nette Object Notation. Она менее сложна и непритязательна, чем XML или JSON, но предоставляет аналогичные возможности. Он очень похож на YAML. Основное преимущество заключается в том, что NEON имеет так называемые сущности, благодаря которым конфигурирование DI-сервисов так сексуально. И позволяет использовать табуляцию для отступов.

NEON создан с нуля, чтобы быть простым в использовании.

Интеграция

Синтаксис

Файл, написанный на NEON, обычно состоит из последовательности или отображения.

Сопоставления

Маппинг – это набор пар ключ-значение, в PHP это называется ассоциативным массивом. Каждая пара записывается как key: value, пробел после : обязателен. Значение может быть любым: строка, число, булево, null, последовательность или другое отображение.

street: 742 Evergreen Terrace
city: Springfield
country: USA

В PHP та же структура будет записана как:

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

Эта нотация называется блочной, потому что все элементы находятся на отдельной строке и имеют одинаковый отступ (в данном случае он отсутствует). NEON также поддерживает построчное представление для отображения, которое заключено в скобки, отступы не играют никакой роли, а разделителем каждого элемента является либо запятая, либо новая строка:

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

Это одно и то же, написанное на нескольких строках (отступ не имеет значения):

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

В качестве альтернативы можно использовать = вместо : , как в блочной, так и в инлайн-нотации:

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

Последовательности

Последовательности – это индексированные массивы в PHP. Они записываются в виде строк, начинающихся с дефиса -, за которым следует пробел. Значение может быть любым: строка, число, булево, null, последовательность или другое отображение.

- Cat
- Dog
- Goldfish

В PHP та же структура будет выглядеть следующим образом:

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

Эта нотация называется блочной, потому что все элементы находятся на отдельной строке и имеют одинаковый отступ (в данном случае он отсутствует). NEON также поддерживает поточное представление последовательностей, которые заключаются в скобки, отступы не играют никакой роли, а разделителем каждого элемента является либо запятая, либо новая строка:

[Cat, Dog, Goldfish]

Это одно и то же, написанное на нескольких строках (отступ не имеет значения):

[
	Cat, Dog
		Goldfish
]

Дефисы не могут быть использованы в инлайн-представлении.

Комбинация

Значения отображений и последовательностей могут быть другими отображениями и последовательностями. Уровень отступа играет важную роль. В следующем примере дефис, используемый для обозначения элементов последовательности, имеет больший отступ, чем ключ pets, поэтому элементы становятся значениями первой строки:

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

В PHP та же структура была бы записана как:

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

Можно комбинировать блочную и инлайн-нотацию:

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

Блочная нотация больше не может быть использована внутри строчной нотации, это не работает:

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

В предыдущем случае мы написали отображение, элементами которого были последовательности. Теперь попробуем сделать все наоборот и создать последовательность, содержащую отображения:

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

Не обязательно, чтобы пункты были расположены на отдельных строках, их можно расположить и таким образом:

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

Выравнивать ли ключи в колонке с помощью пробелов или табуляции – решать вам.

Поскольку PHP использует одну и ту же структуру для отображения и последовательностей, то есть массивы, оба варианта могут быть объединены. На этот раз отступы одинаковы:

- Cat
street: 742 Evergreen Terrace
- Goldfish

В PHP та же структура будет записана как:

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

Строки

Строки в NEON могут быть заключены в одинарные или двойные кавычки. Но, как вы видите, они могут быть и без кавычек.

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

Если строка содержит символы # " ' , : = - [ ] { } ( ) которые можно спутать с синтаксисом NEON, она должна быть заключена в кавычки. Мы рекомендуем использовать одинарные кавычки, поскольку они не используют экранирование. Если вам нужно заключить кавычки в такой строке, удвойте их:

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

Двойные кавычки позволяют использовать экранирующие последовательности для записи специальных символов, используя обратные косые черты \. All escape sequences as in the JSON format are supported, plus \_, которые представляют собой неразрывный пробел, т.е. \u00A0.

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

Существуют и другие случаи, когда необходимо заключать строки в кавычки:

  • они начинаются или заканчиваются пробелами
  • выглядят как числа, булевы или null.
  • NEON будет понимать их как даты

Многострочные строки

Многострочная строка начинается и заканчивается тройной кавычкой на отдельных строках. Отступ первой строки игнорируется для всех строк:

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

В PHP мы бы написали то же самое:

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

Последовательности экранирования работают только для строк, заключенных в двойные кавычки вместо апострофов:

"""
	Copyright \u00A9
"""

Числа

NEON понимает числа, записанные в так называемой научной нотации, а также числа в двоичной, восьмеричной и шестнадцатеричной системе счисления:

- 12         # an integer
- 12.3       # a float
- +1.2e-34   # an exponential number

- 0b11010    # binary number
- 0o666      # octal number
- 0x7A       # hexa number

Нули

Нуль может быть выражен в NEON с помощью null или без указания значения. Также допускаются варианты с заглавной первой или всеми прописными буквами.

a: null
b:

Булевы

Булевы значения выражаются в NEON с помощью true / false или yes / no. Также допускаются варианты с заглавной первой или всеми прописными буквами.

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

Даты

NEON использует следующие форматы для выражения данных и автоматически преобразует их в объекты DateTimeImmutable:

- 2016-06-03                  # date
- 2016-06-03 19:00:00         # date & time
- 2016-06-03 19:00:00.1234    # date & microtime
- 2016-06-03 19:00:00 +0200   # date & time & timezone
- 2016-06-03 19:00:00 +02:00  # date & time & timezone

Сущности

Сущность – это структура, напоминающая вызов функции:

Column(type: int, nulls: yes)

В PHP она разбирается как объект Nette\Neon\Entity:

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

Сущности также могут быть объединены в цепочку:

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

Что разбирается в PHP следующим образом:

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

Внутри круглых скобок применяются правила инлайн-нотации, используемые для отображения и последовательностей, поэтому его можно разделить на несколько строк и нет необходимости добавлять запятые:

Column(
	type: int
	nulls: yes
)

Комментарии

Комментарии начинаются с # и все последующие символы справа игнорируются:

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

NEON против JSON

JSON является подмножеством NEON. Поэтому каждый JSON может быть разобран как NEON:

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

Что если бы мы могли опустить кавычки?

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

Как насчет скобок и запятых?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Являются ли пули более разборчивыми?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

Как насчет комментариев?

# 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

Вы нашли синтаксис NEON!