NEON sandbox

NEON is a human-readable structured data format. It is used for structured data such as configuration files, settings, language translations, etc.

NEON stands for Nette Object Notation. It is less complex and ungainly than XML or JSON, but provides similar capabilities. It is very similar to YAML. The main advantage is that NEON has so-called entities, thanks to which the configuration of DI services is so sexy. And allowes tabs for indentation.

NEON is built from the ground up to be simple to use.

Libraries

NEON for PHP for JavaScript for Python

…or install using composer require nette/neon

Integrations

Syntax

A file written in NEON usually consists of a sequence or mapping.

Mappings

Mapping is a set of key-value pairs, (ie hashes, dictionary, in PHP it would be called an associative array). Each pair is written as key: value, a space after : is required. The value can be anything: string, number, boolean, null, sequence, or other mapping.

street: 742 Evergreen Terrace
city: Springfield
country: USA

This notation is called a block notation because all items are on a separate line and have the same indentation (none in this case). NEON also supports inline representation for mapping, which is enclosed in brackets, indentation plays no role, and the separator of each element is either a comma or a newline:

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

This is the same written on multiple lines (indentation does not matter):

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

Alternatively, = can be used instead of : , both in block and inline notation:

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

Sequences

Sequences are indexed arrays. They are written as lines starting with the hyphen - followed by a space. Again, the value can be anything: string, number, boolean, null, sequence, or other mapping.

- Cat
- Dog
- Goldfish

This notation is called a block notation because all items are on a separate line and have the same indentation (none in this case). NEON also supports inline representation for sequences, which is enclosed in brackets, indentation plays no role, and the separator of each element is either a comma or a newline:

[Cat, Dog, Goldfish]

This is the same written on multiple lines (indentation does not matter):

[
	Cat, Dog
		Goldfish
]

Hyphens cannot be used in an inline representation.

Combination

Values of mappings and sequences may be other mappings and sequences. The level of indentation plays a major role. In the following example, the hyphen used to indicate sequence items has a greater indent than the pets key, so the items become the value of the first line:

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

It is possible to combine block and inline notation:

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

Block notation can no longer be used inside an inline notation, this does not work:

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

Strings

Strings in NEON can be enclosed in single or double quotes. But as you can see, they can also be without quotes.

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

If the string contains characters that can be confused with NEON syntax (hyphens, colons, etc.), it must be enclosed in quotation marks. We recommend using single quotes because they do not use escaping. If you need to enclose a quotation mark in such a string, double it:

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

Double quotes allow you to use escape sequences to write special characters using backslashes \. All escape sequences as in the JSON format are supported, plus \_, which is an non-breaking space, ie \u00A0.

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

There are other cases where you need to enclose strings in quotation marks:

they begin or end with spaces
look like numbers, booleans, or null
NEON would understand them as dates

Multiline strings

A multiline string begins and ends with a triple quotation mark on separate lines. The indent of the first line is ignored for all lines:

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

Escaping sequences only work for strings enclosed in double quotes instead of apostrophes:

"""
	Copyright \u00A9
"""

Numbers

NEON understands numbers written in so-called scientific notation and also numbers in binary, octal and hexadecimal:

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

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

Nulls

Null can be expressed in NEON by using null or by not specifying a value. Variants with a capital first or all uppercase letters are also allowed.

a: null
b:

Booleans

Boolean values are expressed in NEON using true / false or yes / no. Variants with a capital first or all uppercase letters are also allowed.

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

Dates

NEON uses the following formats to express date:

- 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

Entities

An entity is a structure that resembles a function call:

Column(type: int, nulls: yes)

Entities can also be chained:

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

Inside the parentheses, the rules for inline notation used for mapping and sequences apply, so it can be divided into several lines and it is not necessary to add commas:

Column(
	type: int
	nulls: yes
)

Comments

Comments start with # and all of the following characters on the right are ignored:

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

NEON versus JSON

JSON is a subset of NEON. Each JSON can therefore be parsed as NEON:

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

What if we could omit quotes?

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

How about braces and commas?

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

database:
	driver: mysql
	username: root
	password: beruska92

users: [
	Dave, Kryten, Rimmer
]

Are bullets more legible?

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

database:
	driver: mysql
	username: root
	password: beruska92

users:
	- Dave
	- Kryten
	- Rimmer

How about comments?

# 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

You found NEON syntax!

neon sandbox

This is neon file - try to edit it!

This is result