Format Specification

This page describes the NiceDump version 1.0 format.

Format

A parsable NiceDump is created in the following way:

Create a JSON representation of the object.
Base64-encode the JSON data.
Prepend the line =====BEGIN NICE-DUMP===== to the result.
Append the line =====END NICE-DUMP===== to the result.

Content not enclosed by =====BEGIN NICE-DUMP===== and =====END NICE-DUMP===== lines MAY be arbitrary and MUST NOT be considered a part of the NiceDump.

HTML: The NiceDump block SHOULD be enclosed by HTML comments

Example

This example will create a NiceDump for the string variable "Foo Bar".

Create the JSON representation:

{
    "name": "My String",
    "value": "Foo Bar",
    "type": "string",
    "size": 7
}

Base64-encode:

ewogICAgIm5hbWUiOiAiTXkgU3RyaW5nIiwKICAgICJ2YWx1ZSI6ICJGb28gQmFyIiwKICAgICJ0
eXBlIjogInN0cmluZyIsCiAgICAic2l6ZSI6IDcKfQ==

Prepend and append the NiceDump header and footer:

=====BEGIN NICE-DUMP=====
ewogICAgIm5hbWUiOiAiTXkgU3RyaW5nIiwKICAgICJ2YWx1ZSI6ICJGb28gQmFyIiwKICAgICJ0
eXBlIjogInN0cmluZyIsCiAgICAic2l6ZSI6IDcKfQ==
=====END NICE-DUMP=====

Done! A NiceDump reader can now parse this and might display something like this:

My String: "Foo Bar" string[7]

Item

An item corresponds to a basic entry in the NiceDump.

The item MUST have at least one of the parameters described below.
A parser MAY choose to ignore or display unrecognized parameters for forward compatibility.

Comment

A comment for the item.

Name	`comment`
Type	`string`
Example	`{"comment": "Internal class"}`

Is static

Tells whether the item is static or not. Default value is false.

Name	`isStatic`
Type	`bool`
Example	`{"isStatic": true}`

Items

A list of items.

Items is an array of objects where each contains an optional key and a mandatory value. The key and value contains each another item.

Name	`items`
Type	`array`
Example	`{"items": [ {"key": {…}, "value": {…}}, {"value": {…}} ]}`

key MAY be present in the array object, and if so MUST contain an item.
value MUST be present in the array object, and MUST contain an item.
Items SHOULD NOT be an empty array.

Name

The name of the item.

Name	`name`
Type	`string`
Example	`{"name": "Foo Bar"}`

Relation

The relation between the item and a parent item.

Name	`rel`
Type	`string`
Example	`{"rel": "parent"}`

PHP: Relation MAY be parent (for a parent class item).

Size

The size of the item, e.g. the size of an array or a string.

Name	`size`
Type	`number`
Example	`{"size": 4}`

Size MUST be a non-negative integer.

Type

The native type name for the item or any of _group_, _text_.

Name	`type`
Type	`string`
Example	`{"type": "string"}`

Type MUST be a native type name for the corresponding language or any of _group_, _text_.
If no type is given, a parser SHOULD fall back to _text_.
If type is _group_, items SHOULD also be present.
If type is _group_, a parser MAY choose to un-group the underlying items to the same level as the item.

PHP: Type MUST be any of null, bool, int, float, string, array, object, resource, _group_, _text_.

Type name

The specific name for the type, e.g. the class name for an object.

Name	`typeName`
Type	`string`
Example	`{"typeName": "FooClass"}`

Type name SHOULD only be present if type is present in the same item.
Type name SHOULD be a fully qualified class name if the type is object.

Value

The value to display for the item.

Name	`Value`
Type	`string`
Example	`{"value": "42"}`

Value SHOULD be representable for the corresponding type.

Visibility

The visibility for the item.

Name	`visibility`
Type	`string`
Example	`{"visibility": "public"}`

Visibility MUST be a native visibility option for the corresponding language.

PHP: Visibility MUST be any of public, protected, private.