How headwayio/edi works
Project type and purpose
• This is a Rust library (“crate”) named edi that provides parsing of X12 EDI documents into in‐memory Rust structs.
• Key use cases: strict or loose parsing of EDI text streams, rich error reporting, and serde‐compatible serialization/deserialization.
File structure
• Top‐level files:
• Cargo.toml, LICENSE.md, README.md, .gitignore, CI config
• src/ modules:
• tokenizer.rs – breaks raw input into tokens (elements, segments)
• edi_document.rs, interchange_control.rs, functional_group.rs, transaction.rs, generic_segment.rs – data‐model definitions
• edi_parse_error.rs – error types and verbose error reporting
• lib.rs – public API (parse and loose_parse) + module re-exports
• resources/schemas.csv – optional metadata (schemas) for future validation
• examples/ – usage samples of API
• tests/ – unit and validation tests
README for additional insights
• Two parser entry points: parse (strict) and loose_parse (lenient)
• Output type: EdiDocument that implements Serialize/Deserialize via serde
• Limitations: only standard X12, no transaction‐specific schemas, no loop detection
Main components
a. Input layer
• Raw EDI text file/stream (e.g., sample_edi.txt in examples)
b. Tokenizer
• Reads raw text → produces tokens (segment separators, element data)
c. Parser
• Two entry functions (parse, loose_parse)
• Drives state machine across tokens to build hierarchical structs
d. Data Model
• EdiDocument – root container
• InterchangeControl – envelopes
• FunctionalGroup – groups of transactions
• Transaction – individual transaction sets
• GenericSegment – a catch‐all segment representation
e. Error Handling
• EdiParseError – rich error type carrying segment context
f. Serialization/Deserialization
• serde integration for converting EdiDocument to/from JSON, etc.
g. Resources (optional)
• schemas.csv for future mapping/schema validation
Relationships and interactions
• Raw input feeds into the Tokenizer
• Tokenizer outputs a stream of tokens for the Parser
• Parser functions orchestrate token consumption to instantiate Data Model objects
• On parse failure, Parser returns EdiParseError with context
• On success, EdiDocument is returned and can be serialized via serde
• Example code and tests drive both Tokenizer and Parser to validate functionality
Architectural patterns and design principles
• Single Responsibility: tokenizer, parser, data model, and error handling are decoupled modules
• Functional style: pure functions parse/loose_parse return a Result wrapping either a model or an error
• Extensibility: public data model with pub fields, resources file for future schema support
• Zero-copy serde serialization for performance