Documentation
¶
Overview ¶
The graphics.gd/classdb/JSON class enables all data types to be converted to and from a JSON string. This is useful for serializing data, e.g. to save to a file or send over the network.
Stringify is used to convert any data type into a JSON string.
Instance.Parse is used to convert any existing JSON data into a any that can be used within Godot. If successfully parsed, use Instance.Data to retrieve the any, and use [graphics.gd/classdb/@GlobalScope.Instance.Typeof] to check if the Variant's type is what you expect. JSON Objects are converted into a data structure, but JSON data can be used to store slices, numbers, strings and even just a boolean.
package main
import (
"graphics.gd/classdb/JSON"
)
func ExampleJSON() {
var data_to_send = []string{"a", "b", "c"}
var json_string = JSON.Stringify(data_to_send, "", false)
// Save data
// ...
// Retrieve data
var json = JSON.New()
var error = json.Parse(json_string)
if error == nil {
var data_received = json.Data()
if _, ok := data_received.([]any); ok {
print(data_received) // Prints the array.
} else {
print("Unexpected data")
}
} else {
print("JSON Parse Error: ", json.GetErrorMessage(), " in ", json_string, " at line ", json.GetErrorLine())
}
}
Alternatively, you can parse strings using the static ParseString method, but it doesn't handle errors.
package main
import "graphics.gd/classdb/JSON"
func ExampleParseString(json_string string) {
var data = JSON.ParseString(json_string) // Returns null if parsing failed.
_ = data
}
Note: Both parse methods do not fully comply with the JSON specification:
- Trailing commas in arrays or objects are ignored, instead of causing a parser error.
- New line and tab characters are accepted in string literals, and are treated like their corresponding escape sequences \n and \t.
- Numbers are parsed using graphics.gd/classdb/String.Instance.ToFloat which is generally more lax than the JSON specification.
- Certain errors, such as invalid Unicode sequences, do not cause a parser error. Instead, the string is cleaned up and an error is logged to the console.
Index ¶
- func FromNative(v any, full_objects bool) any
- func FromNativeOptions(v any, full_objects bool) any
- func ParseString(json_string string) any
- func Stringify(data any, indent string, full_precision bool) string
- func StringifyOptions(data any, indent string, sort_keys bool, full_precision bool) string
- func ToNative(json any, allow_objects bool) any
- func ToNativeOptions(json any, allow_objects bool) any
- type Advanced
- type Any
- type Expanded
- type Extension
- type ID
- type Instance
- func (self Instance) AsJSON() Instance
- func (self Instance) AsObject() [1]gd.Object
- func (self Instance) AsRefCounted() [1]gd.RefCounted
- func (self Instance) AsResource() Resource.Instance
- func (self Instance) Data() any
- func (self Instance) GetErrorLine() int
- func (self Instance) GetErrorMessage() string
- func (self Instance) GetParsedText() string
- func (self Instance) ID() ID
- func (self Instance) Parse(json_text string) error
- func (self Instance) SetData(value any)
- func (self *Instance) SetObject(obj [1]gd.Object) bool
- func (self Instance) Virtual(name string) reflect.Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromNative ¶
Converts a native engine type to a JSON-compliant value.
By default, objects are ignored for security reasons, unless 'full_objects' is true.
You can convert a native value to a JSON string like this:
func FromNativeOptions ¶
Converts a native engine type to a JSON-compliant value.
By default, objects are ignored for security reasons, unless 'full_objects' is true.
You can convert a native value to a JSON string like this:
func ParseString ¶
Attempts to parse the 'json_string' provided and returns the parsed data. Returns null if parse failed.
func Stringify ¶
Converts a any var to JSON text and returns the result. Useful for serializing data to store or send over the network.
Note: The JSON specification does not define integer or float types, but only a number type. Therefore, converting a Variant to JSON text will convert all numerical values to [Float.X] types.
Note: If 'full_precision' is true, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding.
The 'indent' parameter controls if and how something is indented; its contents will be used where there should be an indent in the output. Even spaces like " " will work. \t and \n can also be used for a tab indent, or to make a newline for each indent respectively.
Example output:
func StringifyOptions ¶
Converts a any var to JSON text and returns the result. Useful for serializing data to store or send over the network.
Note: The JSON specification does not define integer or float types, but only a number type. Therefore, converting a Variant to JSON text will convert all numerical values to [Float.X] types.
Note: If 'full_precision' is true, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding.
The 'indent' parameter controls if and how something is indented; its contents will be used where there should be an indent in the output. Even spaces like " " will work. \t and \n can also be used for a tab indent, or to make a newline for each indent respectively.
Example output:
func ToNative ¶
Converts a JSON-compliant value that was created with FromNative back to native engine types.
By default, objects are ignored for security reasons, unless 'allow_objects' is true.
You can convert a JSON string back to a native value like this:
func ToNativeOptions ¶
Converts a JSON-compliant value that was created with FromNative back to native engine types.
By default, objects are ignored for security reasons, unless 'allow_objects' is true.
You can convert a JSON string back to a native value like this:
Types ¶
type Advanced ¶
type Advanced = class
Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.
type Expanded ¶
func (Expanded) Parse ¶
Attempts to parse the 'json_text' provided.
Returns an [Error]. If the parse was successful, it returns [Ok] and the result can be retrieved using Instance.Data. If unsuccessful, use Instance.GetErrorLine and Instance.GetErrorMessage to identify the source of the failure.
Non-static variant of ParseString, if you want custom error handling.
The optional 'keep_text' argument instructs the parser to keep a copy of the original text. This text can be obtained later by using the Instance.GetParsedText function and is used when saving the resource (instead of generating new text from Instance.Data).
type Extension ¶
Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension
func (*Extension[T]) AsRefCounted ¶
func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted
func (*Extension[T]) AsResource ¶
type ID ¶
ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.
type Instance ¶
Instance of the class with convieniently typed arguments and results.
var Nil Instance
Nil is a nil/null instance of the class. Equivalent to the zero value.
func (Instance) AsRefCounted ¶
func (self Instance) AsRefCounted() [1]gd.RefCounted
func (Instance) AsResource ¶
func (Instance) GetErrorLine ¶
Returns 0 if the last call to Instance.Parse was successful, or the line number where the parse failed.
func (Instance) GetErrorMessage ¶
Returns an empty string if the last call to Instance.Parse was successful, or the error message if it failed.
func (Instance) GetParsedText ¶
Return the text parsed by Instance.Parse (requires passing keep_text to Instance.Parse).
func (Instance) Parse ¶
Attempts to parse the 'json_text' provided.
Returns an [Error]. If the parse was successful, it returns [Ok] and the result can be retrieved using Instance.Data. If unsuccessful, use Instance.GetErrorLine and Instance.GetErrorMessage to identify the source of the failure.
Non-static variant of ParseString, if you want custom error handling.
The optional 'keep_text' argument instructs the parser to keep a copy of the original text. This text can be obtained later by using the Instance.GetParsedText function and is used when saving the resource (instead of generating new text from Instance.Data).
Source Files