====== JSON ======

JSON (JavaScript Object Notation) is a lightweight data interchange format widely used for exchanging data between a server and a client, or between different components of an application. While AutoHotkey is primarily known for its automation capabilities, third-party libraries offer powerful options for working with JSON data.

===== What is JSON? =====

As described at [[https://www.json.org/json-en.html|json.org]], JSON is a format for exchanging data as language-independent text that follows a subset of the JavaScript standard for defining objects. The format is very similar to the one used in AutoHotkey for defining objects, using square brackets to define arrays of values, and curly braces to define a key/value store.

Where they differ is that in JSON, the keys of a curly brace object //must// be quoted. In AHKv1, they //may// be quoted. In AHKv2, they //must not// be quoted. In thqby's AHK_H v2, they once again //may// be quoted.

Although normally in AutoHotkey objects must be defined within a script, by using JSON you can define objects in an external file to be loaded later or retrieve objects from third-party sources like web APIs.

<code AutoHotkey>
#Requires AutoHotkey v1.1
#Include <JSON>

; Without JSON, objects must be defined inside the script
myObject := { "a": 1, "b": 2, "c": [3, 4, 5] } ; v1
; myObject := Map("a", 1, "b", 2, "c", [3, 4, 5]) ; v2

; With JSON, objects can be loaded from an external source,
; such as a file that contains this text:
; { "a": 1, "b": 2, "c": [3, 4, 5] }
FileRead someVar, someFile.json
myObject := JSON.Parse(someVar)
</code>

===== Parsing JSON =====

AutoHotkey does not have any built in libraries for parsing JSON, but there are many third-party options available listed on the [[libraries:json|JSON Libraries]] page. Due to AutoHotkey's limitations each library has its own advantages and disadvantages.

The primary limitation is that AutoHotkey does not natively support all the same types as JSON. AutoHotkey supports objects, arrays, strings, and numbers. It does not support Booleans or Null values so to use those kinds of values you will have to look at implementation specific behavior. Typically libraries will parse these as ''1'' for ''True'', ''0'' for ''False'', and empty string for ''null''.

AutoHotkey v2 introduced the new Map type, which many v2 JSON libraries prefer when loading JSON objects due to the separation of the item store and property store. In v1, loading JSON data containing keys that conflicted with built-in method names could cause those methods to be overridden by whatever data was loaded. Although this tended not to cause security issues, it did open a lot of opportunities for breakage. For example, loading JSON with a key named ''_NewEnum'' would cause the object to no longer work in for-loops.

<tabbox AutoHotkey v1>
<runner ahk>
#Include <JSON> ; Including geek's cJson library
myObject := JSON.Load("{""a"": 1, ""b"": 2, ""c"": [3, 4, 5]}")
MsgBox % "a: " myObject["a"]
MsgBox % "b: " myObject["b"]
MsgBox % "c: " myObject["c"].Length() " items"
</runner>
<tabbox AutoHotkey v2>
<runner ahk2>
#Include <cJSON> ; Including geek's cJson library
myObject := JSON.Load('{"a": 1, "b": 2, "c": [3, 4, 5]}')
MsgBox "a: " myObject["a"]
MsgBox "b: " myObject["b"]
MsgBox "c: " myObject["c"].Length " items"
</runner>
</tabbox>

===== Exporting JSON =====

AutoHotkey does not have any built in libraries for exporting to JSON, but there are many third-party options available listed on the [[libraries:json|JSON Libraries]] page.

<tabbox AutoHotkey v1>
<runner ahk>
#Include <JSON> ; Including geek's cJson library
myJson := JSON.Dump({a: 1, b: 2, c: [1, 2, 3]})
MsgBox % myJson
</runner>
<tabbox AutoHotkey v2>
<runner ahk2>
#Include <cJSON> ; Including geek's cJson library
myJson := JSON.Dump({a: 1, b: 2, c: [1, 2, 3]})
MsgBox myJson
</runner>
</tabbox>