Rust toolkit for COBOL copybook parsing and fixed-record data conversion. Deterministic, memory-safe, zero unsafe in public APIs.
Engineering Preview (v0.4.3). Stable CLI and library APIs; feature completeness is preview-level. See ROADMAP.md for adoption guidance and known limitations.
The repo includes test fixtures. After building, run this to see it work:
git clone https://github.com/EffortlessMetrics/copybook-rs.git
cd copybook-rs
git checkout v0.4.3
cargo build --release
# Decode included EBCDIC fixture to JSON
./target/release/copybook decode \
fixtures/copybooks/simple.cpy \
fixtures/data/simple.bin \
--format fixed --codepage cp037 \
--output demo.jsonl
# View the result
cat demo.jsonl
# {"CUSTOMER-ID":"123456","CUSTOMER-NAME":"John Smith",...,"ACCOUNT-BALANCE":"12345.67",...}The included simple.cpy copybook and simple.bin data file demonstrate EBCDIC-to-JSON conversion with COMP-3 packed decimal fields.
- Data types: DISPLAY, Zoned Decimal, COMP-3, BINARY, COMP-1/COMP-2, Edited PIC
- Structure: REDEFINES, OCCURS (fixed), ODO (tail position), Level-88, RENAMES (R1-R3)
- Formats: Fixed-length and RDW records; CP037/CP273/CP500/CP1047/CP1140
- Features: Field projection (
--select), Dialect lever (--dialect), Deterministic round-trip
- Nested ODO (O5/O6), ODO over REDEFINES
- RENAMES with REDEFINES/OCCURS (R4-R6)
- EXTERNAL / GLOBAL clauses
See COBOL_SUPPORT_MATRIX.md for the full feature matrix.
| Document | Description |
|---|---|
| Getting Started | Tutorial with bundled fixtures |
| Documentation Start | Hand-maintained documentation entry point |
| CLI Reference | Command-line interface documentation |
| Library API | Rust library API reference |
| Error Codes | Error taxonomy (10 families, 61 codes) |
| Support Matrix | COBOL feature coverage |
| Engineering Report | Readiness and current engineering status |
| Design Docs | Feature and design contracts |
| Internal Docs | Internal implementation and spec references |
| Stability Guarantees | API stability contract and versioning policy |
| Support Policy | Release support windows and response times |
| Roadmap | Project status and what's next |
| Code | Tag | Meaning (1-liner) | Test |
|---|---|---|---|
| 2 | CBKD | Data quality failure | exit_code_mapping::exit_code_cbkd_is_2 |
| 3 | CBKE | Encode/validation failure | exit_code_mapping::exit_code_cbke_is_3 |
| 4 | CBKF | Record format/RDW failure | exit_code_mapping::exit_code_cbkf_is_4 |
| 5 | CBKI | Internal orchestration error | exit_code_mapping::exit_code_cbki_is_5 |
# Full validation pipeline
cargo build --workspace --release && cargo test --workspace && cargo clippy --workspace -- -D warnings -W clippy::pedantic && cargo fmt --all --check
# Quick test
cargo test --workspace
# Benchmarks
cargo bench --package copybook-benchSee CONTRIBUTING.md for the full development workflow.
Licensed under AGPL-3.0-or-later. See LICENSE.