Class InputJSONNode

A JSON value in a mutable tree that preserves everything needed to write the document back out exactly as it was read.

Inheritance
object
InputJSONNode
Inherited Members
Namespace: Scylla.Input
Assembly: ScyllaInput.dll
Syntax
public sealed class InputJSONNode
Remarks

Two properties make this different from a general-purpose JSON model, and both exist to serve byte-exact round-tripping of files owned by another tool:

  1. Object members keep their original order. A document is re-emitted with its keys in the sequence they were parsed, so a file that was already canonical stays byte-identical, and one that was not keeps its own shape rather than being silently reordered.
  2. Numbers keep their original source text rather than a parsed value. Parsing and re-rendering is not identity: 1.0 read as a double and written back with a round-trip format specifier becomes 1. Storing the lexeme also sidesteps the culture sensitivity of the integer write overloads.

Unknown members need no special handling. Because the tree models every value it encounters rather than mapping onto a fixed schema, a member nobody understands is preserved by the same code path as one that is fully understood.

Values are never null. A JSON null is a node of type Null, so callers can walk the tree without null checks at every step.

Properties

Count

Gets the number of members when this is an object, or the number of elements when this is an array. Zero for every other node type.

Declaration
public int Count { get; }
Property Value
Type Description
int

Type

Gets the kind of value this node holds.

Declaration
public InputJSONNodeType Type { get; }
Property Value
Type Description
InputJSONNodeType

Methods

AddElement(InputJSONNode)

Appends an element.

Declaration
public void AddElement(InputJSONNode value)
Parameters
Type Name Description
InputJSONNode value

The element. null is stored as a Null node.
Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an array.

AddMember(string, InputJSONNode)

Appends a member unconditionally, without checking whether the key is already present.

Declaration
public void AddMember(string key, InputJSONNode value)
Parameters
Type Name Description
string key

The member name.
InputJSONNode value

The value. null is stored as a Null node.
Remarks

This is the parse-time entry point. JSON permits repeated keys, and although no Unity-authored file contains them, a hand-edited or merge-mangled one might; appending rather than replacing means such a document still round-trips exactly instead of quietly losing a member. Editing code should call SetMember(string, InputJSONNode) instead.

Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an object.
ArgumentNullException

Thrown when the key is null.

AsBool(bool)

Gets the value of a boolean node.

Declaration
public bool AsBool(bool fallback = false)
Parameters
Type Name Description
bool fallback

Returned when this node is not a boolean.
Returns
Type Description
bool

The value, or fallback.

AsLong(long)

Parses a number node as a 64-bit integer.

Declaration
public long AsLong(long fallback = 0)
Parameters
Type Name Description
long fallback

Returned when this node is not a number or does not parse.
Returns
Type Description
long

The parsed value, or fallback.

AsNumberLexeme()

Gets the exact source text of a number node.

Declaration
public string AsNumberLexeme()
Returns
Type Description
string

The lexeme, or null when this node is not a number.

AsString(string)

Gets the text of a string node.

Declaration
public string AsString(string fallback = null)
Parameters
Type Name Description
string fallback

Returned when this node is not a string.
Returns
Type Description
string

The text, or fallback.

Clone()

Produces a deep copy. Useful for duplicating a subtree without the copy sharing mutable state with the original.

Declaration
public InputJSONNode Clone()
Returns
Type Description
InputJSONNode

An independent copy of this node and everything below it.

GetBool(string, bool)

Gets a boolean member.

Declaration
public bool GetBool(string key, bool fallback = false)
Parameters
Type Name Description
string key

The member name.
bool fallback

Returned when the member is absent or is not a boolean.
Returns
Type Description
bool

The value, or fallback.

GetElementAt(int)

Gets an element by position.

Declaration
public InputJSONNode GetElementAt(int index)
Parameters
Type Name Description
int index

Zero-based position.
Returns
Type Description
InputJSONNode

The element.
Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an array.
ArgumentOutOfRangeException

Thrown when the index is out of range.

GetLong(string, long)

Gets a numeric member parsed as a 64-bit integer.

Declaration
public long GetLong(string key, long fallback = 0)
Parameters
Type Name Description
string key

The member name.
long fallback

Returned when the member is absent or does not parse.
Returns
Type Description
long

The value, or fallback.

GetMember(string)

Gets a member value by name.

Declaration
public InputJSONNode GetMember(string key)
Parameters
Type Name Description
string key

The member name, compared ordinally.
Returns
Type Description
InputJSONNode

The value, or null when the member is absent.

GetMemberAt(int)

Gets a member by position, in parse order.

Declaration
public InputJSONMember GetMemberAt(int index)
Parameters
Type Name Description
int index

Zero-based position.
Returns
Type Description
InputJSONMember

The member at that position.
Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an object.
ArgumentOutOfRangeException

Thrown when the index is out of range.

GetString(string, string)

Gets a string member.

Declaration
public string GetString(string key, string fallback = null)
Parameters
Type Name Description
string key

The member name.
string fallback

Returned when the member is absent or is not a string.
Returns
Type Description
string

The text, or fallback.

HasMember(string)

Reports whether a member is present.

Declaration
public bool HasMember(string key)
Parameters
Type Name Description
string key

The member name, compared ordinally.
Returns
Type Description
bool

true when the member exists.

IndexOfElement(InputJSONNode)

Finds an element's position by reference identity.

Declaration
public int IndexOfElement(InputJSONNode value)
Parameters
Type Name Description
InputJSONNode value

The element to locate.
Returns
Type Description
int

The zero-based position, or -1 when absent or this is not an array.
Remarks

Reference identity rather than value equality, matching RemoveElement(InputJSONNode) and for the same reason: nodes have no structural equality, and two bindings with identical content are still two different bindings.

The counterpart to IndexOfMember(string). Structural editing needs it because the removal methods report only whether they found something, not where it was, and putting an element back where it came from requires the index.

IndexOfMember(string)

Finds the position of a member.

Declaration
public int IndexOfMember(string key)
Parameters
Type Name Description
string key

The member name, compared ordinally.
Returns
Type Description
int

The zero-based position, or -1 when absent or this node is not an object.

InsertElement(int, InputJSONNode)

Inserts an element at a position.

Declaration
public void InsertElement(int index, InputJSONNode value)
Parameters
Type Name Description
int index

Zero-based position to insert before.
InputJSONNode value

The element. null is stored as a Null node.
Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an array.
ArgumentOutOfRangeException

Thrown when the index is out of range.

InsertMember(int, string, InputJSONNode)

Sets a member, placing it at a given position when it does not already exist.

Declaration
public void InsertMember(int index, string key, InputJSONNode value)
Parameters
Type Name Description
int index

Where to insert when the key is absent, clamped into range.
string key

The member name.
InputJSONNode value

The value. null is stored as a Null node.
Remarks

SetMember(string, InputJSONNode) appends when the key is absent, which is right for a value the schema does not order but wrong for one it does. Writing expectedControlType onto a hand-edited action that happens to lack it would land the member after initialStateCheck rather than in its documented slot: legal JSON that Unity reads back identically, but a diff that looks like the file was rearranged.

An existing member is replaced where it already sits and is never moved, because relocating a member the file already had is a worse diff than leaving it be.

Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an object.
ArgumentNullException

Thrown when the key is null.

NewArray()

Creates an empty array node.

Declaration
public static InputJSONNode NewArray()
Returns
Type Description
InputJSONNode

A node of type Array with no elements.

NewBool(bool)

Creates a boolean node.

Declaration
public static InputJSONNode NewBool(bool value)
Parameters
Type Name Description
bool value

The value.
Returns
Type Description
InputJSONNode

A node of type Bool.

NewNull()

Creates a null node.

Declaration
public static InputJSONNode NewNull()
Returns
Type Description
InputJSONNode

A node of type Null.

NewNumber(long)

Creates a number node from an integer, rendered with invariant culture.

Declaration
public static InputJSONNode NewNumber(long value)
Parameters
Type Name Description
long value

The value.
Returns
Type Description
InputJSONNode

A node of type Number.

NewNumber(string)

Creates a number node from its exact source text.

Declaration
public static InputJSONNode NewNumber(string lexeme)
Parameters
Type Name Description
string lexeme

The numeric literal as it should appear in the output. Written back verbatim.
Returns
Type Description
InputJSONNode

A node of type Number.
Exceptions
Type Condition
ArgumentException

Thrown when the lexeme is null or empty.

NewObject()

Creates an empty object node.

Declaration
public static InputJSONNode NewObject()
Returns
Type Description
InputJSONNode

A node of type Object with no members.

NewString(string)

Creates a string node.

Declaration
public static InputJSONNode NewString(string value)
Parameters
Type Name Description
string value

The unescaped text. null produces a Null node instead.
Returns
Type Description
InputJSONNode

A node of type String, or a Null node.

RemoveElement(InputJSONNode)

Removes an element by reference identity.

Declaration
public bool RemoveElement(InputJSONNode value)
Parameters
Type Name Description
InputJSONNode value

The element to remove.
Returns
Type Description
bool

true when the element was found and removed.

RemoveElementAt(int)

Removes an element by position.

Declaration
public void RemoveElementAt(int index)
Parameters
Type Name Description
int index

Zero-based position.
Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an array.
ArgumentOutOfRangeException

Thrown when the index is out of range.

RemoveMember(string)

Removes a member.

Declaration
public bool RemoveMember(string key)
Parameters
Type Name Description
string key

The member name.
Returns
Type Description
bool

true when a member was removed.

SetBool(string, bool)

Sets a boolean member, replacing it in place when present.

Declaration
public void SetBool(string key, bool value)
Parameters
Type Name Description
string key

The member name.
bool value

The value.

SetLong(string, long)

Sets a numeric member from an integer, replacing it in place when present.

Declaration
public void SetLong(string key, long value)
Parameters
Type Name Description
string key

The member name.
long value

The value.

SetMember(string, InputJSONNode)

Sets a member, replacing it in place when it already exists and appending it at the end otherwise.

Declaration
public void SetMember(string key, InputJSONNode value)
Parameters
Type Name Description
string key

The member name.
InputJSONNode value

The value. null is stored as a Null node.
Remarks

Replacing in place rather than removing and re-adding is what keeps an edited document's key order stable, so changing one value does not move it to the end and produce a misleading diff.

An object that carries the same key twice, which the reader preserves rather than rejects so a hand-edited file still round-trips byte for byte, has only its first occurrence replaced. That is deliberate and matches how every read here resolves a duplicate: IndexOfMember(string) returns the first match, so writing anywhere else would store a value no subsequent read would ever return.

Exceptions
Type Condition
InvalidOperationException

Thrown when this node is not an object.
ArgumentNullException

Thrown when the key is null.

SetString(string, string)

Sets a string member, replacing it in place when present.

Declaration
public void SetString(string key, string value)
Parameters
Type Name Description
string key

The member name.
string value

The text.

See Also