FromJSON: Difference between revisions

Latest revision as of 02:12, 9 June 2026

This function parses a JSON formatted string and unpacks the values into Lua variables. You can use toJSON to encode variables into a JSON string that can be read by this function.

Important Note: When parsing a JSON array, fromJSON unpacks the elements as multiple separate values. To mimic standard JSON parsing behavior and store these elements together in a single Lua table, you must wrap the function call in a table constructor {}.

If your JSON string was generated directly by toJSON, you do not need to wrap it.

local jsonString = '["Apple", "Orange"]'
local fruitsTable = { fromJSON(jsonString) }

Syntax

var... fromJSON ( string json )

Required Arguments

json: A JSON formatted string.

Returns

Returns the parse JSON data as multiple values or a single table depending on the input JSON structure:

Returns multiple separate values (unpacked) if the root element of the JSON is an array
Returns a single table if the root element of the JSON is an object
Returns nil if the JSON string is invalid or malformed.

Examples

Example 1: Assigning to multiple variables

This example shows how fromJSON extracts values from a JSON array directly into separate Lua variables.

local jsonArray = '["Desert Eagle", 24]'

local name, ammo = fromJSON(jsonArray)

print(name, ammo) --> Output: Desert Eagle  24

Example 2: Wrapping the call inside a table

This example shows how to capture all values of a JSON array in a single Lua table.

local jsonArray = '["Apple", "Orange"]'

-- Put the fromJSON call inside of a table directly to capture all the values of the JSON array
local fruits = {fromJSON(jsonArray)}

print(fruits[1], fruits[2]) --> Output: Apple  Orange

Example 3: Parsing a JSON object

local jsonObject = '{"playerName": "Alex", "score": 2500}'

local playerStats = fromJSON(jsonObject)

if playerStats then
    print(playerStats.playerName) --> Output: Alex
    print(playerStats.score)      --> Output: 2500
end

Example 4: Parsing a nested JSON object

local jsonString = '{"vehicle": "Infernus", "upgrades": {"nos": true, "paintjob": 2}}'

local vehicleInfo = fromJSON(jsonString)

if vehicleInfo then
    print(vehicleInfo.vehicle)           --> Output: Infernus
    print(vehicleInfo.upgrades.nos)      --> Output: true
    print(vehicleInfo.upgrades.paintjob) --> Output: 2
end

@@ Line 1: / Line 1: @@
 __NOTOC__
-{{Server client function}}<!-- Change this to "Client function" or "Server function" appropriately-->
+{{Server client function}}
-<!-- Describe in plain english what this function does. Don't go into details, just give an overview -->
+This function parses a [[JSON]] formatted string and unpacks the values into Lua variables. You can use [[toJSON]] to encode variables into a JSON string that can be read by this function.
-This fake function is for use with blah & blah and does blahblahblabhalbhl
+{{Important Note|1=When parsing a JSON array, [[fromJSON]] unpacks the elements as multiple separate values. To mimic standard JSON parsing behavior and store these elements together in a single Lua table, you must wrap the function call in a table constructor {}.
+If your JSON string was generated directly by [[toJSON]], you do not need to wrap it.
+<syntaxhighlight lang="lua">
+local jsonString = '["Apple", "Orange"]'
+local fruitsTable = { fromJSON(jsonString) }
+</syntaxhighlight>
+}}
 ==Syntax==
-<!-- NOTE: don't use 'special' names for variable names, e.g. you shouldn't be writing things like 'player player, vehicle vehicle', instead write something like 'player thePlayer, vehicle vehicleToGetInto'. This is less confusing and prevents the syntax highlighting being odd -->
 <syntaxhighlight lang="lua">
-returnType functionName ( arguments )
+var... fromJSON ( string json )
 </syntaxhighlight>
 ===Required Arguments===
-<!-- List each argument one per line. This should be the argument's name as in the argument list above, NOT the argument's data type -->
+*'''json:''' A JSON formatted string.
-*'''argumentName:''' description
+===Returns===
+Returns the parse JSON data as multiple values or a single table depending on the input JSON structure:
+* Returns '''multiple separate values''' (unpacked) if the root element of the JSON is an array
+* Returns a single table if the root element of the JSON is an object
+* Returns [[nil]] if the JSON string is invalid or malformed.
+==Examples==
+===Example 1: Assigning to multiple variables===
+This example shows how fromJSON extracts values from a JSON array directly into separate Lua variables.
+<syntaxhighlight lang="lua">
+local jsonArray = '["Desert Eagle", 24]'
+local name, ammo = fromJSON(jsonArray)
-<!-- Only include this section below if there are optional arguments -->
+print(name, ammo) --> Output: Desert Eagle  24
-===Optional Arguments===
+</syntaxhighlight>
-{{OptionalArg}}
-*'''argumentName2:''' description
-*'''argumentName3:''' description
-===Returns===
+===Example 2: Wrapping the call inside a table===
-<!-- Make this descriptive. Explain what cases will return false. If you're unsure, add a tag to it so we can check -->
+This example shows how to capture all values of a JSON array in a single Lua table.
-Returns ''true'' if blah, ''false'' otherwise.
+<syntaxhighlight lang="lua">
+local jsonArray = '["Apple", "Orange"]'
+-- Put the fromJSON call inside of a table directly to capture all the values of the JSON array
+local fruits = {fromJSON(jsonArray)}
+print(fruits[1], fruits[2]) --> Output: Apple  Orange
+</syntaxhighlight>
+===Example 3: Parsing a JSON object===
+<syntaxhighlight lang="lua">
+local jsonObject = '{"playerName": "Alex", "score": 2500}'
+local playerStats = fromJSON(jsonObject)
+if playerStats then
+    print(playerStats.playerName) --> Output: Alex
+    print(playerStats.score)      --> Output: 2500
+end
+</syntaxhighlight>
-==Example==
+===Example 4: Parsing a nested JSON object===
-<!-- Explain what the example is in a single sentance -->
-This example does...
-<!-- Add the code below, an emphasis should be on making it clear, not optimized. You could provide two versions if you wish, one clear and well commented, the other optimized -->
 <syntaxhighlight lang="lua">
---This line does...
+local jsonString = '{"vehicle": "Infernus", "upgrades": {"nos": true, "paintjob": 2}}'
-blabhalbalhb --abababa
---This line does this...
+local vehicleInfo = fromJSON(jsonString)
-mooo
+if vehicleInfo then
+    print(vehicleInfo.vehicle)           --> Output: Infernus
+    print(vehicleInfo.upgrades.nos)      --> Output: true
+    print(vehicleInfo.upgrades.paintjob) --> Output: 2
+end
 </syntaxhighlight>
 ==See Also==
-<!-- Change FunctionArea to the area that this function is in on the main function list page, e.g. Server, Player, Vehicle etc -->
 {{Server_functions}}
-[[Category:Needs_Example]] <!-- leave this until the example is completed. -->
-[[Category:Need_Syntax]] <!-- leave this until syntax is available. Cannot document the function or event without syntax. -->
-[[Category:Incomplete]] <!-- leave this unless you complete the function -->