Rust toolkit for COBOL copybook parsing and fixed-record data conversion. Deterministic, memory-safe, zero unsafe in public APIs.
Engineering Preview (v0.5.0). Stable CLI and library APIs; feature completeness is preview-level. See ROADMAP.md for adoption guidance and known limitations.
conformance: 9890/9890 • roundtrip: N/A • negative: N/A • skipped: 0 • leaks: 0
Source: CI receipts (nextest/junit). This block is updated automatically.
Install the CLI from crates.io and decode an EBCDIC file to JSON:
cargo install copybook-cli@0.5.0 --locked
# Fetch the example fixtures (or use your own copybook + data)
curl -LO https://github.com/EffortlessMetrics/copybook-rs/raw/v0.5.0/fixtures/copybooks/simple.cpy
curl -LO https://github.com/EffortlessMetrics/copybook-rs/raw/v0.5.0/fixtures/data/simple.bin
# Decode EBCDIC fixture to JSON
copybook decode simple.cpy 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.
For Rust library use, depend on the canonical facade:
[dependencies]
copybook = "=0.5.0"use copybook::core::parse_copybook;
use copybook::codec::{decode_record, DecodeOptions};(copybook-rs is a redirect/search alias for the same API; copybook-core/copybook-codec remain available as intentional granular crates.)
To build from source instead, clone the repo, git checkout v0.5.0, and cargo build --release; the binary is ./target/release/copybook.
- 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, 63 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 |
| API Freeze Audit | Checklist for pre-v1.0 stability freeze completion |
| Roadmap | Project status and what's next |
- Stability contract: see Stability Guarantees
- Freeze rules: see API Freeze
- Support window: see Support Policy
- Freeze audit checklist: see API Freeze Audit
| 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.