# mikefarah/yq architecture

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

- Interactive diagram: https://gitdiagram.com/mikefarah/yq
- Repository: https://github.com/mikefarah/yq

## Overview

##### Main Components

a. Core Processing Components:
- Command Line Interface (cmd/)
- Expression Engine (pkg/yqlib/expression_*.go)
- Operators System (pkg/yqlib/operator_*.go)
- Data Processing Pipeline

b. Input/Output Components:
- Multiple Format Decoders (YAML, JSON, XML, CSV, TOML, Properties)
- Multiple Format Encoders
- File Handling System

c. Evaluation Components:
- Stream Evaluator
- All-at-once Evaluator
- String Evaluator

**[User Input] → [Command Line Interface]**
- ↓
**[Input Files] → [Format Decoders] → [Expression Engine] → [Format Encoders] → [Output]**
- ↑                     ↓                     ↑
- [File Handler]        [Operator System]    [Writer System]
- ↓
- [Evaluation System]

##### Component Relationships

- Double lines: Primary processing path

##### Detailed Component Breakdown

Expression Engine:
**[Expression Parser] → [Lexer] → [Operator Chain] → [Expression Evaluator]**

Format Handling:
**[Input] → [Format Detection] → [Appropriate Decoder] → [Internal Representation]**
- ↓                                                           ↓
**[Output] ← [Format Encoder] ← [Writer] ← [Processed Data]**

##### Additional Elements

- Configuration handling
- Error management
- Documentation generation
- Testing framework integration

##### Technical Details

Technical specifications:
- Go-based implementation
- Portable binary output
- Command-line interface
- Multiple format support

##### Integration Points

Integration with:
- Shell environments
- CI/CD systems (GitHub Actions)
- Container platforms (Docker/Podman)

##### The pipeline-based processing approach

Remember to include version information and any significant architectural changes between major versions, as this helps maintain historical context and understanding of the system's evolution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph CLI["Command Line Interface"]
        CMD["Command Handler"]
        EVAL_ALL["Evaluate All Command"]
        EVAL_SEQ["Evaluate Sequence Command"]
    end

    subgraph INPUT["Input Processing"]
        FH["File Handler"]
        FD["Format Detection"]
        subgraph Decoders["Format Decoders"]
            YAML_D["YAML Decoder"]
            JSON_D["JSON Decoder"]
            XML_D["XML Decoder"]
            CSV_D["CSV Decoder"]
            TOML_D["TOML Decoder"]
            PROP_D["Properties Decoder"]
        end
    end

    subgraph CORE["Core Processing"]
        subgraph EE["Expression Engine"]
            EP["Expression Parser"]
            LEX["Lexer"]
            POST["Postfix Processing"]
        end
        
        subgraph OP["Operators System"]
            OPC["Core Operators"]
        end
        
        subgraph EVAL["Evaluation System"]
            SE["Stream Evaluator"]
            AE["All-at-once Evaluator"]
            STE["String Evaluator"]
        end
        
        DN["Data Navigator"]
        CH["Context Handler"]
        NP["Node Processing"]
    end

    subgraph OUTPUT["Output Processing"]
        WH["Write Handler"]
        subgraph Encoders["Format Encoders"]
            YAML_E["YAML Encoder"]
            JSON_E["JSON Encoder"]
            XML_E["XML Encoder"]
            CSV_E["CSV Encoder"]
            TOML_E["TOML Encoder"]
            PROP_E["Properties Encoder"]
        end
    end

    UI[/"User Input"/] --> CMD
    FILES[/"Input Files"/] --> FH
    
    CMD --> FH
    FH --> FD
    FD --> Decoders
    Decoders --> EE
    EE --> OP
    OP --> EVAL
    EVAL --> DN
    DN --> CH
    CH --> NP
    NP --> Encoders
    Encoders --> WH
    WH --> OUT[/"Output"/]

    %% Click events for component mapping
    click CMD "https://github.com/mikefarah/yq/blob/master/cmd/root.go"
    click EVAL_ALL "https://github.com/mikefarah/yq/blob/master/cmd/evaluate_all_command.go"
    click EVAL_SEQ "https://github.com/mikefarah/yq/blob/master/cmd/evaluate_sequence_command.go"
    click EP "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/expression_parser.go"
    click LEX "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/lexer.go"
    click POST "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/expression_postfix.go"
    click OPC "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/operators.go"
    click YAML_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_yaml.go"
    click JSON_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_json.go"
    click XML_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_xml.go"
    click CSV_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_csv_object.go"
    click TOML_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_toml.go"
    click PROP_D "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/decoder_properties.go"
    click YAML_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_yaml.go"
    click JSON_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_json.go"
    click XML_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_xml.go"
    click CSV_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_csv.go"
    click TOML_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_toml.go"
    click PROP_E "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/encoder_properties.go"
    click SE "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/stream_evaluator.go"
    click AE "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/all_at_once_evaluator.go"
    click STE "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/string_evaluator.go"
    click FH "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/file_utils.go"
    click WH "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/write_in_place_handler.go"
    click DN "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/data_tree_navigator.go"
    click CH "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/context.go"
    click NP "https://github.com/mikefarah/yq/blob/master/pkg/yqlib/candidate_node.go"

    classDef default fill:#fff,stroke:#333,stroke-width:2px;
    classDef input fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;
    classDef core fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
    classDef output fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
    classDef cli fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;

    class CLI,CMD,EVAL_ALL,EVAL_SEQ cli;
    class INPUT,FH,FD,Decoders,YAML_D,JSON_D,XML_D,CSV_D,TOML_D,PROP_D input;
    class CORE,EE,EP,LEX,POST,OP,OPC,EVAL,SE,AE,STE,DN,CH,NP core;
    class OUTPUT,WH,Encoders,YAML_E,JSON_E,XML_E,CSV_E,TOML_E,PROP_E output;
```
