Crate copybook_core 

Core parsing and schema types for COBOL copybooks

This crate provides the fundamental types and parsing logic for COBOL copybook processing, including AST construction, layout resolution, and schema validation.

Key Features

Enhanced COBOL Support

• Level-88 Condition Values: Full support for condition name definitions with VALUE clauses
• Binary Width Syntax: Support for explicit BINARY(n) width specifications
• Comprehensive Numeric Types: Full parsing of zoned, packed, and binary field definitions
• Recursion Limits: Parser protection against deeply nested or malformed copybooks
• Error Context: Detailed error reporting with field paths and source locations

Schema Generation

• Field Hierarchy: Complete representation of COBOL data structures with Level-88 conditions
• Layout Resolution: Accurate byte offset and size calculations
• Structural Validation: Comprehensive checks for ODO positioning, Level-88 placement, REDEFINES compatibility

Parser Improvements

• Robustness: Enhanced handling of edge cases and malformed input
• Performance: Efficient parsing with minimal memory allocation
• Standards Compliance: Adherence to COBOL copybook syntax standards
• Safety: Zero unsafe code with comprehensive validation

Usage Example

use copybook_core::{parse_copybook, parse_copybook_with_options, ParseOptions, FieldKind};

// Parse a copybook with Level-88 condition values
let copybook_text = r#"
       01  CUSTOMER-RECORD.
           05  CUSTOMER-STATUS     PIC X(1).
               88  STATUS-ACTIVE   VALUE 'A'.
               88  STATUS-INACTIVE VALUE 'I'.
               88  STATUS-PENDING  VALUE 'P'.
           05  CUSTOMER-ID         PIC 9(6).
           05  ORDER-COUNT         PIC 9(3).
           05  ORDERS OCCURS 1 TO 100 TIMES
                   DEPENDING ON ORDER-COUNT.
               10  ORDER-ID        PIC 9(8).
               88  RUSH-ORDER      VALUE 99999999.
"#;

// Parse with default options and handle any errors gracefully
let schema_default = match parse_copybook(copybook_text) {
    Ok(schema) => schema,
    Err(error) => {
        eprintln!("Failed to parse copybook: {error}");
        return;
    }
};
println!(
    "Default parsing produced {} top-level fields",
    schema_default.fields.len()
);

// Parse with custom options for enhanced validation
let options = ParseOptions {
    allow_inline_comments: true,
    strict: true,
    ..Default::default()
};
let schema_strict = match parse_copybook_with_options(copybook_text, &options) {
    Ok(schema) => schema,
    Err(error) => {
        eprintln!("Strict parsing failed: {error}");
        return;
    }
};

// Examine the parsed schema including Level-88 conditions
for field in &schema_strict.fields {
    match &field.kind {
        FieldKind::Condition { values } => {
            println!("Level-88 condition '{}' with values: {:?}", field.name, values);
        }
        FieldKind::Group => {
            println!("Group field: {}", field.name);
        }
        _ => {
            println!(
                "Data field: {} (offset: {}, size: {})",
                field.name, field.offset, field.len
            );
        }
    }
}

Re-exports

pub use parser::ParseOptions;

pub use projection::project_schema;

pub use schema::Field;

pub use schema::FieldKind;

pub use schema::Occurs;

pub use schema::Schema;

pub use schema::SignPlacement;

pub use schema::SignSeparateInfo;

pub use schema::TailODO;

Modules

audit

No-op audit stubs for performance-critical builds

dialect

Dialect contract for ODO min_count semantics (Normative, ZeroTolerant, OneTolerant). Backward-compatible re-export for dialect APIs now hosted in copybook-dialect.

error

Re-export of all error types from copybook_error.

error_reporter

Structured error reporting with severity levels and summary statistics. Structured error reporting re-exports.

feature_flags

Compile-time and runtime feature flag governance. Feature flag API surface re-exported from the governance contracts façade.

layout

Layout resolution: byte offsets, REDEFINES, and OCCURS DEPENDING ON. Layout resolution and field offset calculation

lexer

Lexical analysis of COBOL copybook source text. COBOL copybook lexer shim.

parser

Recursive-descent parser producing the Schema AST from tokens. COBOL copybook parser

pic

PICTURE clause analysis and field-size computation. PIC clause parsing and validation for COBOL data types

projection

Field projection for selective decode/encode (--select). Field projection for copybook schemas

safe_ops

Utility functions for panic-safe operations

schema

Core schema types: Schema, Field, FieldKind, and related structures. Schema types for COBOL copybook structures

support_matrix

COBOL feature support matrix and status registry. Support matrix API surface re-exported from the governance contracts façade.

utils

Shared utility functions and extension traits. Panic-safe utility functions and extension traits

Structs

Error

Main error type for copybook operations

ErrorContext

Context information for detailed error reporting

ErrorReport

Detailed error report with context and metadata

ErrorReporter

Structured error reporter with configurable handling

ErrorSummary

Comprehensive error statistics and summary

FeatureFlags

Feature flag configuration.

FeatureFlagsHandle

Thread-safe, mutable handle to FeatureFlags for runtime toggling.

Enums

Dialect

Dialect for ODO min_count interpretation

ErrorCode

Stable error codes for programmatic error handling

ErrorMode

Error handling mode configuration

ErrorSeverity

Error severity levels

Feature

All available feature flags.

FeatureCategory

Feature category for grouping related features.

Traits

OptionExt

Extension trait for Option<T> providing panic-safe unwrapping with context

SliceExt

Extension trait for slice indexing providing panic-safe access

VecExt

Extension trait for Vec<T> providing panic-safe access operations

Functions

all_features

Return a list of every defined Feature variant.

parse_copybook

Parse a COBOL copybook into a structured schema

parse_copybook_with_options

Parse a COBOL copybook with specific options

Type Aliases

Result

Result type alias for copybook operations