# errornointernet/hsize architecture

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

- Interactive diagram: https://gitdiagram.com/errornointernet/hsize
- Repository: https://github.com/errornointernet/hsize

## Overview

##### Project type and purpose
- hsize is a Rust-based open-source command-line utility (with a library API) for converting file sizes to and from human-readable units and for “replace” operations using regex.
- It ships as a single binary (`hsize`) with several subcommands (`replace`, `generate`, etc.), plus a reusable core library for integration into other Rust programs.

##### File structure
- Top-level:
– Cargo.toml/Cargo.lock: Rust package definition
– default.nix/flake.nix: Nix packaging
– .github/workflows: CI pipelines (build, lint, generate manpages/completions)
– completions/: static shell-completion scripts
– man/: prewritten manpages
- src/:
– main.rs: CLI entry point
– lib.rs: public library interface
– arguments.rs: command-line parsing definitions (Clap)
– cli/: subcommand handlers (e.g. replace.rs)
– format.rs: formatting logic, Options struct
– unit.rs: unit and scale definitions
– replace.rs: regex search-and-replace implementation

##### Extract insights from the README
- Primary features: convert numeric inputs (args or stdin) to human-readable units (--binary, precision, suffix toggles), and perform regex-driven in-text replacements.
- Subcommands generate shell completions and manpages, showing a dual focus on UX and documentation.
- Exposes a public API (Converter, Options, Scale, Unit) for library consumers.

##### Components
a. Main Components:
1. CLI Layer
- Argument Parser (Clap)
- Command Dispatcher (default vs. replace vs. generate)
2. Core Library
- Converter (convert, format, format_with_options)
- Unit & Scale Definitions
- Formatting Engine (Options, separators, precision)
- Replace Module (uses regex crate)
3. I/O
- stdin/stdout interface
- Shell completion files (completions/ directory)
- Manpage files (man/ directory)
4. Build & CI
- Cargo build/test pipelines (.github/workflows)
- Nix flakes

b. Relationships & Data Flow:
– User invokes `hsize` → CLI Layer
– CLI Layer → Argument Parser → Command Dispatcher
– If “convert” (default): pass values to Converter → Formatting Engine → stdout
– If “replace”: feed stdin text → Replace Module (regex matching + Converter) → stdout
– If “generate” subcommands: Comparator reads definitions → emits Bash/Fish/Zsh scripts or manpages into completions/ or man/
– CI pipelines trigger generation and validate outputs

c. Architectural Patterns & Principles:
– Separation of concerns: CLI parsing, core conversion logic, and replace logic are modular.
– Reusable library core (lib.rs) leveraged by both the binary and external consumers.
– Declarative CLI definitions (Clap) enable automatic generation of completions and documentation.
– Single-process, in-process routing of subcommands.

d. Key Technologies & Libraries:
– Rust & Cargo
– Clap (argument parsing, subcommand support, completion generation)
– regex crate (pattern matching in replace)
– Nix (packaging)
– GitHub Actions (CI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        Entry["CLI Entry\n(main.rs)"]:::cli
        Parser["Argument Parser\n(arguments.rs)"]:::cli
        Dispatcher["Command Dispatcher\n(cli/mod.rs)"]:::cli
        ReplaceHandler["Replace Subcommand\n(cli/replace.rs)"]:::cli
    end

    subgraph "Core Library"
        LibBoundary["Library Boundary\n(lib.rs)"]:::core
        Converter["Converter & Formatting Engine\n(format.rs)"]:::core
        UnitScale["Unit & Scale Definitions\n(unit.rs)"]:::core
        ReplaceCore["Replace Module\n(replace.rs)"]:::core
    end

    subgraph "I/O & Docs"
        StdIO["stdin/stdout"]:::io
        Completions["Shell Completions\n(completions/)"]:::io
        Manpages["Manpages\n(man/)"]:::io
    end

    subgraph "CI & Packaging"
        CI["CI Pipelines\n(.github/workflows/)"]:::ci
        Nix["Nix Packaging\n(default.nix, flake.nix)"]:::ci
    end

    User["User"] --> Entry
    Entry --> Parser
    Parser --> Dispatcher
    Dispatcher -->|"convert (default)"| Converter
    Converter --> UnitScale
    Converter --> StdIO
    Dispatcher -->|"replace"| ReplaceHandler
    ReplaceHandler --> ReplaceCore
    ReplaceCore --> Converter
    ReplaceCore --> StdIO
    Dispatcher -->|"generate"| LibBoundary
    LibBoundary --> Completions
    LibBoundary --> Manpages
    CI --> Entry
    CI --> Completions
    CI --> Manpages
    CI --> Nix

    click Entry "https://github.com/errornointernet/hsize/blob/main/src/main.rs"
    click Parser "https://github.com/errornointernet/hsize/blob/main/src/arguments.rs"
    click Dispatcher "https://github.com/errornointernet/hsize/blob/main/src/cli/mod.rs"
    click ReplaceHandler "https://github.com/errornointernet/hsize/blob/main/src/cli/replace.rs"
    click LibBoundary "https://github.com/errornointernet/hsize/blob/main/src/lib.rs"
    click Converter "https://github.com/errornointernet/hsize/blob/main/src/format.rs"
    click UnitScale "https://github.com/errornointernet/hsize/blob/main/src/unit.rs"
    click ReplaceCore "https://github.com/errornointernet/hsize/blob/main/src/replace.rs"
    click Completions "https://github.com/errornointernet/hsize/tree/main/completions/"
    click Manpages "https://github.com/errornointernet/hsize/tree/main/man/"
    click CI "https://github.com/errornointernet/hsize/blob/main/.github/workflows/build.yaml"
    click Nix "https://github.com/errornointernet/hsize/blob/main/default.nix"

    classDef cli fill:#fef,stroke:#333,stroke-width:1px
    classDef core fill:#eef,stroke:#333,stroke-width:1px
    classDef io fill:#efe,stroke:#333,stroke-width:1px
    classDef ci fill:#ffe,stroke:#333,stroke-width:1px
```
