How hzhang08/gocat works
Project type and purpose
• From the README and file tree, gocat is a stand-alone, terminal‐based SGF viewer & editor for Go game records, written in Rust.
• It is not a client–server or web app, but a single binary that runs interactively in your terminal, parsing SGF files, maintaining game state, rendering boards, and responding to keystrokes.
File structure
• Top-level Cargo.toml & src/ directory indicate a Rust project.
• src/main.rs: application entry point and orchestrator
• src/sgf_parser.rs: SGF file parsing and serialization
• src/game.rs: in-memory game state, move tree, annotations
• src/ui.rs: terminal rendering (drawing board, menus, dialogs)
• src/ui_mode_actions.rs: mapping user input (hotkeys) into game/UI operations
Key insights from the README
• Interactive, keyboard-driven interface
• Core workflows: open SGF → parse → initialize game state → render initial position → enter event loop (handle keys) → possibly mutate state → redraw → save back to SGF
• No external server or database—only filesystem I/O and terminal APIs
• CLI Entrypoint (main.rs)
• SGF Parser Module (sgf_parser.rs)
• Game State Manager (game.rs)
• UI Layer (ui.rs)
• Input/Mode Actions (ui_mode_actions.rs)
• Terminal I/O (external crate, e.g., termion/crossterm)
• File System (local storage)
b. Relationships and data flow
1) User invokes gocat <file>.sgf → CLI Entrypoint
2) Entrypoint calls Parser → reads SGF from File System → outputs GameRecord
3) Game State Manager loads GameRecord → exposes model API
4) UI Layer renders initial board using Game State → sends escape sequences to Terminal I/O
5) Terminal I/O captures keystrokes → forwards events to Input Handler (inside UI Layer)
6) Input Handler calls Mode Actions → Mode Actions mutate Game State or update annotations via Game State API
7) After each action, UI Layer queries Game State → produces new view → writes to Terminal I/O
8) On save/quit, Parser serializes Game State back to SGF → writes to File System
c. Architectural patterns & principles
• Modular separation: parser, model, UI, and input handling in distinct modules
• MVC-like structure:
• Model = Game State Manager
• View = UI Layer + Terminal I/O
• Controller = UI Mode Actions/Input Handler
• Single event loop: central loop in main.rs delegating to parser, UI, and action modules
• Dependency flow: main → parser, game, ui → ui_mode_actions; no circular dependencies
d. Key technologies & libraries
• Rust (Cargo, ownership model)
• SGF format (text-based game record)
• Terminal I/O crate (e.g., termion or crossterm for raw mode, input events, ANSI rendering)