Add json_parser library

Author: diffstorm

CMakeLists.txt

@@ -0,0 +1,69 @@
+# author Eray Ozturk | erayozturk1@gmail.com
+# url github.com/diffstorm
+cmake_minimum_required(VERSION 3.12)
+project(json_parser LANGUAGES C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Library configuration
+add_library(json_parser STATIC
+    json_parser.h
+    json_parser.c
+)
+
+set_target_properties(json_parser PROPERTIES
+    C_VISIBILITY_PRESET hidden
+    INTERPROCEDURAL_OPTIMIZATION FALSE
+)
+
+target_include_directories(json_parser PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+# C demo
+add_executable(demo
+    demo.c
+)
+
+# C++17 demo
+add_executable(demo_cpp
+    demo.cpp
+)
+
+# Link demo to library
+target_link_libraries(demo PRIVATE json_parser)
+target_link_libraries(demo_cpp PRIVATE json_parser)
+
+# Google Test configuration
+find_package(GTest REQUIRED)
+find_package(Threads REQUIRED)
+
+# Test executable
+add_executable(json_parser_tests
+    json_parser_test.cpp
+)
+
+target_link_libraries(json_parser_tests
+    PRIVATE
+    json_parser
+    GTest::GTest
+    GTest::Main
+    Threads::Threads
+)
+
+enable_testing()
+add_test(NAME json_parser_tests COMMAND json_parser_tests)
+
+# Installation configuration
+install(TARGETS json_parser
+    ARCHIVE DESTINATION lib
+    LIBRARY DESTINATION lib
+    INCLUDES DESTINATION include
+)
+
+install(FILES json_parser.h
+    DESTINATION include
+)

README.md

@@ -1,2 +1,45 @@
-# json_parser
-Header only lightweight JSON parser library
+# JSON Parser Library
+
+A lightweight, single-header C library for parsing JSON data. Designed for simplicity and portability, this parser provides a low-footprint solution to decode JSON-formatted strings into structured tokens while adhering to core JSON specifications.
+
+## Features
+
+- **Standard Compliance**: Supports parsing of JSON objects, arrays, strings, numbers, and literals (`true`, `false`, `null`).
+- **Unicode Support**: Handles UTF-16 surrogate pairs and encodes Unicode escape sequences into valid UTF-8.
+- **Configurable Limits**: Tunable thresholds for maximum nesting depth, token count, and string length.
+- **Error Reporting**: Detailed error codes and human-readable error messages for troubleshooting parsing issues.
+- **Memory Safety**: Cleanup functions ensure allocated resources are properly released.
+
+## Components
+
+### Core Structures
+- **`json_parser_t`**: Manages the parser state, including input data, token storage, and error tracking.
+- **`json_token_t`**: Represents a parsed JSON token, storing its type (object, array, string, number, etc.) and associated value.
+- **`json_error_t`**: Enumerates all possible parsing errors, such as invalid tokens, nesting depth exceeded, or allocation failures.
+
+### Key Functions
+- **Initialization & Cleanup**: `json_parser_init` prepares the parser, while `json_parser_free` releases allocated memory.
+- **Parsing**: `json_parser_parse` processes the input JSON string and populates tokens.
+- **Utilities**: `json_get_tokens` retrieves parsed tokens, and `json_error_string` converts error codes to descriptive messages.
+
+## Error Handling
+The parser tracks errors during execution and halts on the first encountered issue. Errors range from syntax violations (e.g., unexpected characters) to resource constraints (e.g., exceeding token limits). Users can programmatically check the error type and respond accordingly.
+
+## Building
+The library is implemented as a single-header file (`json_parser.h`) with optional embedded implementation. It can be integrated into projects in two ways:
+1. **As a Header-Only Library**: Define `JSON_PARSER_IMPLEMENTATION` in one source file to include the implementation.
+2. **As a Static Library**: Use the provided CMake configuration to compile a static library, simplifying linking in larger projects.
+
+## Usage
+1. **Initialize the Parser**: Provide the JSON input string and its length.
+2. **Parse the Input**: Execute the parsing routine and check for errors.
+3. **Retrieve Tokens**: Access the parsed tokens to read JSON structure and values.
+4. **Cleanup**: Release parser resources after processing.
+
+## :snowman: Author
+
+Eray Öztürk ([@diffstorm](https://github.com/diffstorm))
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

demo.c

@@ -0,0 +1,56 @@
+/**
+    @brief JSON Parser Library
+
+    A lightweight, single-header C library for parsing JSON data. Designed for simplicity and portability, this parser provides a low-footprint solution to decode JSON-formatted strings into structured tokens while adhering to core JSON specifications.
+
+    @date 2025-05-03
+    @version 1.0
+    @author Eray Ozturk | erayozturk1@gmail.com
+    @url github.com/diffstorm
+    @license MIT License
+*/
+
+#include <stdio.h>
+#include <string.h>
+#define JSON_PARSER_IMPLEMENTATION
+#include "json_parser.h"
+
+int main() {
+    const char *json = "{\"name\":\"John\\u00D0e\",\"age\":30,\"scores\":[90.5,80.0]}";
+    json_parser_t parser;
+    json_parser_init(&parser, json, strlen(json));
+    
+    json_error_t error = json_parser_parse(&parser);
+    if (error != JSON_ERROR_NONE) {
+        printf("Error: %s\n", json_error_string(error));
+        return 1;
+    }
+    
+    size_t count;
+    const json_token_t *tokens = json_get_tokens(&parser, &count);
+    for (size_t i = 0; i < count; i++) {
+        const json_token_t *t = &tokens[i];
+        printf("Token %zu: ", i);
+        switch (t->type) {
+            case JSON_TOKEN_OBJECT:
+                printf("Object\n"); break;
+            case JSON_TOKEN_ARRAY:
+                printf("Array\n"); break;
+            case JSON_TOKEN_STRING:
+                printf("String: %s\n", t->value.string); break;
+            case JSON_TOKEN_NUMBER:
+                printf("Number: %f\n", t->value.number); break;
+            case JSON_TOKEN_TRUE:
+                printf("Boolean: true\n"); break;
+            case JSON_TOKEN_FALSE:
+                printf("Boolean: false\n"); break;
+            case JSON_TOKEN_NULL:
+                printf("Null\n"); break;
+            default:
+                printf("Unknown\n");
+        }
+    }
+    
+    json_parser_free(&parser);
+    return 0;
+}

demo.cpp

@@ -0,0 +1,68 @@
+/**
+    @brief JSON Parser Library
+
+    A lightweight, single-header C library for parsing JSON data. Designed for simplicity and portability, this parser provides a low-footprint solution to decode JSON-formatted strings into structured tokens while adhering to core JSON specifications.
+
+    @date 2025-05-03
+    @version 1.0
+    @author Eray Ozturk | erayozturk1@gmail.com
+    @url github.com/diffstorm
+    @license MIT License
+*/
+
+#include <iostream>
+#include <string>
+
+#include "json_parser.h"
+
+int main() {
+    // Use raw string literal to avoid escaping characters
+    const std::string json = R"({"name":"John\u00D0e","age":30,"scores":[90.5,80.0]})";
+    
+    json_parser_t parser;
+    json_parser_init(&parser, json.data(), json.size());
+    
+    const json_error_t error = json_parser_parse(&parser);
+    if (error != JSON_ERROR_NONE) {
+        std::cerr << "Error: " << json_error_string(error) << "\n";
+        json_parser_free(&parser);
+        return 1;
+    }
+    
+    size_t token_count = 0;
+    const json_token_t* tokens = json_get_tokens(&parser, &token_count);
+    
+    for (size_t i = 0; i < token_count; ++i) {
+        const auto& token = tokens[i];
+        std::cout << "Token " << i << ": ";
+        
+        switch (token.type) {
+            case JSON_TOKEN_OBJECT:
+                std::cout << "Object\n";
+                break;
+            case JSON_TOKEN_ARRAY:
+                std::cout << "Array\n";
+                break;
+            case JSON_TOKEN_STRING:
+                std::cout << "String: " << token.value.string << "\n";
+                break;
+            case JSON_TOKEN_NUMBER:
+                std::cout << "Number: " << token.value.number << "\n";
+                break;
+            case JSON_TOKEN_TRUE:
+                std::cout << "Boolean: true\n";
+                break;
+            case JSON_TOKEN_FALSE:
+                std::cout << "Boolean: false\n";
+                break;
+            case JSON_TOKEN_NULL:
+                std::cout << "Null\n";
+                break;
+            default:
+                std::cout << "Unknown\n";
+        }
+    }
+    
+    json_parser_free(&parser);
+    return 0;
+}

json_parser.c

@@ -0,0 +1,14 @@
+/**
+    @brief JSON Parser Library
+
+    A lightweight, single-header C library for parsing JSON data. Designed for simplicity and portability, this parser provides a low-footprint solution to decode JSON-formatted strings into structured tokens while adhering to core JSON specifications.
+
+    @date 2025-05-03
+    @version 1.0
+    @author Eray Ozturk | erayozturk1@gmail.com
+    @url github.com/diffstorm
+    @license MIT License
+*/
+
+#define JSON_PARSER_IMPLEMENTATION
+#include "json_parser.h"