libJSONHandle

A library that makes a query or an edit for JSON or JSONL, and offers a toolset for managing an embedded JSONL database.

The library is originally designed for satisfying the needs to handle the replies from AI models. Now it is able to handle the operations to an embeded database with the format of JSON Lines.

The library is released under GNU Lesser General Public License version 3.0, while the executable program is released under Apache License version 2.0.

Version 2.0.7 - Release Notes

Download source: libJSONHandle-2.0.7.tar.xz

Download binary for Linux (amd64): libJSONHandle-2.0.7-linux-amd64.tar.xz (Built using GCC 16.0 experimental, cmake and make; tested on Debian 14 Testing for amd64)

Third-Party Libraries

If there is an error that says libstdc++.so.6.0.35 is not found, you may download libstdc++-6.0.35.tar.xz, and extract libstdc++.so.6 to the folder of libJSONHandle's binary. The libstdc++ library is distributed under GCC Runtime Library Exception.

The binaries of old libJSONHandle versions for Windows are distributed with GCC runtime libraries and MinGW-w64 winpthreads library. GCC runtime libraries are distributed under GCC Runtime Library Exception. MinGW-w64 winpthreads library is distributed under MIT License and BSD 3-Clause Clear License (Copyright (c) 2011 mingw-w64 project. (C) 2010 Lockless Inc. All rights reserved.).

How to Use the Executable Program

jsonHandle [options]

For example:

1. Make a query

(1) For a single JSON entry, only a single query is allowed.

jsonHandle example.json -q candidates.content.parts.text -c candidates.content.role=model

(2) For a JSONL file, multiple queries are supported.

jsonHandle example.jsonl -q users.age,users.email,users.address -c users.name=Tom

2. Make an edit

(1) For a single JSON entry, only a single edit is allowed.

jsonHandle example.json -e "hardware.gpu model=\"NVIDIA GeForce RTX 4060\"" -c hardware.id=12345

(2) For a JSONL file, multiple edit operations are supported.

In command line, because the separator is a comma, an edit is very

restricted. If you directly use the library's functions for edit

operations, you may use a vector for implementing multiple edit operations.

jsonHandle example.jsonl -e "hardware.gpu model=\"NVIDIA GeForce RTX 4060\",hardware.gpu memory=8" -c hardware.id=12345

Options:

<file>

The path of a JSON file.

The file path should be enclosed in double quotation marks if it contains a space.

When the option is lacking, or the path is invalid, the program will ask for providing a JSON text.

-q

The query.

The hierarchy keys are separated by a dot.

If there is a space in the query, the query should be enclosed in double quotation marks.

For example:

-q candidates.content.parts.text

-q "hardware.gpu brand"

-e

The assignment expression for an edit.

The hierarchy keys in a key path are separated by a dot.

If there is any space in the edit string, please enclose the string in double quotation marks.

Besides the outer quotation marks, a string-type value must be explicitly enclosed in double quotation marks with one of the following methods:

Use single quotation marks as outer quotation marks for the edit string like '"string"';

Or use escaped double quotation marks to enclose the string-type value like "\"string\"".

If the type of value is different from the type of the original value, the edit will be ignored unless using the option "-ef".

There are the rules about how to write an edit string for modifying, inserting or deleting a value, a key or an element.

(1) For editing a value in an object, the format of an edit string is "keyPath=value".

(2) For editing a value in an array, the format of an edit string is "keyPath:index=value".

(3) For inserting a key-value pair to an object, the format of an edit string is "objectKeyPath+key=value".

(4) For inserting a key-value pair to an object in an array, the format of an edit string is "arrayKey+key=value".

(5) For inserting an element to an array, the format of an edit string is "arrayKeyPath+element". The element is a simple value or an object, following the rules of JSON.

(6) For inserting a top-layer key-value pair, the format of an edit string is "+key=value".

(7) For removing a top-layer key, the format of an edit string is "-key".

(8) For removing a key from an object, the format of an edit string is "objectKeyPath-key".

(9) For removing an element from an array, the format of an edit string is "arrayKeyPath-index".

For example:

-e "hardware.cpu model"="\"Intel Core i9 14900\""

-e "gpu products+model=\"NVIDIA GeForce RTX 4060\""

-c

The conditions for the query.

The hierarchy keys are separated by a dot.

There is an equals sign between the keys and the value.

Multiple conditions are separated by a comma.

If there is any space, the string with a space or the entire string should be enclosed in double quotation marks.

Without the option, a query or an edit operation will be implemented to the first found key or element for a single JSON entry or all JSON lines in a JSONL file. Because of this mechanism, you may get the list of a specific key for a JSONL file.

For example:

-c candidates.content.role=model

-c "device type"="Raspberry Pi"

-c "device type=Personal Computer,hardware.cpu brand=AMD"