summaryrefslogtreecommitdiff
path: root/doc/classes/JSON.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/classes/JSON.xml')
-rw-r--r--doc/classes/JSON.xml46
1 files changed, 30 insertions, 16 deletions
diff --git a/doc/classes/JSON.xml b/doc/classes/JSON.xml
index 5d83c75417..93731cf553 100644
--- a/doc/classes/JSON.xml
+++ b/doc/classes/JSON.xml
@@ -6,18 +6,17 @@
<description>
The [JSON] enables all data types to be converted to and from a JSON string. This useful for serializing data to save to a file or send over the network.
[method stringify] is used to convert any data type into a JSON string.
- [method parse] is used to convert any existing JSON data into a [Variant] that can be used within Godot. If successfully parsed, use [method get_data] to retrieve the [Variant], and use [code]typeof[/code] to check if the Variant's type is what you expect. JSON Objects are converted into a [Dictionary], but JSON data can be used to store [Array]s, numbers, [String]s and even just a boolean.
+ [method parse] is used to convert any existing JSON data into a [Variant] that can be used within Godot. If successfully parsed, use [member data] to retrieve the [Variant], and use [code]typeof[/code] to check if the Variant's type is what you expect. JSON Objects are converted into a [Dictionary], but JSON data can be used to store [Array]s, numbers, [String]s and even just a boolean.
[b]Example[/b]
[codeblock]
var data_to_send = ["a", "b", "c"]
- var json = JSON.new()
- var json_string = json.stringify(data_to_send)
+ var json_string = JSON.stringify(data_to_send)
# Save data
# ...
# Retrieve data
var error = json.parse(json_string)
if error == OK:
- var data_received = json.get_data()
+ var data_received = json.data
if typeof(data_received) == TYPE_ARRAY:
print(data_received) # Prints array
else:
@@ -25,17 +24,19 @@
else:
print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", json.get_error_line())
[/codeblock]
+ Alternatively, you can parse string using the static [method parse_string] method, but it doesn't allow to handle errors.
+ [codeblock]
+ var data = JSON.parse_string(json_string) # Returns null if parsing failed.
+ [/codeblock]
+ [b]Note:[/b] 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 [code]\n[/code] and [code]\t[/code].
+ - Numbers are parsed using [method String.to_float] 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 cleansed and an error is logged to the console.
</description>
<tutorials>
</tutorials>
<methods>
- <method name="get_data" qualifiers="const">
- <return type="Variant" />
- <description>
- Returns the [Variant] containing the data of a successful [method parse].
- [b]Note:[/b] It will return [code]Null[/code] if the last call to parse was unsuccessful or [method parse] has not yet been called.
- </description>
- </method>
<method name="get_error_line" qualifiers="const">
<return type="int" />
<description>
@@ -52,11 +53,19 @@
<return type="int" enum="Error" />
<param index="0" name="json_string" type="String" />
<description>
- Attempts to parse the [code]json_string[/code] provided.
- Returns an [enum Error]. If the parse was successful, it returns [code]OK[/code] and the result can be retrieved using [method get_data]. If unsuccessful, use [method get_error_line] and [method get_error_message] for identifying the source of the failure.
+ Attempts to parse the [param json_string] provided.
+ Returns an [enum Error]. If the parse was successful, it returns [constant OK] and the result can be retrieved using [member data]. If unsuccessful, use [method get_error_line] and [method get_error_message] for identifying the source of the failure.
+ Non-static variant of [method parse_string], if you want custom error handling.
+ </description>
+ </method>
+ <method name="parse_string" qualifiers="static">
+ <return type="Variant" />
+ <param index="0" name="json_string" type="String" />
+ <description>
+ Attempts to parse the [param json_string] provided and returns the parsed data. Returns [code]null[/code] if parse failed.
</description>
</method>
- <method name="stringify">
+ <method name="stringify" qualifiers="static">
<return type="String" />
<param index="0" name="data" type="Variant" />
<param index="1" name="indent" type="String" default="&quot;&quot;" />
@@ -65,8 +74,8 @@
<description>
Converts a [Variant] var to JSON text and returns the result. Useful for serializing data to store or send over the network.
[b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a Variant to JSON text will convert all numerical values to [float] types.
- [b]Note:[/b] If [code]full_precision[/code] is true, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding.
- The [code]indent[/code] parameter controls if and how something is indented, the string used for this parameter will be used where there should be an indent in the output, even spaces like [code]" "[/code] will work. [code]\t[/code] and [code]\n[/code] can also be used for a tab indent, or to make a newline for each indent respectively.
+ [b]Note:[/b] If [param full_precision] is [code]true[/code], when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding.
+ The [param indent] parameter controls if and how something is indented, the string used for this parameter will be used where there should be an indent in the output, even spaces like [code]" "[/code] will work. [code]\t[/code] and [code]\n[/code] can also be used for a tab indent, or to make a newline for each indent respectively.
[b]Example output:[/b]
[codeblock]
## JSON.stringify(my_dictionary)
@@ -107,4 +116,9 @@
</description>
</method>
</methods>
+ <members>
+ <member name="data" type="Variant" setter="set_data" getter="get_data" default="null">
+ Contains the parsed JSON data in [Variant] form.
+ </member>
+ </members>
</class>