JSON_PARSE
The JSON_PARSE function takes a JSON (JavaScript Object Notation) string or file and converts it into an IDL variable.
This routine is written in the IDL language. Its source code can be found in the file json_parse.pro in the lib subdirectory of the IDL distribution.
Tip: The default result of JSON_PARSE is either a LIST or an ORDEREDHASH. If you print out the result using Implied Print, then the output will automatically be printed in JSON format.
Examples
Convert JSON array into a LIST
json = '[true,null,42,3.14,"Hello"]'
result = JSON_PARSE(json)
HELP, result
result
IDL prints:
RESULT LIST <ID=3 NELEMENTS=5>
[
true,
null,
42,
3.1400000000000001,
"Hello"
]
Convert JSON object into an ORDEREDHASH
json = '{"Jupiter":{"Europa":4.8e22, "Ganymede":1.48e23}}'
result = JSON_PARSE(json)
HELP, result
result
PRINT, result['Jupiter'].Keys()
PRINT, result['Jupiter', 'Europa']
IDL prints:
RESULT HASH <ID=3 NELEMENTS=1>
{
"Jupiter":
{
"Ganymede": 1.4800000e+023,
"Europa": 4.8000000e+022
}
}
Ganymede
Europa
4.8000000e+022
Convert JSON array into an IDL array
json = '["Mercury", "Venus", "Earth"]'
result = JSON_PARSE(json, /TOARRAY)
PRINT, result
IDL prints:
Mercury
Venus
Earth
Convert an IDL structure into a JSON string and back into an IDL structure
mystruct = {TRUE: !TRUE, FALSE: !FALSE, INT: 5, FLOAT: 3.14, $
STR: "Hello", INTARRAY: [1,2,3,4,5], FLOATARRAY: [1.0,2.0,3.0]}
json = JSON_SERIALIZE(mystruct)
output = JSON_PARSE(json, /TOARRAY, /TOSTRUCT)
HELP, output
IDL prints:
** Structure <1d8ea18>, 7 tags, length=104, data length=98, refs=1:
TRUE BOOLEAN true (1)
FALSE BOOLEAN false (0)
INT LONG64 5
FLOAT DOUBLE 3.1400001
STR STRING 'Hello'
INTARRAY LONG64 Array[5]
FLOATARRAY DOUBLE Array[3]
Syntax
Result = JSON_PARSE(String, /DICTIONARY, /FOLD_CASE, /TOARRAY, /TOSTRUCT )
Return Value
If String begins with a curly brace "{", then the result is an ORDEREDHASH (or a structure if TOSTRUCT is set), containing the ordered key-value pairs from the JSON string. If String begins with a square bracket "[", then the result is a LIST (or an array if TOARRAY is set), containing the ordered collection of values.
If String is a scalar string that does not begin with "{" or "[", then it is assumed to be a file name. If the file exists, then the contents of the file are read and parsed.
When converting JSON values into IDL variables, the following rules are used:
- "null" becomes !NULL, unless the TOSTRUCT keyword is set, in which case the string "!NULL" is used.
- "false" and "true" become IDL booleans.
- An integer value in the range -263 to 263–1 becomes an IDL variable of type LONG64.
- An integer value in the range 263 to 264–1 becomes an IDL variable of type ULONG64.
- An integer value greater than or equal to 264 becomes an IDL variable of type DOUBLE (in this case some precision will be lost as doubles can only represent an exact integer up to about 253).
- A floating-point number becomes an IDL variable of type DOUBLE.
- A string will be converted to an IDL string. Any escaped characters (preceded by a "\") will be converted back to normal characters.
- A JSON array becomes an IDL LIST variable, unless the TOARRAY keyword is set, in which case an IDL array is returned.
- A JSON object becomes an IDL ORDEREDHASH variable, unless either the DICTIONARY or TOSTRUCT keyword is set.
Arguments
String
String must be a valid JSON string containing either a JSON object of name-value pairs, or a JSON array of values. If String is not valid JSON, JSON_PARSE will parse String until the first instance of invalid JSON.
String can also be a file name. In this case the entire file is read into memory and parsed as a single JSON string.
Keywords
DICTIONARY
If this keyword is set, then any JSON objects within the result (including the result itself) will be returned as DICTIONARY variables, instead of ORDEREDHASH variables. For IDL dictionaries, the keys are case insensitive and can be accessed using IDL's "dot" notation, similar to IDL structures. For example:
json = '{"Jupiter":{"Europa":4.8e22, "Ganymede":1.48e23}}'
result = JSON_PARSE(json, /DICTIONARY)
HELP, result
HELP, result.jupiter ; case insensitive
PRINT, result.jupiter.Keys()
PRINT, result.jupiter.europa
IDL prints:
RESULT DICTIONARY <ID=3 NELEMENTS=1>
<Expression> DICTIONARY <ID=10 NELEMENTS=2>
Ganymede Europa
4.8000000e+022
Note: The JSON format specifies that key names are case sensitive. If you have a JSON object with two keys that are identical except for their case, then using the DICTIONARY keyword will only return the second key/value pair.
Note: To use the DICTIONARY keyword successfully, all of the JSON keys must be valid IDL variable names (no special characters or spaces). If any keys are not valid then an error is thrown.
FOLD_CASE
By default, the keys returned in the ORDEREDHASH are case sensitive. If the FOLD_CASE keyword is set, then the ORDEREDHASH variable will be case insensitive. For example:
json = '{"My Key":1.23}'
result = JSON_PARSE(json, /FOLD_CASE)
PRINT, result.Keys()
PRINT, result['MY KEY'] ; ignore case
IDL prints:
My Key
1.2300000
This keyword is ignored when either the DICTIONARY or TOSTRUCT keyword is set.
Note: When using FOLD_CASE, the original case is preserved within the OrderedHash key list. You could therefore pass this OrderedHash back into JSON_SERIALIZE to reproduce the original JSON.
TOARRAY
If this keyword is set, then any JSON arrays within the result (including the result itself) will be returned as IDL arrays, instead of LIST variables.
Note: For this keyword to work correctly, each JSON array within the result must contain values that can all be converted to the same data type. The data type of each array will be determined by using the "highest" type within that array. For example, if your JSON array has two integer values and one decimal value, the resulting array will have type DOUBLE. For details on the rules used for type promotion, see List::ToArray under the PROMOTE_TYPE keyword.
TOSTRUCT
If this keyword is set, then any JSON objects within the result (including the result itself) will be returned as IDL structures, instead of ORDEREDHASH variables.
Note: Since IDL structure tags must be valid IDL identifiers, any spaces or special characters within the JSON keys will be converted to underscore characters. In addition, all keys will be converted to uppercase. Finally, any "null" values will be converted to the string "!NULL" since you cannot have a null field in a structure. If you need to convert the result back into an equivalent JSON string, do not use this keyword and return the result as an ORDEREDHASH instead.
Version History
|
8.2 |
Introduced |
| 8.3 |
Added DICTIONARY keyword Updated references from HASH to ORDEREDHASH |
| 8.4 |
The TOARRAY keyword now uses all of the array elements to determine the type, not just the first element. Values for "false" and "true" now use BOOLEAN variables. Added FOLD_CASE keyword. |
Resources and References
JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write, and for machines to parse and generate. JSON was designed as an alternative to XML, and is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. Further details can be found at https://www.json.org/json-en.html.