ReadFromJSON

A function added by the ShowOff NVSE Plugin version 1.45.

Description

Parses a JSON file at the given filepath and returns it converted as a script value. See Examples section to see how JSON value types are translated to a script variable type, as well as how to handle all possible return type if it can't be predicted.

jsonPointer determines the path in the JSON hierarchy to read from; pass "" (empty string) to get the root value (everything). It follows the standardized syntax for JSON Pointers.

filepath is relative to root folder (where FalloutNV.exe lies).

parserMode determines which JSON-like parser to use, which determines how the file's contents will be interpreted.

• Modes are listed in the Notes section.

If useCache is true, then the parsed JSON will be stored in session-persistent memory.

• This is useful to avoid the performance cost of re-parsing the file, but at the cost of memory.
• To clear the cache, use ClearFileCacheShowOff.
  
  This function can only be used in a script, not as a Condition.

Syntax

[help]

(parsedJson:anyType) ReadFromJSON filepath:string jsonPointer:string{""} parserMode:int{0} useCache:bool{false} 

Notes

• Valid parser modes:

Parse Mode	Value
Standard JSON	0
JAXN - Extended JSON	1
TaoConfig	2

Examples

1: Converting Basic JSON Values.

Assuming "myFile.txt" has the following contents:

"I am the only value in this JSON file"

Then

string_var sStr = ReadFromJSON "myFile.txt" "" 0

will set sStr to "I am the only value in this JSON file".

Converting Forms

Forms are read as JSON strings following a specific format.

They must be prefixed with '@', followed by the source file name, then ':', and finally the formID (without the mod index).

• Example (for Craig Boone): @FalloutNV.esm:096BCE
  • Leading zeros can be removed; this still works: @FalloutNV.esm:96BCE

Example: Assuming "myFile.txt" has the following contents:

"@LonesomeRoad.esm:003E43"

Then

ref rForm = ReadFromJSON "myFile.txt" "" 0

will set rForm to the NVDLC04Ulysses (Ulysses) form.

Other Conversions

JSON number/boolean -> float
JSON Null -> Ar_Null

2: Converting JSON Objects.

Assuming "myFile.txt" has the following contents:

{    
    "key1":1,
    "key2":2.4,
    "key3":"this file is a single Object"
}

Then

array_var aJson = ReadFromJSON "myFile.txt" "" 0

will set aJson to a StringMap array containing ["key1":1, "key2":2.4, "key3":"this file is a single Object"].

3: Converting JSON Arrays

Assuming "myFile.txt" has the following contents:

[1, 2, "this file is a single array"]

Then

array_var aJson = ReadFromJSON "myFile.txt" "" 0

will set aJson to a regular array containing [1, 2, "this file is a single array"].

4: Working with all these Return Types

If we don't know the JSON value type to expect from the file we'll parse, then we can box the return type of ReadFromJSON and use TypeOf to check the value type at runtime.

• To "box" refers here to store the value in a single-element array using the Box NVSE Operator, &.

Assuming "myFile.txt" has the following contents:

1000

Then

array_var aJson = &(ReadFromJSON "myFile.txt" "" 0)
string_var sType = TypeOf (*aJson)

will set aJson to a regular array containing [1000]. sType will be set to "Number".

5: Reading Nested JSON Values

Nested JSON values stored in Objects / Arrays will be converted to NVSE arrays/stringmaps.
There is no limit to how deeply nested a JSON structure can be, meaning there is also no limit for how deeply nested the converted value can be.

Example 1: JSON Object With Nested Arrays

Assuming "myFile.txt" has the following contents:

{
	"array1": [1, 2, "this file contains 2 arrays, housed in 1 object"],
	"array2": [1, 2, "I am the second inner array"]
}

Then

array_var aJson = &(ReadFromJSON "myFile.txt" "" 0)

will set aJson to an array containing a multidimensional StringMap array, since the root value of the JSON file is an Object, which converts to an NVSE StringMap.

This stringmap contains 2 regular arrays:

[ "array1": [1, 2, "this file contains 2 arrays, housed in 1 object"], 
"array2": [1, 2, "I am the second inner array"] ]

As such, aJson can be read in the following ways:

array_var aSubArray1 = (*aJson)["array1"]  
printvar aSubArray1 
;* Will print as [1, 2, "this file contains 2 arrays, housed in 1 object"].

string_var sString = aSubArray1["array2"][2]
printvar sString
;* Will print as "I am the second inner array".

Example 2: JSON Array With Nested Arrays

Assuming "myFile.txt" has the following contents:

[
	[1, 2, "this file contains 2 arrays, housed in 1 array"],
	[1, 2, "I am the second inner array"]
]

Then

array_var aJson = &(ReadFromJSON "myFile.txt" "" 0)

will set aJson to an array containing a multidimensional array, since the root value of the JSON file is an Array, which converts to a regular NVSE Array.

This multidimensional array contains 2 regular arrays:

[ [1, 2, "this file contains 2 arrays, housed in 1 array"], 
 [1, 2, "I am the second inner array"] ]

Example 3: JSON Object With Different Nested Values

Assuming "myFile.txt" has the following contents:

{
  "nestedArray": ["@LonesomeRoad.esm:003E43", "@FalloutNV.esm:E9C3B"],
  "nestedObject": {
                "nestedEntry1":"hello",
                "nestedEntry2": [1,2,3,4],
                "nestedEntry3": {
                                  "someKey":"Some string value"
                                }
              },
  "nestedString":"Magic"
}

Then

array_var aJson = &(ReadFromJSON "myFile.txt" "" 0)

will set aJson to an array containing a multidimensional StringMap, since the root value is an object, which converts to a StringMap.

As such, aJson can be read like so:

array_var aArrayOfForms = (*aJson)["nestedArray"]
printvar aArrayOfForms 
;* Will print as [[id: 4003E43, edid: "NVDLC04UlyssesREF", name: "Ulysses"], [id: E9C3B, edid: "WeapNVServiceRifle", name: "Service Rifle"]]

array_var aStringMap = aJson["nestedObject"]
string_var sString = aStringMap["nestedEntry1"]
printvar sString
;* Will print as "hello"

array_var aArray = aStringMap["nestedEntry2"]
printvar aArray 
;* Will print as [1, 2, 3, 4]

array_var aStringMap2 = aStringMap["nestedEntry3"]
printvar aStringMap2 
;* Will print as [ "someKey":"Some string value" ]

sString = aJson["nestedString"]
printvar sString
;* Will print as "Magic"

Notes

• To suppress error messages and test if a file is valid JSON or not, use TestExpr.

See Also

• WriteToJSON
• ClearFileCacheShowOff