Repository files navigation

API Documentation Pages for current and previous releases of this library can be found here

This repository contains the coreJSON library, a parser that strictly enforcesthe ECMA-404 JSON standard and is suitable for low memory footprint embeddeddevices. The coreJSON library is distributed under theMIT Open Source License.

This library has gone through code quality checks including verification that nofunction has aGNU Complexityscore over 8, and checks against deviations from mandatory rules in theMISRA coding standard. Deviations from the MISRAC:2012 guidelines are documented underMISRA Deviations. Thislibrary has also undergone both static code analysis fromCoverity static analysis, and validation of memorysafety through theCBMC automated reasoning tool.

See memory requirements for this libraryhere.

coreJSON v3.3.0source code is partof theFreeRTOS 202406.00 LTSrelease.

#include<stdio.h>#include"core_json.h"intmain(){// Variables used in this example.JSONStatus_tresult;charbuffer[]="{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";size_tbufferLength=sizeof(buffer )-1;charqueryKey[]="bar.foo";size_tqueryKeyLength=sizeof(queryKey )-1;char*value;size_tvalueLength;// Calling JSON_Validate() is not necessary if the document is guaranteed to be valid.result=JSON_Validate(buffer,bufferLength );if(result==JSONSuccess )    {result=JSON_Search(buffer,bufferLength,queryKey,queryKeyLength,&value,&valueLength );    }if(result==JSONSuccess )    {// The pointer "value" will point to a location in the "buffer".charsave=value[valueLength ];// After saving the character, set it to a null byte for printing.value[valueLength ]='\0';// "Found: bar.foo -> xyz" will be printed.printf("Found: %s -> %s\n",queryKey,value );// Restore the original character.value[valueLength ]=save;    }return0;}

A search may descend through nested objects when thequeryKey containsmatching key strings joined by a separator,.. In the example above,bar hasthe value{"foo":"xyz"}. Therefore, a search for query keybar.foo wouldoutputxyz.

A compiler that supportsC90 or later such asgcc is required to build thelibrary.

Additionally, the library uses 2 header files introduced in ISO C99,stdbool.handstdint.h. For compilers that do not provide this header file, thesource/include directory containsstdbool.readme andstdint.readme, which can be renamed tostdbool.h andstdint.h respectively.

For instance, if the example above is copied to a file namedexample.c,gcccan be used like so:

gcc -I source/include example.c source/core_json.c -o example./example

gcc can also produce an output file to be linked:

gcc -I source/include -c source/core_json.c

For pre-generated documentation, please see the documentation linked in thelocations below:

Note that the latest included version of the coreJSON library may differ acrossrepositories.

The Doxygen references were created using Doxygen version 1.9.6. To generate theDoxygen pages, please run the following command from the root of thisrepository:

doxygen docs/doxygen/config.doxyfile

By default, the submodules in this repository are configured withupdate=nonein.gitmodules, to avoid increasing clone time and disk spaceusage of other repositories (likeamazon-freertos that submodules thisrepository).

To build unit tests, the submodule dependency of Unity is required. Use thefollowing command to clone the submodule:

git submodule update --checkout --init --recursive test/unit-test/Unity

• For running unit tests
  • C90 compiler like gcc
  • CMake 3.13.0 or later
  • Ruby 2.0.0 or later is additionally required for the Unity test framework(that we use).
• For running the coverage target, gcov is additionally required.

1. Go to the root directory of this repository. (Make sure that theUnitysubmodule is cloned as describedabove.)

2. Create build directory:mkdir build && cd build

3. Runcmake while inside build directory:cmake -S ../test

4. Run this command to build the library and unit tests:make all

5. The generated test executables will be present inbuild/bin/tests folder.

6. Runctest to execute all tests and view the test run summary.

To learn more about CBMC and proofs specifically, review the training materialhere.

Thetest/cbmc/proofs directory contains CBMC proofs.

In order to run these proofs you will need to install CBMC and other tools byfollowing the instructionshere.

SeeCONTRIBUTING.md for information oncontributing.