# p-gen/smenu architecture

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

- Interactive diagram: https://gitdiagram.com/p-gen/smenu
- Repository: https://github.com/p-gen/smenu

## Overview

The project “smenu” is a command-line, terminal-based selection filter tool written in C. It reads words (or tokens) from standard input or from a file and then displays them in a scrolling window on the terminal. The tool makes use of a modular design within a single executable that leverages multiple source files (e.g., smenu.c, list.c, utils.c, utf8.c) along with additional libraries (like “ctxopt” for handling options). The project employs the autotools build system, evident from files such as configure.ac, Makefile.am, and many configuration scripts in the build-aux directory. There are also many examples and a comprehensive testing suite to verify its behavior on different terminals and encodings (including UTF-8).

##### Main Components
- Input/Parsing Module:
- This component is responsible for reading data from STDIN or from files. In the source, files such as fgetc.c, fgetc.h, and usage.c illustrate aspects of input handling.
- Option Management and Configuration:
- The project uses a subsystem called “ctxopt” for processing and managing command-line arguments and configurations. This component connects to the main execution flow early.
- Core Logic / UI Engine:
- This is the heart of the tool. The source files such as smenu.c and management files like list.c, safe.c, and utils.c provide the logic to build the interactive menu, handle scrolling, and react to keyboard/mouse interaction. The handling of different layouts (simple_menu, lvm_menu, yesno) is shown in the examples directory.
- Terminal Display / Rendering:
- Although not a separate library, the code deals with terminal-specific features (leveraging the terminfo database). The UI engine interacts directly with the terminal for drawing the selection window and managing the cursor.
- Utility Libraries:
- Support modules like xmalloc, utf8, and various helper functions (e.g., for list management) underpin the core functionality.
- Testing and Examples:
- A comprehensive testing suite (located under the tests directory) and an array of example usage scripts provide regression testing and demonstrate different use cases. Even though these aren’t part of the runtime flow, they form an essential layer for ensuring system reliability.

##### Relationships and Interactions
- Data Flow:
- The user (or external process) provides input which is handled by the Input/Parsing Module.
- Command-line arguments are parsed by the Option Management component (using ctxopt) prior to invoking the core logic.
- The Core Logic / UI Engine uses utility functions to process the data, then orchestrates the rendering of an interactive selection menu to the terminal display.
- User interaction with the terminal (keyboard and/or mouse) is processed back by the UI engine, thus leading to an output selection.
- Build & Configuration:
- The build system (configure, Makefile scripts) plays the role of tying together the various modules and ensuring dependencies are met. This aspect can be drawn as external tooling that “builds” the executable which contains all the components.

##### Architectural Patterns and Design Principles
- Modular Design:
- Although the application is a single executable, the code base is broken into logically separate components (input management, UI rendering, option processing, utilities).
- Separation of Concerns:
- The separation between terminal input handling, display logic, and command-line configuration helps isolate functionality and eases testing.
- Reusability and Extensibility:
- The examples and tests directory demonstrate that the design fosters ease-of-extension so that various terminal behaviors and configurations can be tested outside of the core logic.

##### Including Relevant Technologies
- Programming Language: C
- Build Tools: GNU Autotools (configure.ac, Makefile.am, etc.)
- Option/Configuration Libraries: ctxopt
- Terminal Handling: Based on terminfo, supporting UTF-8 (with handling for double-width characters and potentially extended grapheme clusters)
- Testing Frameworks: Custom scripts in the tests directory for running functional tests across different input cases.

##### Detail and Granularity
- Every major component (like “ctxopt,” “UTF-8 support,” “terminal rendering,” and “input parsing”) is labeled clearly.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Subgraphs
    subgraph "User Terminal"
        UT("User Terminal"):::interface
    end

    subgraph "Input & Option Handling"
        IP("Input/Parsing Module"):::component
        OM("Option Management (ctxopt)"):::component
    end

    subgraph "Core Engine"
        CE("Core UI Engine"):::component
    end

    subgraph "Supporting Libraries"
        UL("Utility Libraries"):::library
    end

    subgraph "External Tools"
        BC("Build & Configuration"):::external
        TE("Testing & Examples"):::external
    end

    %% Connections
    UT -->|"provides_input"| IP
    UT -->|"sends_options"| OM
    IP -->|"parsed_tokens"| CE
    OM -->|"parsed_options"| CE
    CE -->|"renders_output"| UT
    UL -->|"supports"| CE
    BC -->|"builds"| IP
    BC -->|"builds"| OM
    BC -->|"builds"| CE
    TE -->|"validates"| IP
    TE -->|"validates"| OM
    TE -->|"validates"| CE
    TE -->|"validates"| UL

    %% Click Events for Input/Parsing Module
    click IP "https://github.com/p-gen/smenu/blob/master/fgetc.c"
    click IP "https://github.com/p-gen/smenu/blob/master/fgetc.h"
    click IP "https://github.com/p-gen/smenu/blob/master/usage.c"
    click IP "https://github.com/p-gen/smenu/blob/master/usage.h"

    %% Click Events for Option Management
    click OM "https://github.com/p-gen/smenu/blob/master/ctxopt.c"
    click OM "https://github.com/p-gen/smenu/blob/master/ctxopt.h"

    %% Click Events for Core UI Engine
    click CE "https://github.com/p-gen/smenu/blob/master/smenu.c"
    click CE "https://github.com/p-gen/smenu/blob/master/smenu.h"
    click CE "https://github.com/p-gen/smenu/blob/master/list.c"
    click CE "https://github.com/p-gen/smenu/blob/master/list.h"
    click CE "https://github.com/p-gen/smenu/blob/master/safe.c"
    click CE "https://github.com/p-gen/smenu/blob/master/safe.h"
    click CE "https://github.com/p-gen/smenu/blob/master/utils.c"
    click CE "https://github.com/p-gen/smenu/blob/master/utils.h"

    %% Click Events for Utility Libraries
    click UL "https://github.com/p-gen/smenu/blob/master/utf8.c"
    click UL "https://github.com/p-gen/smenu/blob/master/utf8.h"
    click UL "https://github.com/p-gen/smenu/blob/master/xmalloc.c"
    click UL "https://github.com/p-gen/smenu/blob/master/xmalloc.h"

    %% Click Events for Build & Configuration
    click BC "https://github.com/p-gen/smenu/blob/master/configure.ac"
    click BC "https://github.com/p-gen/smenu/blob/master/Makefile.am"
    click BC "https://github.com/p-gen/smenu/tree/master/build-aux"

    %% Click Events for Testing & Examples
    click TE "https://github.com/p-gen/smenu/tree/master/tests"
    click TE "https://github.com/p-gen/smenu/tree/master/examples"

    %% Styles
    classDef interface fill:#ffdddd,stroke:#a83232,stroke-width:2px;
    classDef component fill:#ddffdd,stroke:#32a852,stroke-width:2px;
    classDef library fill:#ddddff,stroke:#3232a8,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#a8a832,stroke-width:2px;
```
