🐍 The jsoncons Package 🐛❇️🐉

🚙🦖 COBOL-to-JSON CLI Utility in Python 🦕🐍

The jsoncons package is designed to provide a basic command-line interface for handling JSON data. This can be useful for simple scripting or interoperability tasks (e.g., having a COBOL program generate a text file that this tool converts to JSON, or vice versa). COBOL-to-JSON parsing features were added in v1.0.0 and will be extended in future versions of jsoncons.

Installation:

pip install jsoncons

Basic Usage for Pretty-Print JSON:

• Create Input File If Necessary: In your project directory, verify there is a file named input.json with the following content:

  {"key":"value", "items":[1,2]}

• Validate & Pretty-print JSON: Read from stdin, write to stdout. (Linux Command)

  echo '{"key":"value", "items":[1,2]}' | jsoncons encode

  Windows Powershell Command: Read from stdin, write to stdout.

  echo {"\"key\"":"\"value\"", "\"items\"":[1,2]} | jsoncons encode

• Validate & Pretty-print JSON from file to file: (Tested on Windows 10)

  jsoncons encode input.json output_pretty.json

• (The decode command might be an alias or offer slightly different formatting if needed)

Latest Release: jsoncons v1.1.0 ✨

New Features: Fibonacci Hashing Integration

• Fibonacci Hashing Function: fibonacci_hash_to_index() for efficient hash table indexing
• New CLI Commands:
  • process_json_fib - Fibonacci variant of JSON processing
  • cobol_to_json_fib - Fibonacci variant of COBOL-to-JSON conversion
• Comprehensive Jupyter Notebook: Fibonacci_Hashing_Demo.ipynb demonstrating:
  • Performance benchmarks (Fibonacci vs. Modulo vs. Bitwise AND hashing)
  • Distribution analysis with visualizations
  • Step-by-step algorithm visualization
  • Educational content on hashing techniques
• Full Backward Compatibility: All existing commands work unchanged
• Tested on Python: 3.8+, 3.11.1, 3.11.2, 3.12.1

What is Fibonacci Hashing?

Fibonacci hashing is a multiplicative hashing technique that uses the golden ratio to distribute hash values uniformly across power-of-2 sized hash tables. It's faster than modulo hashing and provides better distribution than simple bitwise AND operations.

Key Benefits:

• ⚡ Performance: Uses only multiplication and bit shift operations
• 📊 Distribution: Uniform distribution across hash table indices
• 🎓 Educational: Learn about advanced hashing techniques
• 🔧 Extensible: Foundation for future performance optimizations

Using Fibonacci Hashing

# Process JSON with Fibonacci variant
jsoncons process_json_fib input.json output.json

# Convert COBOL to JSON with Fibonacci variant
jsoncons cobol_to_json_fib --layout-file layout.json input.cobol output.json

# Use the Fibonacci hashing function in Python
from jsoncons.cli import fibonacci_hash_to_index

index = fibonacci_hash_to_index(hash_value=12345, table_size_power_of_2=1024)
print(f"Hash index: {index}")  # Output: 0-1023

Jupyter Notebook Demo

Run the included Fibonacci_Hashing_Demo.ipynb to see:

• Performance comparisons with 100,000 hash operations
• Distribution analysis with histograms
• Visual step-by-step demonstration of the algorithm
• Practical applications and conclusions

Previous Release: jsoncons v1.0.4

Bug Fixed: f-string Issue in COBOL-to-JSON function

• COBOL-to-JSON function tested in 3.11.1, 3.11.2, 3.12.1
• Compatibility with Python v3.8+

Roadmap to v2.0.0

• Integration with IBM zOS
• Performance optimizations using Fibonacci hashing in internal data structures
• Enhanced COBOL field lookup with hash table acceleration

🤝 Contributing 🖥️

Contributions are welcome! If you find errors, have suggestions for improvements, or want to add more examples, please feel free to:

1. Open an issue to discuss the change.
2. Fork the repository.
3. Create a new branch (git checkout -b feature/your-feature-name).
4. Make your changes and commit them (git commit -m 'Add some feature').
5. Push to the branch (git push origin feature/your-feature-name).
6. Open a Pull Request.

📝 License ⚖️

This project is licensed under the MIT License - see the LICENSE file for details.

---

🧪 Unit Test Explanation For jsoncons Package ✅

1. Imports: Imports necessary modules like unittest, sys (for patching argv/streams), io (for capturing streams), os, json, tempfile, shutil, and unittest.mock.patch. It also imports the cli module from the package.
2. TestJsonConsCLI Class: Inherits from unittest.TestCase.
3. setUp:
   • Creates a temporary directory using tempfile.mkdtemp() to isolate test files.
   • Defines paths for input, output, and invalid files within the temp directory.
   • Creates sample valid and invalid JSON strings and data structures.
   • Writes the sample valid and invalid JSON to the respective temporary files.
4. tearDown: Cleans up by removing the temporary directory and all its contents using shutil.rmtree().
5. run_cli Helper:
   • Takes a list of arguments (args_list) and optional stdin_data.
   • Prepends the script name ('serial-json') to the arguments list as sys.argv[0].
   • Uses unittest.mock.patch as a context manager to temporarily replace sys.argv, sys.stdout, and sys.stderr with test-controlled objects (io.StringIO for streams).
   • If stdin_data is provided, sys.stdin is also patched.
   • Calls the actual cli.main() function within the patched context.
   • Catches SystemExit (which sys.exit() raises) to get the exit code.
   • Returns the captured stdout string, stderr string, and the exit code.
6. Test Methods (test_...):
   • Each method tests a specific scenario (stdin/stdout, file I/O, options, errors).
   • They call run_cli with appropriate arguments and/or stdin data.
   • They use self.assertEqual, self.assertNotEqual, self.assertTrue, self.assertIn, etc., to verify:
     • The exit code (0 for success, non-zero for errors).
     • The content of captured stderr (should be empty on success, contain error messages on failure).
     • The content of captured stdout (when output is expected there).
     • The existence and content of output files (when file output is expected).
7. if __name__ == '__main__':: Allows running the tests directly using python -m unittest tests.test_cli or python tests/test_cli.py.

⛰️ Extending jsoncons to COBOL 👀

How COBOL could interact:

A COBOL program could:

1. Write data to a temporary text file (e.g., input.txt).
2. Use CALL 'SYSTEM' (or equivalent OS call) to execute the Python script:

   CALL 'SYSTEM' USING 'jsoncons input.txt output.json'.

3. Read the resulting output.json file from COBOL.

Alternatively:

1. COBOL generates simple key-value pairs or a structured text format.
2. A more sophisticated jsoncons encode command could be written to parse this specific text format and produce JSON.
3. A jsoncons decode command could parse JSON and output a simple text format readable by COBOL.

The provided CLI keeps things simple and standard, relying on JSON as the interchange format, which COBOL would interact with via file I/O and system calls.