yaml2json

A YAML to JSON converter implemented using the RapidYAML library, designed for high-throughput data processing applications.

Comparative performance measurements were conducted using hyperfine on Apple Silicon (macOS) against established tools yq and lq:

• Zero-copy parsing using memory-mapped file input
• Optimized compiler flags: -O3 -march=native with Link Time Optimization (LTO)
• Direct JSON serialization without intermediate data structures
• Linear time complexity scaling with input size
• Deterministic parsing behavior across test cases
• Excellent performance scaling (7-21x improvement over competitors, with better scaling on larger files)

Performance measurements can be reproduced using the provided test suite:

# Repository setup
git clone https://github.com/SimpleSoftwareOrg/yaml2json.git
cd yaml2json

# Build configuration
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Benchmark execution
cd ../benchmarks
./benchmark.sh                 # Execute comparative measurements (auto-generates test files)

Dependencies: hyperfine and yq (lq is downloaded automatically). Dependency validation is performed automatically.

Test Protocol: Each measurement consists of 3 warmup iterations followed by 20 timed executions using hyperfine. Statistical analysis includes mean execution time, standard deviation, and confidence intervals.

Pre-compiled binaries are available for multiple platforms:

# System-wide installation (/usr/local/bin)
curl -sSL https://raw.githubusercontent.com/SimpleSoftwareOrg/yaml2json/main/install.sh | sudo bash

# User installation (~/bin)
curl -sSL https://raw.githubusercontent.com/SimpleSoftwareOrg/yaml2json/main/install.sh | bash -s -- --user

The tool supports multiple input/output methods for maximum flexibility and backwards compatibility:

# Explicit flags (recommended for scripts)
yaml2json --input input.yaml --output output.json
yaml2json -i input.yaml -o output.json

# Positional arguments (backwards compatible)
yaml2json input.yaml output.json
yaml2json input.yaml output.json --pretty

# Stdin to stdout (great for pipelines)
cat input.yaml | yaml2json
curl -s https://example.com/data.yaml | yaml2json

# File to stdout
yaml2json input.yaml
yaml2json --input input.yaml

# Stdin to file
cat input.yaml | yaml2json --output output.json

# Any of the above with pretty formatting
yaml2json input.yaml --pretty
yaml2json -i input.yaml -o output.json --pretty
cat input.yaml | yaml2json --pretty

* Uses stdin/stdout when not specified. Supports positional arguments for backwards compatibility.

# Traditional usage
yaml2json config.yaml config.json

# Pipeline processing
kubectl get pods -o yaml | yaml2json | jq '.items[0].metadata.name'

# Mixed usage
yaml2json --input config.yaml | jq '.database.host'
cat config.yaml | yaml2json --output config.json --pretty

The tool will provide verbose error messages for any issues encountered during conversion.

• Zero-copy parsing implementation using memory-mapped file I/O
• Link-time optimization (LTO) with platform-specific instruction tuning
• Direct JSON serialization to stdout
• Support for files up to available system memory
• Cross-platform compatibility (macOS, Linux, Windows)

• CMake 3.15 or later
• C++17-compliant compiler (GCC 8+, Clang 8+, MSVC 2019+)

git clone https://github.com/SimpleSoftwareOrg/yaml2json.git
cd yaml2json
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

• CMAKE_BUILD_TYPE=Release - Production build with optimizations
• CMAKE_BUILD_TYPE=Debug - Development build with debug information
• YAML2JSON_STATIC - Static linking configuration

The project includes comprehensive unit tests using Google Test framework. To build and run tests:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)
ctest --output-on-failure

• Unit Tests: Test individual components in isolation
  • FileReaderTest: Tests file reading with mmap support
  • YamlToJsonConverterTest: Tests YAML to JSON conversion
  • JsonFormatterTest: Tests JSON pretty-printing
  • ErrorHandlerTest: Tests error handling and reporting
• Integration Tests: Test the complete workflow
  • End-to-end conversion tests
  • Error handling scenarios
  • Performance tests with large files

This project is licensed under the MIT License. See LICENSE for complete terms.

Contributions are accepted following the guidelines in CONTRIBUTING.md.