Module quartz_nbt::snbt

Provides support for parsing stringified NBT data.

SNBT is essentially an extension of JSON. It uses the same overarching syntax with some changes to enforce stronger types.

Numbers

Numbers in SNBT generally have a single-character suffix specifying their type (with i32 and f64 being exceptions). If a number without a decimal point is encountered without a type specifier, then the parser assumes it is an int. Likewise, if a number with a decimal point but no type specifier is encountered, then it is assumed to be a double. Note that the type specifier for doubles (D or d) is optional, however the integer type specifier (I or i) is reserved for arrays and cannot be appended to an integer. Examples are shown below:

• Byte (i8): 2B, -3b
• Short (i16): 17S, -1024s
• Int (i32): 123
• Long (i64): 43046721L
• Float (f32): 3.141F, 0.0f
• Double (f64): 18932.214, 10.2D

Booleans are encoded as bytes, so 0b represents false and 1b (or any non-zero byte value) represents true.

Strings

SNBT treats any sequence of unicode characters not representing another token to be a string. For this reason, strings are not required to be in quotes, however they can optionally be enclosed in either single or double quotes. In other words, foo is equivalent to "foo" and 'foo', and "\"quoted\"" is equivalent to '"quoted"'. Although Minecraft’s parser discourages the use of whitespace in SNBT, this parser implementation is fully capable of handling it. The way whitespace is ignored is by trimming strings, so if leading or trailing whitespace is required, then the string must be enclosed in quotes.

SNBT strings also support several escape sequences:

• \', \", \\: copies the second character verbatim
• \n: new line
• \r: carriage return
• \t: tab
• \uXXXX: an unsigned hex number representing a unicode character

These escape sequences are only applied if a string is surrounded by quotes. An unquoted escape sequence will be taken verbatim.

Arrays and Lists

There are three array types supported by Minecraft’s NBT formal: byte arrays, int arrays, and long arrays. To differentiate an NbtList from an array, arrays start with its values’ type specifier followed by a semicolon. For example, an empty int array is denoted by [I;], and an example of a long array is [L; -1, -2, -3]. It is not necessary to put a type specifier on the elements of an array, however the array must be homogenously typed, meaning each element is of the same type.

NBT lists also use the square bracket syntax, however they do not contain a type specifier. For example, a list of strings may look like [foo, bar, baz]. NBT lists, even though they theoretically can contain multiple different types, must also be homogenous. The parser will throw an error if the list is non-homogenous. Note that it is necessary to include the type specifier for each element in an NBT list where applicable.

Compounds

All valid SNBT strings have a compound as the root tag. Compounds, like JSON objects, follow the syntax of {key: value, ...}. Compounds must have every key be a string, but its values do not have to be homogenously typed. Whitespace is allowed to make compounds more readable, however one should refer to the section on strings to avoid unexpected elisions.

Structs

• SnbtError
  An error that occurs during the parsing process. This error contains a copy of a segment of the input where the error occurred as well as metadata about the specific error. See ParserErrorType for the different error types.

Enums

• ParserErrorType
  A specific type of parser error. This enum includes metadata about each specific error.

Functions

• parse
  Parses the given string into an NBT tag compound.
• parse_and_size
  Parses the given string just like parse, but also returns the amount of parsed characters.