README

简介

NEON 是一种人类可读的结构化数据格式。在 Nette 中，它用于配置文件。它还用于结构化数据，例如设置、语言翻译等。 在沙盒中尝试。

NEON 代表 Nette 对象表示法。它比 XML 或 JSON 简单且不复杂，但提供类似的功能。它与 YAML 非常相似。主要优点是 NEON 有所谓的 实体，这使得 DI 服务的配置如此性感。还允许使用制表符进行缩进。

NEON 从一开始就是简单易用的。

支持 Neon

你喜欢 NEON 吗？你在期待新功能吗？

谢谢！

使用方法

通过 Composer 安装

composer require nette/neon

它需要 PHP 版本 8.0 至 8.4。文档可以在 网站上找到。

Neon::encode() 返回将 $value 转换为 NEON 的结果。作为第二个参数 $blockMode，您可以传递 true，这将创建多行输出。第三个参数 $indentation 指定用于缩进的字符（默认为制表符）。

use Nette\Neon\Neon;

$neon = Neon::encode($value); // Returns $value converted to NEON
$neon = Neon::encode($value, true); // Returns $value converted to multiline NEON

Neon::decode() 将给定的 NEON 转换为 PHP 值

$value = Neon::decode('hello: world'); // Returns an array ['hello' => 'world']

Neon::decodeFile() 将给定的 NEON 文件转换为 PHP 值

$value = Neon::decodeFile('config.neon');

所有方法在出错时都会抛出 Nette\Neon\Exception。

集成

• NetBeans（具有内置支持）

• PhpStorm（插件）

• Visual Studio Code（插件）

• Sublime Text 3（插件）

• Sublime Text 2（插件）

• NEON for PHP

• NEON for JavaScript

• NEON for Python.

您可以使用 neon-lint 控制台命令检查 Neon 文件中的语法错误

vendor/bin/neon-lint <path>

语法

用 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'

双引号允许您使用反斜杠\编写特殊字符的转义序列。支持与JSON格式相同的所有转义序列，还包括\_，即非断行空格，即\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语法！

如果你喜欢NEON，请立即捐赠。谢谢！