WKL Office JSON

Do izdaje 1.0.3 se je knjižnica imenovala WKL Access JSON.

graph TD
    D["JDoc – LoadJson, Load, Save, Json, ParseError, DateZone"] -->|"Root"| N["JNode (poljubno vozlišče) – Item, Value, Path, ChildNodes, JPath, SelectNodes, GetString …"]
    N --> E["JElement – objekt JSON: Keys, HasKey, SetValue, AddElement, AddArray, RemoveKey"]
    N --> A["JArray – polje JSON: Add, Insert, RemoveAt"]
    N --> V["JValue – niz, število, true/false, null"]
    N -->|"SelectNodes, ChildNodes"| L["JNodeList – Item, Count, For Each"]
    D -->|"neuspelo nalaganje"| P["JParseError – Line, LinePos, SrcText, Reason"]

Knjižnica JSON za Access in VBA z objektnim modelom, kakršnega poznate iz MSXML: dokument naložite, po njem poizvedujete z JPath, berete tipizirane vrednosti, spreminjate in ustvarjate vozlišča ter rezultat zapišete kot besedilo JSON ali v datoteko.

• Pojmi iz MSXML: JDoc kot dokument, LoadJson s ParseError, SelectSingleNode in SelectNodes, seznami vozlišč s For Each.
• JPath po RFC 9535 (JSONPath): poti, nadomestni znaki, rekurzivni spust, rezine, filtri s primerjavami in funkcijami.
• Tipizirane bralne metode z nadomestno vrednostjo: GetString, GetLong, GetDouble, GetCurrency, GetDecimal, GetDate, GetBoolean, GetValue, vsaka z izbirno nadomestno vrednostjo, podobno kot pri Nz().
• Natančna števila: števila ohranijo besedilo, s katerim so bila prebrana, zato Json, Save in GetString nikoli ne spremenijo nobene števke. GetCurrency in GetDecimal to besedilo pretvorita neposredno, ne prek Double; Currency nato zaokroži na štiri decimalna mesta, Decimal na 28–29 veljavnih števk. 19-mestni identifikatorji se ohranijo kot Decimal.
• Datumi: ISO 8601 (profil RFC 3339) v obeh smereh, s pravilom za časovne pasove, ki velja za ves dokument.
• Gradnja JSON: SetValue samodejno ustvari manjkajoče objekte in polja na poti; poleg tega gnezdeni objekti, kopije vozlišč in odstranjevanje vozlišč.
• Vedenje kot v programu Access: privzeti član Item, položaji, šteti od 0, Is za istovetnost, stalne številke napak s potjo ali položajem v opisu.
• Brez namestitve izvajalnega okolja: ena knjižnica DLL NativeAOT za 32-bitni in ena za 64-bitni Office.

Dokument in vozlišča. JDoc vsebuje eno drevo. Vsako vozlišče je JNode; njegov konkretni razred je JElement (objekt), JArray (polje; v tej dokumentaciji „polje“ vedno pomeni polje JSON oziroma VBA, angl. array) ali JValue, katerega od njih, pove NodeType. Vozlišča, ustvarjena s CreateElement, CreateArray in CreateValue, so nevezana, dokler jih ne vstavite.

Poti. Izrazi JPath se začnejo pri korenu ($) ali, brez $, pri vozlišču, na katerem jih pokličete. SelectSingleNode vrne prvo ujemanje ali Nothing, SelectNodes vsa ujemanja, Exists pa pove, ali ujemanje obstaja; bralne metode preberejo prvo ujemanje kot tipizirano vrednost.

Vrednosti. Branje števila vrne naravni tip VBA (Long, Decimal ali Double); bralne metode vrednost pretvorijo v zahtevani tip, vrednosti, ki vanj ne sodijo, pa zavrnejo, namesto da bi jih okrnile. JSON null je v VBA Null.

Napake. Nalaganje vrne False in izpolni ParseError, tako kot v MSXML. Pri vseh drugih napakah se sproži napaka VBA s številko iz JErrorCode; napaka, ki je knjižnica ne predvideva, se javi kot &H8000FFFF z besedilom vzroka, pomanjkanje pomnilnika kot &H8007000E. Sporočila (ParseError.Reason, Err.Description) so v angleščini, nemščini, slovenščini, hrvaščini ali italijanščini: v jeziku, ki ga v istem procesu uporabljajo kontrolniki WKL, sicer v jeziku uporabniškega vmesnika sistema Windows, sicer v angleščini. Odločajte po številki, nikoli po besedilu; številka je v vseh jezikih enaka.

• Vadnica: branje in pisanje JSON v VBA
• Navodila:
  • Klic spletne storitve in branje njenega odgovora JSON
  • Poizvedovanje po JSON z JPath
  • Branje natančnih zneskov in velikih identifikatorjev
  • Branje in pisanje datumov in časov
  • Obravnava neveljavnega JSON
• Vrednosti in omejitve: preslikava tipov med JSON in VBA, števila, datumi, omejitve
• Referenca API (v angleščini): JDoc, `JNode`, `JElement`, `JArray`, `JValue`, `JNodeList`, `JParseError`, naštevanja
• Odpravljanje težav:
  • LoadJson vrne False za JSON, ki ga druga orodja sprejmejo
  • Bralna metoda sproži jeTypeMismatch
  • Datum, prebran iz JSON, je zamaknjen za nekaj ur
  • SetValue sproži jeUnsupportedValue
  • New JDoc javi napako 429 ali pa je sklic označen kot manjkajoč (v angleškem Officeu MISSING): napačna različica (32- ali 64-bitna), glejte Namestitev in uvajanje