# rust-bakery/nom architecture

> Architecture diagram of the GitHub repository rust-bakery/nom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rust-bakery/nom
- Repository: https://github.com/rust-bakery/nom

## Overview

##### Main Components

a) Core Parser Engine
- Main parsing traits and types from src/traits.rs
- To the error handling system (src/error.rs)

b) Parser Combinators Groups (organize as modules radiating from the core):
- Bytes (src/bytes/) - For byte-level parsing
- Characters (src/character/) - For character/string parsing
- Numbers (src/number/) - For numeric parsing
- Bits (src/bits/) - For bit-level parsing
- Sequences (src/sequence/) - For combining parsers
- Branches (src/branch/) - For alternative parsing paths
- Multi (src/multi/) - For repetition and collection
- Combinators (src/combinator/) - For parser transformations

##### Data Flow Architecture
Following flows:

**Input Data → Parser Combinators → Parsing Result**
- ↓
- Error Handling

##### Component Relationships

- How each parser module connects to the core engine
- Two main parsing modes: "complete" and "streaming"
- Demonstrate error propagation paths
- How combinators can be composed

##### Special Features Layer
- Zero-copy parsing capabilities
- Streaming support
- Custom error handling
- Bit-level parsing
- Debug/trace capabilities

##### Implementation Details

Technical aspects:
- Input type abstraction (showing support for &[u8], &str, custom types)
- Error type system
- Parser trait implementation flow
- Memory management model (zero-copy architecture)

##### Integration Points

Integration capabilities with:
- Custom input types
- External error handling
- Streaming parsers
- Test frameworks

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        L1[Core Component]:::core
        L2[Parser Module]:::parser
        L3[/Input/Output/]:::io
        L4{Decision Point}:::decision
        L5[[Error Handling]]:::error
        style Legend fill:#f0f0f0,stroke:#333
    end

    subgraph Core["Core Parser Engine"]
        Traits["Parser Traits"]:::core
        click Traits "https://github.com/rust-bakery/nom/blob/main/src/traits.rs"
        Error["Error System"]:::error
        click Error "https://github.com/rust-bakery/nom/blob/main/src/error.rs"
        Internal["Internal Utils"]:::core
        click Internal "https://github.com/rust-bakery/nom/blob/main/src/internal.rs"
        Macros["Macro System"]:::core
        click Macros "https://github.com/rust-bakery/nom/blob/main/src/macros.rs"
    end

    subgraph Combinators["Parser Combinators"]
        Bytes["Bytes Parsing"]:::parser
        click Bytes "https://github.com/rust-bakery/nom/tree/main/src/bytes/"
        Chars["Character Parsing"]:::parser
        click Chars "https://github.com/rust-bakery/nom/tree/main/src/character/"
        Numbers["Number Parsing"]:::parser
        click Numbers "https://github.com/rust-bakery/nom/tree/main/src/number/"
        Bits["Bit-level Parsing"]:::parser
        click Bits "https://github.com/rust-bakery/nom/tree/main/src/bits/"
        Sequences["Sequence Parsing"]:::parser
        click Sequences "https://github.com/rust-bakery/nom/tree/main/src/sequence/"
        Branches["Branch Operations"]:::parser
        click Branches "https://github.com/rust-bakery/nom/tree/main/src/branch/"
        Multi["Multi/Repetition"]:::parser
        click Multi "https://github.com/rust-bakery/nom/tree/main/src/multi/"
        Transform["Combinators"]:::parser
        click Transform "https://github.com/rust-bakery/nom/tree/main/src/combinator/"
    end

    subgraph Modes["Parsing Modes"]
        Complete["Complete Parsing"]:::mode
        Streaming["Streaming Parsing"]:::mode
        
        BytesComplete["Bytes Complete"]:::parser
        click BytesComplete "https://github.com/rust-bakery/nom/blob/main/src/bytes/complete.rs"
        BytesStream["Bytes Streaming"]:::parser
        click BytesStream "https://github.com/rust-bakery/nom/blob/main/src/bytes/streaming.rs"
        
        CharsComplete["Chars Complete"]:::parser
        click CharsComplete "https://github.com/rust-bakery/nom/blob/main/src/character/complete.rs"
        CharsStream["Chars Streaming"]:::parser
        click CharsStream "https://github.com/rust-bakery/nom/blob/main/src/character/streaming.rs"
        
        NumComplete["Numbers Complete"]:::parser
        click NumComplete "https://github.com/rust-bakery/nom/blob/main/src/number/complete.rs"
        NumStream["Numbers Streaming"]:::parser
        click NumStream "https://github.com/rust-bakery/nom/blob/main/src/number/streaming.rs"
        
        BitsComplete["Bits Complete"]:::parser
        click BitsComplete "https://github.com/rust-bakery/nom/blob/main/src/bits/complete.rs"
        BitsStream["Bits Streaming"]:::parser
        click BitsStream "https://github.com/rust-bakery/nom/blob/main/src/bits/streaming.rs"
    end

    subgraph Features["Special Features"]
        ZeroCopy["Zero-Copy Parsing"]:::feature
        CustomError["Custom Error Types"]:::feature
        Debug["Debug/Trace"]:::feature
        StringOps["String Operations"]:::feature
        click StringOps "https://github.com/rust-bakery/nom/blob/main/src/str.rs"
    end

    Input[/"Input Data"/]:::io --> Core
    Core --> Combinators
    Combinators --> Modes
    Error --> CustomError
    Modes --> Output[/"Parsing Result"/]:::io
    
    Complete --> BytesComplete & CharsComplete & NumComplete & BitsComplete
    Streaming --> BytesStream & CharsStream & NumStream & BitsStream

    classDef core fill:#a8d1f0,stroke:#333
    classDef parser fill:#90EE90,stroke:#333
    classDef io fill:#FFE4B5,stroke:#333
    classDef decision fill:#FFD700,stroke:#333
    classDef error fill:#FFB6C1,stroke:#333
    classDef mode fill:#DDA0DD,stroke:#333
    classDef feature fill:#98FB98,stroke:#333
```
