rexx-address-book/analysis.md

Project Analysis: rexx-address-book

Tech Stack & Layout

• Object Rexx serves as the core language, blending procedural scripting with OOP for modular, extensible code; key extensions include Unix for system interactions (e.g., file handling, environment vars), SQLite for lightweight persistent storage, and ncurses for building a terminal-based UI (TUI); configuration uses JSON for flexibility, chosen to leverage Rexx's strengths in scripting while adding modern data and UI capabilities without heavy dependencies.
• High-level directory structure includes app/ for core application modules and classes (e.g., database and UI logic), db/ for database-related scripts or schemas (though integrated into app/ in this setup), tests/ for unit tests (e.g., database functionality), addrbook.rex as the main entry point script, install.rex for setup and configuration, and default-config.json for default settings like DB paths and UI themes, ensuring easy customization and portability.

Module & Function Relationships

• The main script addrbook.rex acts as the orchestrator, loading classes from app/ and invoking install.rex for initial setup; install.rex handles environment checks, DB initialization, and config loading to prepare the app for runtime.
• The SQLite backend (via app/appdb.cls) manages data persistence for contacts, while the ncurses frontend (via app/appui.cls) handles user interactions like menus and forms, separating concerns for maintainability.
• Configuration in default-config.json ties pieces together by defining paths (e.g., DB file), UI settings (e.g., colors), and defaults, which are parsed in install.rex and propagated to classes in app/ for a unified, configurable experience.

Function & Method Reference

addrbook.rex (Main Entry Point)

• main(): Orchestrates app startup by loading configs, initializing DB and UI objects, and entering the main event loop; uses ::requires to import classes, creates instances like AppDB and AppUI, and calls UI methods for user interaction; exists to centralize control flow, promoting a clean separation between setup and runtime.
• handleExit(): Cleans up resources like closing DB connections and ncurses sessions on exit; employs Object Rexx's guard off for safe object destruction and Unix extensions for any file cleanup; designed for graceful shutdown, ensuring data integrity and resource management.

install.rex (Setup Script)

• install(): Checks system dependencies, parses default-config.json using Rexx stems for JSON data, sets up SQLite DB schema if needed; leverages Unix extensions for path validation and file creation; exists to make the app portable and user-friendly, handling one-time setup without cluttering the main script.
• configLoad(): Reads and validates JSON config into a Rexx directory object; uses classic Rexx parsing with stems to convert JSON to accessible structures; rationale is to enable dynamic configuration, allowing easy tweaks without code changes.

app/appdb.cls (Database Class)

• init(): Initializes SQLite connection using extension calls like sqlite_open; sets up stems for contact records (e.g., contacts.name, contacts.email); uses Object Rexx classes for encapsulation, ensuring DB ops are object-oriented; exists to abstract storage, separating data logic from UI.
• addContact(): Inserts a new contact via SQLite execute with parameterized queries to prevent injection; maps input stems to SQL, handles transactions; designed for safety and efficiency, demonstrating Rexx's stem usage for flexible data handling.
• queryContacts(): Retrieves contacts with SQL select, populates Rexx arrays or stems; integrates SQLite results into objects; rationale is query optimization and easy data flow to UI, using OOP methods for reusability.

app/appui.cls (UI Class)

• init(): Starts ncurses session with initscr() and sets up windows/menus; uses Object Rexx methods to manage UI state objects; exists to encapsulate TUI logic, leveraging ncurses for interactive terminal apps without GUI overhead.
• displayMenu(): Renders main menu using ncurses panels and handles key inputs via getch(); employs loops with conditionals for navigation, updating UI objects dynamically; designed for usability, separating input handling from business logic.
• editContactForm(): Creates form fields for contact editing, validates input, and calls DB methods; uses ncurses forms extension and Rexx stems for form data; rationale is intuitive user experience, with error handling built into methods.

app/utils.rex (Utility Functions)

• parseJson(): Converts JSON strings to Rexx directories using procedural parsing; classic Rexx string functions like pos() and substr(); exists as a helper to avoid external libs, supporting config-driven design.
• logError(): Logs errors to file or console using Unix extensions; simple procedural function with condition signals; designed for debugging and robustness, keeping utils lightweight.

tests/test_appdb.rexx (Test Suite)

• testAddContact(): Mocks DB insert and asserts results using Rexx's assert equivalents; calls class methods and checks stems; exists for TDD, ensuring DB reliability through isolated testing.
• testQuery(): Simulates queries and validates output structures; uses Object Rexx's testing patterns; rationale is to catch issues early, demonstrating separation of tests from production code.

Object & Data Flow

• Main data structures include contact records as Rexx stems (e.g., contact.1.name = "John") for flexible storage, and configuration as directory objects (e.g., config~dbPath) for easy access.
• Data flows from user input via ncurses UI methods (e.g., form submissions) to business logic in addrbook.rex (validation), then to SQLite backend for storage/retrieval (e.g., appdb~addContact(stem)); reverse flow pulls DB data into stems, formats via utils, and displays in UI windows.
• Error handling uses Object Rexx's signal on for conditions like syntax or novalue, with try-catch patterns in methods; safety includes parameterized SQLite queries and ncurses refresh checks to prevent crashes or data corruption.

Learning Path & Gotchas

• Start with addrbook.rex for overall flow, then install.rex for setup, followed by app/appdb.cls and app/appui.cls to grasp OOP integration, utils for helpers, and tests for validation; this order builds from high-level to details.
• Common pitfalls for Object Rexx newcomers include confusing classic Rexx procedural code with OOP (e.g., overusing globals instead of methods), improper ::requires for class loading, and mixing stems (dynamic arrays) with true objects—treat stems as lightweight data holders.
• Gotchas with ncurses include handling terminal resizes or key mappings across platforms (use resizeterm()), SQLite in Rexx requires careful extension loading and error codes, and Unix differences (e.g., paths on Windows vs. Linux) may need conditionals.
• Design decisions like UI-DB separation enhance modularity, JSON config allows extensibility without recompiles, and minimal dependencies showcase Object Rexx's power for self-contained CLI/TUI apps, making it ideal for hobbyists building real tools.