JDoc

Dim myJDoc As New JDoc

A JSON document: loads, holds, queries and writes one JSON tree.

None

JDoc is the entry point, created with New JDoc; its concepts follow MSXML's DOMDocument: LoadJson and ParseError as loadXML and parseError, Root as documentElement, SelectSingleNode and SelectNodes with JPath instead of XPath.

The query members (JPath, SelectSingleNode, SelectNodes, Exists and the getters) work on the root node; their rules are described once on `JNode`.

JSON is strict RFC 8259: no comments, no trailing commas, no single quotes. The nesting depth is limited to 512 levels, because the parser runs on the Access UI thread and shares its stack with VBA.

Created with New JDoc or CreateObject.

Dim doc As New JDoc
If Not doc.LoadJson(responseText) Then
    MsgBox "Invalid JSON in line " & doc.ParseError.Line & ": " & doc.ParseError.Reason
    Exit Sub
End If
Debug.Print doc.GetString("$.customer.name")

None

Function LoadJson(ByVal Json As String) As Boolean

Parses JSON text into the document.

Return value: Boolean – True on success; False when the text is not valid JSON, with the details in ParseError.

A leading U+FEFF (byte order mark) is ignored. As MSXML's loadXML, an invalid text does not raise an error: the document is left empty and ParseError describes the problem (line, column, line text, reason). Always check the return value: after a failed load only the getters without a default (GetString(path) …) raise the error of the load (jeParseError, or jeFileError after Load). Queries report nothing - SelectNodes returns an empty list, so a For Each over it does not run, SelectSingleNode and Root return Nothing, Exists returns False, Json returns an empty string - and getters with a default return the default.

None

Declared by JDoc.

Function Load(ByVal FileName As String) As Boolean

Reads a JSON file into the document.

Return value: Boolean – True on success; False when the file cannot be read or is not valid JSON, with the details in ParseError.

The file is read as UTF-8 unless a byte order mark selects UTF-16 or UTF-32 (see Values and limits). As LoadJson, Load raises no error: a file that cannot be read, or invalid content, empties the document and returns False; ParseError.ErrorCode is jeFileError or jeParseError. For jeFileError, Line, LinePos and FilePos are 0 and SrcText is empty.

None

Declared by JDoc.

Sub Save(ByVal FileName As String, Optional ByVal Indent As Boolean = True)

Writes the document to a UTF-8 file.

A file that cannot be written raises jeFileError; the description names the cause (file or folder missing, path too long or invalid, access denied, otherwise the HRESULT). An empty document writes an empty file, which Load rejects.

None

Declared by JDoc.

Property Get Json() As String

Returns the whole document as compact JSON text.

None

Property value: String – The JSON text; an empty string for an empty document.

Read-only.

None

Declared by JDoc.

Function ToJson(Optional ByVal Indent As Boolean = False) As String

Returns the whole document as JSON text.

Return value: String – The JSON text.

Output escapes " and \, the control characters U+0000-U+001F (\b \f \n \r \t, the others as \u00XX) and unpaired surrogates (\uXXXX); all other characters, including non-ASCII characters, /, U+007F, U+2028 and U+2029, are written as they are. Indented output uses two spaces and CR LF.

None

Declared by JDoc.

Property Get Root() As JNode
Property Set Root(RHS As JNode)

Gets or sets the root node of the document.

None

Property value: `JNode` – The root node; Nothing for an empty document.

Assign a node created with CreateElement, CreateArray or CreateValue with Set doc.Root = node.

Read/write.

None

Declared by JDoc.

Property Get ParseError() As JParseError

Returns the details of the last failed load.

None

Property value: `JParseError` – A `JParseError`; its ErrorCode is 0 after a successful load.

Read-only.

None

Declared by JDoc.

Function CreateElement() As JElement

Creates an empty JSON object that is not yet attached to the tree.

None

Return value: `JElement` – The new `JElement`.

None

None

Declared by JDoc.

Function CreateArray() As JArray

Creates an empty JSON array that is not yet attached to the tree.

None

Return value: `JArray` – The new `JArray`.

None

None

Declared by JDoc.

Function CreateValue(ByVal Value As Variant) As JValue

Creates a JSON value that is not yet attached to the tree.

Return value: `JValue` – The new `JValue`.

None

None

Declared by JDoc.

Function JPath(ByVal Path As String) As JNode

Applies `JNode.JPath` to the root node.

Return value: `JNode` – The first node found, or Nothing.

None

None

Declared by JDoc.

Function SelectSingleNode(ByVal Path As String) As JNode

Applies `JNode.SelectSingleNode` to the root node.

Return value: `JNode` – The first node found, or Nothing.

None

None

Declared by JDoc.

Function SelectNodes(ByVal Path As String) As JNodeList

Applies `JNode.SelectNodes` to the root node.

Return value: `JNodeList` – A `JNodeList` of the nodes found.

None

None

Declared by JDoc.

Function Exists(ByVal Path As String) As Boolean

Applies `JNode.Exists` to the root node.

Return value: Boolean – True when at least one node is found.

None

None

Declared by JDoc.

Function GetString(ByVal Path As String, Optional ByVal Default As Variant) As String

Applies `JNode.GetString` to the root node.

Return value: String – The value as String.

None

None

Declared by JDoc.

Function GetLong(ByVal Path As String, Optional ByVal Default As Variant) As Long

Applies `JNode.GetLong` to the root node.

Return value: Long – The value as Long.

None

None

Declared by JDoc.

Function GetDouble(ByVal Path As String, Optional ByVal Default As Variant) As Double

Applies `JNode.GetDouble` to the root node.

Return value: Double – The value as Double.

None

None

Declared by JDoc.

Function GetCurrency(ByVal Path As String, Optional ByVal Default As Variant) As Currency

Applies `JNode.GetCurrency` to the root node.

Return value: Currency – The value as Currency.

None

None

Declared by JDoc.

Function GetDecimal(ByVal Path As String, Optional ByVal Default As Variant) As Variant

Applies `JNode.GetDecimal` to the root node.

Return value: Variant – The value as a Decimal Variant.

None

None

Declared by JDoc.

Function GetDate(ByVal Path As String, Optional ByVal Default As Variant) As Date

Applies `JNode.GetDate` to the root node.

Return value: Date – The value as Date.

None

None

Declared by JDoc.

Function GetBoolean(ByVal Path As String, Optional ByVal Default As Variant) As Boolean

Applies `JNode.GetBoolean` to the root node.

Return value: Boolean – The value as Boolean.

None

None

Declared by JDoc.

Function GetValue(ByVal Path As String, Optional ByVal Default As Variant) As Variant

Applies `JNode.GetValue` to the root node.

Return value: Variant – The value as Variant.

None

None

Declared by JDoc.

Function SetValue(ByVal Path As String, ByVal Value As Variant) As JNode

Sets the value at a simple path and creates missing objects on the way.

Return value: `JNode` – The node that holds the value.

Missing objects and arrays along the path are created (an object for a following name, an array for a following position); an empty document gets one as its root. A position equal to the length of an array appends; a negative position counts from the end; any other position outside the array raises jeIndexOutOfRange. The path $ replaces the root. A step into a value of the wrong kind (a name into an array, a position into an object or value) raises jeInvalidOperation. Inserting a node follows the rules of `JElement.SetValue`.

doc.SetValue "$.address.city", "Chicago"   ' creates "address" when missing

Declared by JDoc.

Property Get DateZone() As JDateZone
Property Let DateZone(RHS As JDateZone)

Gets or sets how times with a zone are read by GetDate and DateValue.

None

Property value: `JDateZone` – One of the `JDateZone` constants; the default is jdzLocal.

Writing a Date never adds a zone, because a VBA Date has none.

Read/write.

None

Declared by JDoc.