qb64pe-json - A library for JSON parsing and creation

[DSMan195276]

qb64pe-json
https://github.com/mkilgore/qb64pe-json

qb64pe-json is a library for parsing and creating JSON strings. Currently it is hosted and developed on GitHub, and I just released the beta v0.1.0 version. Attached to this post is the v0.1.0 release, and also the examples currently present in the repository. Below is the README from the repository:

---

qb64pe-json

qb64pe-json is a JSON parsing and creation library for QB64-PE. Given a string containing JSON, it can convert it into a Json object which can then be queried to retrieve the values in the JSON. Additionally it contains a variety of

JsonTokenCreate*

functions which can be used to build up a Json object, which can then be rendered into a String version of that JSON.

Please see json.bi for more in-depth documentation around the API. Additionally see the examples/ for code samples of the API in use.

To use the API, download a release version and place the

json.bi

and

json.bm

files into your project. Then reference the two files via

'$include:

.

Overall Design

qb64pe-json works by turning a JSON structure into a collection of "tokens", which are kept internal to a

Json

object. Tokens are allocated as needed, and token IDs are returned from several Functions. You can then pass a token ID into many of the APIs to interact with the token, such as get its value, get its children, etc. Valid token IDs are always positive.

The main Type in qb64pe-json is the

Json

Type. After declaring one, you need to pass it to

JsonInit

to initialize it, and eventually pass it to

JsonClear

to release it. Not passing a

Json

object to

JsonClear

will result in memory leaks.

There are four types of tokens - Objects, Arrays, Keys, and Values. Values are then split up into several "primitive" types a value can be, which are strings, numbers, bools, and

null

. A typical token structure looks something like this:

This is the original JSON passed to

JsonParse()

:

Code: (Select All)

{
    "key1": {
        "key2": 20,
        "key3": [ true, "string", null ],
    },
    "key4": 50
}

This is the resulting token structure:

Code: (Select All)

Object (1)
  - Key (value = "key1") (2)
    - Object (3)
      - Key (value = "key2") (4)
        - Value (type = number, value = 20) (5)
      - Key (value = "key3") (6)
        - Array (7)
          - Value (type = bool, value = true) (8)
          - Value (type = string, value = "string") (9)
          - Value (type = null) (10)
  - Key (value = "key4") (11)
    - Value (type = number, value = 50) (12)

The numbers after each token signify its ID, which is what will be returned by the API when referring to that particular token. The typical way to interact with this structure is through

JsonQuery()

, which takes a query string and returns the token identified by it. For example, if you do

JsonQuery(json, "key1.key2")

, it will return 5, which is the token ID for the "20" Value token. You can then pass the token ID from that query to

JsonTokenGetValueInteger(token)

to retrieve the actual value 20 as an integer.

JsonQuery(json, "key2.key3")

returns 7, the token ID for the Array. With this array you can make use of

JsonTokenTotalChildren(array)

and pass it the token ID to retrieve the number of children (entries) in that array. You can then additionally make use of

JsonTokenGetChild(array, index)

to get the token ID of each child of the array. Note the indexes into the array start at zero, so

JsonTokenGetChild(array, 0)

would return 8, the bool in the array since it is the first entry.

JsonTokenGetChild(array, 2)

would return 10, the last entry in the array. You can of course then pass those token IDs to the various

JsonTokenGetValue

functions to retrieve their values.

If you have a token and need to know what it is, you can use

JsonTokenGetType(token)

to retrieve a

JSONTOK_TYPE_*

value indicating its type. If its type is

JSONTOK_TYPE_VALUE

, then you can additionally use

JsonTokenGetPrimType(token)

to get its primitive type, in the form of a

JSONTOK_PRIM_*

value.

Json

objects contain the concept of a "RootToken", which is simply the token of the base of the entire JSON structure. Several APIs start at the RootToken automatically, such as

JsonQuery()

,

JsonRender()

, etc. However all APIs offer an option to take a token directly to start with, ignoring the RootToken. This is powerful as it allows you to treat smaller subtrees of the entire structure as their own Json structure. For example in the above structure, you can use

JsonQueryFrom(3, "key2")

to do a query starting from the Object with index 3, completely ignoring the Object it's contained in.

Errors are reported from qb64pe-json via the global

JsonHadError

and

JsonError

variables.

JsonHadError

is zero (

JSON_ERR_Success

) when a function was successful, and a negative value when an error occurs. The negative values correspond to the

JSON_ERR_*

constants, and indicate the specific kind of error that occurred.

JsonError

will contain a human-readable string version of the error.

JSON Creation

In addition to parsing JSON, qb64pe-json allows you to create the Json structure yourself and then turn it into a JSON string (for storing or sending elsewhere). This is done by using the

JsonTokenCreate*()

functions. These functions create a new token and return its token ID. You can then make use of this token ID to add it to other tokens and build the Json structure. Objects and Arrays can have entries added to them via

JsonTokenArrayAdd

and

JsonTokenObjectAdd

.

Once you have built your Json structure, you can optionally use

JsonSetRootToken

to set the RootToken of the Json object to be the root of your created structure. Then, you can use

JsonRender$()

to produce a JSON string version of that structure.

JsonRenderFormatted$()

gives you more control over the rendering. Currently, it allows you to include indentation in the result, which makes it easier to read.