03-17-2023, 02:38 AM
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()`:
This is the resulting token structure:
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.
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.