libraries:json:cjson

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
libraries:json:cjson [2023-01-25 19:00] – Fix code runner boxes geeklibraries:json:cjson [2023-12-11 18:06] (current) – geek
Line 1: Line 1:
 <markdown> <markdown>
  
-# cJson.ahk+# cJson.ahk \[v1]\[v2]
  
 The first and only AutoHotkey JSON library to use embedded compiled C for high The first and only AutoHotkey JSON library to use embedded compiled C for high
Line 8: Line 8:
 ## Compatibility ## Compatibility
  
-This library is compatible with AutoHotkey v1.1 U64 and U32. +This library is compatible with AutoHotkey v2.0, and older versions are available for v1.1 U64 and U32.
- +
-Now that AHKv2 is out of Alpha, it's likely that its object structures will not +
-change significantly again in the future. Compatibility with AHKv2 will require +
-modification to both the AHK wrapper and the C implementation. Support is +
-planned, but may not be implemented any time soon.+
  
 ## Using cJson ## Using cJson
Line 20: Line 15:
 </markdown> </markdown>
  
 +<tabbox AutoHotkey v2.0>
 +<runner ahk2>
 +#Requires AutoHotkey v2.0
 +
 +#Include <cJson>
 +
 +; Create an object with every supported data type
 +obj := ["abc", 123, {true: true, false: false, null: ""}, [JSON.true, JSON.false, JSON.null]]
 +
 +; Convert to JSON
 +MsgBox JSON.Dump(obj) ; Expect: ["abc", 123, {"false": 0, "null": "", "true": 1}, [true, false, null]]
 +</runner>
 +<tabbox AutoHotkey v1.1>
 <runner> <runner>
 #Requires AutoHotkey v1.1 Unicode #Requires AutoHotkey v1.1 Unicode
Line 29: Line 37:
 ; Convert to JSON ; Convert to JSON
 MsgBox, % JSON.Dump(obj) ; Expect: ["abc", 123, {"false": 0, "null": "", "true": 1}, [true, false, null]]</runner> MsgBox, % JSON.Dump(obj) ; Expect: ["abc", 123, {"false": 0, "null": "", "true": 1}, [true, false, null]]</runner>
 +</tabbox>
  
 <markdown> <markdown>
Line 34: Line 43:
 </markdown> </markdown>
  
 +<tabbox AutoHotkey v2.0>
 +<runner ahk2>
 +#Requires AutoHotkey v2.0
 +
 +#Include <cJson>
 +
 +; Create some JSON
 +str := '["abc", 123, {"true": 1, "false": 0, "null": ""}, [true, false, null]]'
 +obj := JSON.Load(str)
 +
 +; Convert using default settings
 +MsgBox (
 + str "`n"
 + "`n"
 + "obj[1]: " obj[1] " (expect abc)`n"
 + "obj[2]: " obj[2] " (expect 123)`n"
 + "`n"
 + "obj[3]['true']: " obj[3]['true'] " (expect 1)`n"
 + "obj[3]['false']: " obj[3]['false'] " (expect 0)`n"
 + "obj[3]['null']: " obj[3]['null'] " (expect blank)`n"
 + "`n"
 + "obj[4][1]: " obj[4][1] " (expect 1)`n"
 + "obj[4][2]: " obj[4][2] " (expect 0)`n"
 + "obj[4][3]: " obj[4][3] " (expect blank)`n"
 +)
 +
 +; Convert Bool and Null values to objects instead of native types
 +JSON.BoolsAsInts := false
 +JSON.NullsAsStrings := false
 +obj := JSON.Load(str)
 +MsgBox obj[4][1] == JSON.True ; 1
 +MsgBox obj[4][2] == JSON.False ; 1
 +MsgBox obj[4][3] == JSON.Null ; 1
 +</runner>
 +<tabbox AutoHotkey v1.1>
 <runner> <runner>
 #Requires AutoHotkey v1.1 Unicode #Requires AutoHotkey v1.1 Unicode
Line 60: Line 104:
 ;MsgBox, % "obj[4, 3]: " obj[4, 3] == JSON.Null ; 1 ;MsgBox, % "obj[4, 3]: " obj[4, 3] == JSON.Null ; 1
 </runner> </runner>
 +</tabbox>
  
 <markdown> <markdown>
Line 70: Line 115:
 magic objects that give you greater control over how things are encoded. By magic objects that give you greater control over how things are encoded. By
 default, cJson will behave according to the following table: default, cJson will behave according to the following table:
 +</markdown>
  
 +<tabbox AutoHotkey v2.0>
 +<markdown>
 +| Value         | Encodes as            | Decodes as            |
 +|---------------|---------------------- |---------------------- |
 +| `true`        | `1`                   | `1` *                 |
 +| `false`       | `0`                   | `0` *                 |
 +| `null`        | N/A                   | `""` *                |
 +| `0.1` †       | `0.10000000000000001` | `0.10000000000000001` |
 +| `JSON.True`   | `true`                | N/A                   |
 +| `JSON.False`  | `false`               | N/A                   |
 +| `JSON.Null`   | `null`                | N/A                   |
 +
 +\* To avoid type data loss when decoding `true` and `false`, the class property
 +   `JSON.BoolsAsInts` can be set `:= false`. Once set, boolean true and false
 +   will decode to `JSON.True` and `JSON.False` respectively. Similarly, for
 +   Nulls `JSON.NullsAsStrings` can be set `:= false`. Once set, null will decode
 +   to `JSON.Null`.
 +
 +† In AutoHotkey, numbers with a fractional component are represented internally
 +  as double-precision floating point values. Floating point values are
 +  effectively a base-2 fraction, and just like how not all base-10 fractions can
 +  convert cleanly into base-10 decimals (see: 2/3 to 0.333...) not all base-2
 +  fractions can convert cleanly into base-10 decimals. This results in
 +  situations where you write a simple base-10 decimal of 0.1, but it shows as a
 +  really ugly 0.10000000000000001 when your code displays it. Although
 +  AutoHotkey v1 used a bunch of tricks to hide this imprecision, such as by
 +  rounding aggressively to six places and by storing decimal values written in
 +  your code as strings until used for calculation, AutoHotkey v2 does not try to
 +  hide this. Similarly, cJson does not either.
 +</markdown>
 +<tabbox AutoHotkey v1.1>
 +<markdown>
 | Value         | Encodes as | Decodes as    | | Value         | Encodes as | Decodes as    |
 |---------------|------------|---------------| |---------------|------------|---------------|
Line 92: Line 170:
   into a script are saved by AHK as hybrid floats. To force encoding as a float,   into a script are saved by AHK as hybrid floats. To force encoding as a float,
   perform some redundant operation like adding zero.   perform some redundant operation like adding zero.
 +</markdown>
 +</tabbox>
  
 +<markdown>
 ### Array Detection ### Array Detection
- +</markdown> 
-AutoHotkey makes no internal distinction between indexed-sequential arrays and+<tabbox AutoHotkey v2.0> 
 +<markdown> 
 +AutoHotkey v2.0 has separate Array and Map objects, and those will convert to 
 +JSON Arrays and Maps correctly. 
 +</markdown> 
 +<tabbox AutoHotkey v1.1> 
 +<markdown> 
 +AutoHotkey v1.1 makes no internal distinction between indexed-sequential arrays and
 keyed objects. As a result, this distinction must be chosen heuristically by the keyed objects. As a result, this distinction must be chosen heuristically by the
 cJson library. If an object contains only sequential integer keys starting at cJson library. If an object contains only sequential integer keys starting at
 `1`, it will be rendered as an array. Otherwise, it will be rendered as an `1`, it will be rendered as an array. Otherwise, it will be rendered as an
 object. object.
 +</markdown>
 +</tabbox>
 +<markdown>
  
 ## Roadmap ## Roadmap
Line 110: Line 201:
 * Add methods to replace values in the JSON blob without fully parsing and * Add methods to replace values in the JSON blob without fully parsing and
   reformatting the blob.   reformatting the blob.
-* Add a special class to force encoding of indexed arrays as objects. 
 * Integrate with a future MCLib-hosted COM-based hash-table style object for * Integrate with a future MCLib-hosted COM-based hash-table style object for
   even greater performance.   even greater performance.
-* AutoHotkey v2 support. 
  
 --- ---
  
-## [Download cJson.ahk](https://github.com/G33kDude/cJson.ahk/releases)+[Download cJson.ahk](https://github.com/G33kDude/cJson.ahk/releases)
 </markdown> </markdown>