# matthewplemmons/hls architecture

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

- Interactive diagram: https://gitdiagram.com/matthewplemmons/hls
- Repository: https://github.com/matthewplemmons/hls

## Overview

This repository is a small C implementation of `ls`. Its main workflow parses options and directory arguments, enumerates entries according to hidden-file rules, then prints names or long metadata. The README documents `-l`, `-1`, `-a`, and `-A`; long output formats permissions, ownership, size, and timestamps. Shared allocation, string, and error helpers support those stages. Sorting is declared but commented out in the sampled runtime. Relationships below are limited to calls visible in the excerpts; the filesystem is an external dependency.

Main entry points: [`hls.c`](https://github.com/matthewplemmons/hls/blob/master/hls.c) (Program entry and directory traversal), [`hls-arg-parse.c`](https://github.com/matthewplemmons/hls/blob/master/hls-arg-parse.c) (Option and path parsing), [`hls-print.c`](https://github.com/matthewplemmons/hls/blob/master/hls-print.c) (Name and long output), [`hls-calloc.c`](https://github.com/matthewplemmons/hls/blob/master/hls-calloc.c) (Zeroed allocation and cleanup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and traversal"]
  node_entry["Program entry and directory traversal<br/>[hls.c]"]
  node_arguments["Option and path parsing<br/>[hls-arg-parse.c]"]
end

subgraph group_listing["Directory listing"]
  node_count["Visible entry counting<br/>[hls.c]"]
  node_collection["Filename collection"]
end

subgraph group_output["Formatting and output"]
  node_printing["Name and long output<br/>[hls-print.c]"]
  node_date["Timestamp formatting<br/>[hls-dateformat.c]"]
end

subgraph group_support["Runtime support"]
  node_errors["Directory error reporting<br/>[hls-error.c]"]
  node_allocation["Zeroed allocation and cleanup<br/>[hls-calloc.c]"]
  node_strings["String operations<br/>[hls-strings.c]"]
end

node_user(("CLI user"))
node_filesystem[("Filesystem")]

node_user -->|"runs"| node_entry
node_entry -->|"parses options"| node_arguments
node_entry -->|"extracts paths"| node_arguments
node_arguments -->|"validates directories"| node_filesystem
node_arguments -->|"reports failures"| node_errors
node_entry -->|"counts entries"| node_count
node_count -->|"reads directory"| node_filesystem
node_entry -->|"collects names"| node_collection
node_collection -->|"reads directory"| node_filesystem
node_entry -->|"prints listing"| node_printing
node_printing -->|"reads metadata"| node_filesystem
node_printing -->|"formats timestamp"| node_date
node_arguments -->|"allocates paths"| node_allocation
node_arguments -->|"builds paths"| node_strings
node_collection -->|"allocates names"| node_allocation
node_collection -->|"copies names"| node_strings
node_printing -->|"allocates full path"| node_allocation
node_printing -->|"builds full path"| node_strings
node_date -->|"allocates result"| node_allocation
node_date -->|"rewrites timestamp"| node_strings
node_errors -->|"allocates message"| node_allocation
node_errors -->|"builds message"| node_strings

click node_entry "https://github.com/matthewplemmons/hls/blob/master/hls.c"
click node_arguments "https://github.com/matthewplemmons/hls/blob/master/hls-arg-parse.c"
click node_count "https://github.com/matthewplemmons/hls/blob/master/hls.c"
click node_collection "https://github.com/matthewplemmons/hls/blob/master/collect-filenames.c"
click node_printing "https://github.com/matthewplemmons/hls/blob/master/hls-print.c"
click node_date "https://github.com/matthewplemmons/hls/blob/master/hls-dateformat.c"
click node_errors "https://github.com/matthewplemmons/hls/blob/master/hls-error.c"
click node_allocation "https://github.com/matthewplemmons/hls/blob/master/hls-calloc.c"
click node_strings "https://github.com/matthewplemmons/hls/blob/master/hls-strings.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_arguments,node_user toneBlue
class node_count,node_collection,node_filesystem toneAmber
class node_printing,node_date toneMint
class node_errors,node_allocation,node_strings toneRose
```

## Components

### CLI and traversal

- [Program entry and directory traversal](https://github.com/matthewplemmons/hls/blob/master/hls.c): `hls.c`
- [Option and path parsing](https://github.com/matthewplemmons/hls/blob/master/hls-arg-parse.c): `hls-arg-parse.c`

### Directory listing

- [Visible entry counting](https://github.com/matthewplemmons/hls/blob/master/hls.c): `hls.c`
- [Filename collection](https://github.com/matthewplemmons/hls/blob/master/collect-filenames.c): `collect-filenames.c`

### Formatting and output

- [Name and long output](https://github.com/matthewplemmons/hls/blob/master/hls-print.c): `hls-print.c`
- [Timestamp formatting](https://github.com/matthewplemmons/hls/blob/master/hls-dateformat.c): `hls-dateformat.c`

### Runtime support

- [Directory error reporting](https://github.com/matthewplemmons/hls/blob/master/hls-error.c): `hls-error.c`
- [Zeroed allocation and cleanup](https://github.com/matthewplemmons/hls/blob/master/hls-calloc.c): `hls-calloc.c`
- [String operations](https://github.com/matthewplemmons/hls/blob/master/hls-strings.c): `hls-strings.c`

### Other components

- **CLI user**
- **Filesystem**

## Connections

- CLI user → Program entry and directory traversal: runs (evidence: `README.md`)
- Program entry and directory traversal → Option and path parsing: parses options (evidence: `hls.c`)
- Program entry and directory traversal → Option and path parsing: extracts paths (evidence: `hls.c`)
- Option and path parsing → Filesystem: validates directories (evidence: `hls-arg-parse.c`)
- Option and path parsing → Directory error reporting: reports failures (evidence: `hls-arg-parse.c`)
- Program entry and directory traversal → Visible entry counting: counts entries (evidence: `hls.c`)
- Visible entry counting → Filesystem: reads directory (evidence: `hls.c`)
- Program entry and directory traversal → Filename collection: collects names (evidence: `hls.c`)
- Filename collection → Filesystem: reads directory (evidence: `collect-filenames.c`)
- Program entry and directory traversal → Name and long output: prints listing (evidence: `hls.c`)
- Name and long output → Filesystem: reads metadata (evidence: `hls-print.c`)
- Name and long output → Timestamp formatting: formats timestamp (evidence: `hls-print.c`)
- Option and path parsing → Zeroed allocation and cleanup: allocates paths (evidence: `hls-arg-parse.c`)
- Option and path parsing → String operations: builds paths (evidence: `hls-arg-parse.c`)
- Filename collection → Zeroed allocation and cleanup: allocates names (evidence: `collect-filenames.c`)
- Filename collection → String operations: copies names (evidence: `collect-filenames.c`)
- Name and long output → Zeroed allocation and cleanup: allocates full path (evidence: `hls-print.c`)
- Name and long output → String operations: builds full path (evidence: `hls-print.c`)
- Timestamp formatting → Zeroed allocation and cleanup: allocates result (evidence: `hls-dateformat.c`)
- Timestamp formatting → String operations: rewrites timestamp (evidence: `hls-dateformat.c`)
- Directory error reporting → Zeroed allocation and cleanup: allocates message (evidence: `hls-error.c`)
- Directory error reporting → String operations: builds message (evidence: `hls-error.c`)
