jsonmacros 0.0.4

A JSON preprocessor with macros, conditionals, and includes

JSONMacros

A JSON preprocessor with macros, conditionals, and includes for Python.

Overview

JSONMacros allows you to write dynamic JSON files with macro definitions, conditional logic, file includes, and Python expression evaluation. It's perfect for configuration files, data templates, and any scenario where you need programmatic JSON generation.

Features

• Macros: Define reusable variables and functions with parameters
• Conditionals: Use $if, $then, $else for conditional content
• File Includes: Import and merge other JSON files with $include
• Python Expressions: Evaluate Python code within JSON using ${...} syntax
• Flexible Merging: Control how included files are merged

Installation

pip install jsonmacros

Quick Start

from jsonmacros import JsonMacroProcessor

processor = JsonMacroProcessor()
result = processor.process_file("path/to/your/template.json")
print(result)

Usage Examples

Basic Macros

Input

{
    "$macros": [
        {
            "name": "greeting",
            "body": "Hello, world!"
        },
        {
            "name": "number",
            "body": 42
        }
    ],
    "message": "${greeting}",
    "value": "${number}"
}

Output

{
    "message": "Hello, world!",
    "value": 42
}

Parameterized Macros

Input

{
    "$macros": [
        {
            "name": "add",
            "params": ["x", "y"],
            "body": "${x + y}"
        }
    ],
    "value": {
        "$macro": "add",
        "$params": {
            "x": 6,
            "y": 7
        }
    }
}

Output

{
    "value": 13
}

Conditionals

Input

{
    "$macros": [
        {
            "name": "score",
            "body": 85
        }
    ],
    "result": {
        "$if": "${score >= 90}",
        "$then": "Excellent",
        "$else": {
            "$if": "${score >= 70}",
            "$then": "Good",
            "$else": "Needs Improvement"
        }
    }
}

Output

{
    "result": "Good"
}

File Includes

Create modular JSON files by including others:

base.json:

{
    "$macros": [
        {
            "name": "app_name",
            "body": "MyApp"
        }
    ],
    "config": {
        "name": "${app_name}",
        "version": "1.0.0"
    }
}

extended.json:

{
    "$include": ["base.json"],
    "$macros": [
        {
            "name": "environment",
            "body": "production"
        }
    ],
    "config": {
        "environment": "${environment}",
        "debug": false
    }
}

output.json (with merge strategy MERGE):

{
    "config": {
        "name": "MyApp",
        "version": "1.0.0",
        "environment": "production",
        "debug": false
    }
}

API Reference

JsonMacroProcessor

The main class for processing JSON with macros.

from jsonmacros import JsonMacroProcessor, JsonMergeStrategy

processor = JsonMacroProcessor(merge_strategy=JsonMergeStrategy.OVERRIDE)

JsonMergeStrategy

Controls how included files are merged:

• Define merge strategies for handling conflicts and combining data

Examples

See the examples/ directory for more comprehensive examples:

• examples/test.json - Parameterized macros with Python expressions
• examples/merge_a.json - Base configuration with macros
• examples/merge_b.json - Extended configuration with includes and conditionals

Requirements

• Python >=3.9

License

This project is licensed under the BSD 3-Clause License - see the LICENSE.md file for details.

Contributing

Issues and contributions are welcome! Please visit the GitHub repository to report bugs or request features.

Authors

• Broderick Riopelle [e-mail]