Project 2: Raw Key Decoder

A tool that prints decoded key events (arrow keys, function keys, Ctrl combos).

Quick Reference

Attribute	Value
Difficulty	Level 2: Intermediate (REFERENCE.md)
Time Estimate	Weekend
Main Programming Language	C
Alternative Programming Languages	Rust, Go, Python
Coolness Level	Level 2: Practical but Forgettable (REFERENCE.md)
Business Potential	Level 1: Resume Gold (REFERENCE.md)
Prerequisites	Input Modes and Key Decoding
Key Topics	Input Handling

1. Learning Objectives

By completing this project, you will:

Build and validate the core behavior described in the real-world outcome.
Apply Input Modes and Key Decoding to a working TUI.
Design a predictable input-to-rendering pipeline with explicit state changes.
Produce a tool that behaves consistently across terminals and restores state on exit.

2. All Theory Needed (Per-Concept Breakdown)

Input Modes and Key Decoding (termios Line Discipline)

Fundamentals Terminal input is not delivered to your program exactly as the user types it. The terminal driver applies a line discipline that can buffer input, handle editing keys, and interpret control characters. POSIX termios defines canonical (line-based) and non-canonical (raw-ish) input processing. In canonical mode, input is delivered line-by-line and read() waits until newline or EOF; editing keys like erase and kill are handled by the driver. In non-canonical mode, input is delivered immediately and the driver does not perform line editing. This distinction is essential for interactive TUIs because you need keypress-level input, not line-buffered input. citeturn1search3

Deep Dive into the concept The termios interface defines how a terminal device processes input and output. Canonical mode (often called “cooked”) is designed for typical shell usage: the driver buffers input until it sees a line delimiter, then passes it to the program. This means your program cannot react to individual keypresses in real time, and special characters like Backspace are processed before the program ever sees them. In contrast, non-canonical mode disables line buffering and line editing, and uses the MIN and TIME settings to control when read() returns. This lets a TUI receive bytes immediately and implement its own key handling.

Raw mode in modern libraries is usually a bundle of termios changes: disable canonical input, disable echo, and disable signal generation for control characters. This is crucial for handling keys like Ctrl+C yourself. Libraries like crossterm summarize the effects: input is no longer line buffered, special keys are not processed by the terminal driver, and input is delivered byte-by-byte. citeturn3search2

Once in non-canonical/raw mode, you must interpret input bytes. Many keys are sent as multi-byte escape sequences (for example, arrow keys often begin with ESC). These sequences are not standardized across all terminals, which is why terminfo also contains key capabilities. Your input decoder must handle partial sequences, timeouts, and ambiguous prefixes (ESC alone vs ESC as the start of a sequence). A robust approach is to implement a small state machine: when you see ESC, start collecting bytes; if a complete known sequence is matched, emit a high-level key event; if timeout occurs, treat ESC as a standalone key.

Another key aspect is signals and terminal restoration. If your program is interrupted (SIGINT, SIGTERM) while in raw mode, the terminal may remain in a broken state. A reliable TUI sets up cleanup handlers to restore termios state on exit, and uses an alternate screen buffer to keep the user’s shell clean.

Finally, input in TUIs is not just keys. Resize events are delivered via signals (like SIGWINCH) or via platform-specific APIs, and mouse input can be enabled in some terminals. In your architecture, all of these should be normalized into a single event stream to keep update logic deterministic.

Non-canonical mode uses two parameters, often called VMIN and VTIME, to control when reads return. This lets you trade off latency and CPU usage. A common approach is to request at least one byte and use a short timeout, which yields responsive input without a busy loop. For portability, you should treat these parameters as a contract: they define the boundary between polling and blocking behavior in your main loop.

The line discipline can also transform bytes (for example, carriage return to newline) and handle special control characters. When you disable canonical processing, these transformations often stop, which means you must decide how to handle them yourself. This is why a raw-mode TUI frequently treats Enter, Backspace, and Tab as high-level events that it interprets explicitly.

Key decoding is best done in layers: a byte reader, a sequence parser, and an event normalizer. The parser recognizes known escape sequences and converts them into symbolic events, while the normalizer maps them into consistent key names across platforms. This layered design lets you test the parser independently from the rest of the UI, and it makes it easier to support both simple keys (single byte) and complex keys (multi-byte sequences).

How this fits on projects

Project 2 (Raw Key Decoder), Project 5 (ncurses Dashboard), Project 8 (Bubble Tea Git Client)

Definitions & key terms

Canonical mode: Line-buffered input processing; read() returns after newline/EOF. citeturn1search3
Non-canonical mode: Byte-level input without line editing. citeturn1search3
Raw mode: A common configuration that disables echo, line buffering, and special-key processing. citeturn3search2
Escape sequence: Multi-byte sequences starting with ESC representing special keys.

Mental model diagram

Keyboard -> Driver Buffer -> termios line discipline -> read() -> Key Decoder -> Events
            (canonical or raw)                                (state machine)

How it works

Configure termios to canonical or non-canonical mode.
Read bytes from stdin as they arrive.
Feed bytes into a decoder that recognizes escape sequences.
Emit high-level events (Up, Down, Ctrl+C, etc.).
Feed events into your app’s update loop.

Minimal concrete example

PSEUDOCODE:
SET_INPUT_MODE(raw)
WHILE running:
  bytes = READ_NONBLOCKING()
  FOR b IN bytes:
    decoder.feed(b)
    IF decoder.has_event():
      event = decoder.pop_event()
      dispatch(event)

Common misconceptions

“Raw mode means no rules” -> It still follows MIN/TIME semantics.
“Arrow keys are single bytes” -> They are usually escape sequences.
“SIGINT always means exit” -> You can capture Ctrl+C in raw mode.

Check-your-understanding questions

Why does canonical mode prevent real-time key handling?
What is the role of MIN and TIME in non-canonical mode?
Why must you restore terminal state on exit?

Check-your-understanding answers

Input is buffered until newline/EOF, so keypresses are not delivered immediately.
They control when read() returns in byte-oriented input.
Otherwise the user’s terminal can remain in raw/no-echo mode.

Real-world applications

TUIs, terminal games, interactive debuggers, SSH-based tools

Where you’ll apply it

Project 2, Project 5, Project 8, Project 12

References

POSIX termios input processing (canonical vs non-canonical) citeturn1search3
crossterm raw mode behavior (summary of effects) citeturn3search2
“Advanced Programming in the UNIX Environment” - Ch. 18

Key insights Raw input is a controlled state machine, not a free-for-all stream.

Summary Input handling is a layered pipeline; understanding termios is required to build reliable keyboard-driven interfaces.

Homework/Exercises to practice the concept

Draw a state machine for decoding ESC-based arrow keys.
Describe how you would detect a resize event in your app.

Solutions to the homework/exercises

Start in NORMAL; on ESC move to ESC_SEEN; accept ‘[’ then digits; map known final byte to key.
Use a signal handler for window resize and push a Resize event into your loop.

3. Project Specification

3.1 What You Will Build

A tool that prints decoded key events (arrow keys, function keys, Ctrl combos).

Included:

The core UI flow described in the Real World Outcome
Deterministic input handling and rendering
Clean exit and terminal state restoration

Excluded:

GUI features, mouse-first workflows, or non-terminal frontends
Networked collaboration or cloud sync

3.2 Functional Requirements

Core Interaction: Implements the main interaction loop and updates the screen correctly.
Input Handling: Handles required keys without blocking and supports quit/exit.
Rendering: Updates only what changes to avoid flicker.
Resize Handling: Adapts to terminal resize or shows a clear warning state.
Errors: Handles invalid input or missing data gracefully.

3.3 Non-Functional Requirements

Performance: Stable refresh without visible flicker under normal usage.
Reliability: Terminal state is restored on exit or error.
Usability: Keyboard-first navigation with clear status/help hints.

3.4 Example Usage / Output

$ ./key-decoder

$ ./key-decoder Press keys (Q to quit)

KEY: UP KEY: DOWN KEY: CTRL+C KEY: ESC KEY: F5


ASCII layout:

[Live key log] [Footer: last sequence bytes]

3.5 Data Formats / Schemas / Protocols

Screen Model: 2D grid of cells with glyph + style
Input Events: Normalized key events (Up, Down, Enter, Esc, Ctrl)
State Snapshot: Immutable model used for rendering each frame

3.6 Edge Cases

Terminal resized to smaller than minimum layout
Rapid key repeat and partial escape sequences
Missing or invalid input file (if applicable)
Unexpected termination (SIGINT)

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ ./key-decoder

3.7.2 Golden Path Demo (Deterministic)

Launch the tool
Perform the primary action once
Observe the expected screen update

3.7.3 If CLI: provide an exact terminal transcript

$ ./key-decoder

$ ./key-decoder Press keys (Q to quit)

KEY: UP KEY: DOWN KEY: CTRL+C KEY: ESC KEY: F5


ASCII layout:

[Live key log] [Footer: last sequence bytes]

3.7.4 Failure Demo (Deterministic)

$ ./key-decoder --bad-flag
ERROR: unknown option: --bad-flag
exit code: 2

4. Solution Architecture

4.1 High-Level Design

Input -> Event Queue -> State Update -> Render -> Terminal

4.2 Key Components

Component	Responsibility	Key Decisions
Input Decoder	Normalize raw input into events	Handle partial sequences safely
State Model	Hold UI state and selections	Keep state immutable per frame
Renderer	Draw from state to terminal	Diff-based updates
Controller	Orchestrate loop and timers	Non-blocking IO

4.3 Data Structures (No Full Code)

DATA STRUCTURE: Cell
- glyph
- fg_color
- bg_color
- attrs

DATA STRUCTURE: Frame
- width
- height
- cells[width][height]

4.4 Algorithm Overview

Key Algorithm: Render Diff

Build new frame from current state
Compare with old frame
Emit minimal updates for changed cells

Complexity Analysis:

Time: O(width * height)
Space: O(width * height)

5. Implementation Guide

5.1 Development Environment Setup

# Build and run with your toolchain

5.2 Project Structure

project-root/
|-- src/
|-- tests/
|-- assets/
`-- README.md

5.3 The Core Question You’re Answering

“What exactly reaches my program when I press a key?”

5.4 Concepts You Must Understand First

Canonical vs Non-Canonical Input
- When does read() return?
- Book Reference: “Advanced Programming in the UNIX Environment” - Ch. 18
Escape Sequence Parsing
- Why do arrow keys start with ESC?
- Book Reference: “The Linux Programming Interface” - Ch. 62
State Machines
- How do you parse a stream incrementally?
- Book Reference: “Algorithms, Fourth Edition” - Ch. 1

5.5 Questions to Guide Your Design

Parsing
- How will you handle partial sequences?
- What timeout will distinguish ESC vs ESC+[?
Output
- How will you log raw bytes vs decoded events?

5.6 Thinking Exercise

Build the Key Decoder FSM

Draw states for NORMAL, ESC_SEEN, CSI_SEEN.

Questions to answer:

What happens if you get ESC then a regular letter?
When do you reset to NORMAL?

5.7 The Interview Questions They’ll Ask

“Explain canonical vs non-canonical input.”
“Why are arrow keys multi-byte sequences?”
“How would you parse a streaming protocol?”
“How do you avoid blocking the UI?”
“Why must terminal state be restored?”

5.8 Hints in Layers

Hint 1: Log raw bytes Print hex codes of every input byte first.

Hint 2: Recognize ESC + ‘[’ sequences Build a small parser that waits for a final byte.

Hint 3: Pseudocode

if b == ESC: state = ESC_SEEN
elif state == ESC_SEEN and b == '[': state = CSI

Hint 4: Debugging Add a timeout counter to reset state if no byte arrives.

5.9 Books That Will Help

Topic	Book	Chapter
Terminal I/O	“Advanced Programming in the UNIX Environment”	Ch. 18
Parsing streams	“Algorithms, Fourth Edition”	Ch. 1

5.10 Implementation Phases

Phase 1: Foundation

Goals:

Initialize the terminal and input handling
Render the first static screen

Tasks:

Implement setup and teardown
Draw a static layout that matches the Real World Outcome

Checkpoint: The UI renders and exits cleanly.

Phase 2: Core Functionality

Goals:

Implement the main interaction loop
Update state based on input

Tasks:

Add event processing
Implement the main feature (draw, navigate, filter)

Checkpoint: The primary interaction works end-to-end.

Phase 3: Polish & Edge Cases

Goals:

Handle resizing and invalid input
Improve performance and usability

Tasks:

Add resize handling
Add error states and help hints

Checkpoint: No flicker and clean recovery from edge cases.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Input model	raw vs canonical	raw	Required for key-level input
Render strategy	full redraw vs diff	diff	Avoid flicker and reduce output
State model	mutable vs immutable	immutable	Predictable updates and testing

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Unit Tests	Validate parsing and state transitions	Key decoder tests
Integration Tests	Verify rendering pipeline	Frame diff vs expected
Edge Case Tests	Terminal resize and invalid input	Small terminal size

6.2 Critical Test Cases

Resize: Shrink terminal below minimum and verify warning.
Rapid Input: Hold down keys and ensure no crash.
Exit: Force quit and verify terminal restoration.

6.3 Test Data

Input sequence: Up, Up, Down, Enter
Expected: selection moves and activates without crash

7. Common Pitfalls & Debugging

Problem 1: “ESC key never registers”

Why: You always treat ESC as the start of a sequence.
Fix: Add a timeout to treat ESC as standalone.
Quick test: Press ESC alone and ensure it logs.

8. Extensions & Challenges

8.1 Beginner Extensions

Add a help overlay with keybindings
Add a status bar with timestamps

8.2 Intermediate Extensions

Add configurable themes
Add persistent settings file

8.3 Advanced Extensions

Add plugin hooks for new views
Add performance tracing for render time

9. Real-World Connections

9.1 Industry Applications

Terminal dashboards for infrastructure monitoring
Developer tools used over SSH and in containers

htop, ranger, lazygit, nmtui (for UI design reference)

9.3 Interview Relevance

Input handling, event loops, and state modeling questions

10. Resources

10.1 Essential Reading

“Advanced Programming in the UNIX Environment”

10.2 Video Resources

Conference talks on terminal UI architecture (choose one and take notes)

10.3 Tools & Documentation

terminfo, curses, or framework docs used in this project

See other projects in this folder for follow-on ideas

11. Self-Assessment Checklist

11.1 Understanding

I can explain the rendering pipeline for this project
I can explain how input is decoded and normalized
I can explain how my UI state updates per event

11.2 Implementation

All functional requirements are met
All critical test cases pass
Edge cases are handled and documented

11.3 Growth

I documented lessons learned
I can explain this project in a job interview

12. Submission / Completion Criteria

Minimum Viable Completion:

Program runs and matches Real World Outcome
Terminal state restored on exit
Main interaction works

Full Completion:

All minimum criteria plus:
Resize handling and error states
Tests for core parsing and rendering

Excellence (Going Above & Beyond):

Performance profiling results included
Additional features from Extensions completed

Project 2: Raw Key Decoder

Quick Reference

1. Learning Objectives

2. All Theory Needed (Per-Concept Breakdown)

Input Modes and Key Decoding (termios Line Discipline)

3. Project Specification

3.1 What You Will Build

3.2 Functional Requirements

3.3 Non-Functional Requirements

3.4 Example Usage / Output

3.5 Data Formats / Schemas / Protocols

3.6 Edge Cases

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

3.7.2 Golden Path Demo (Deterministic)

3.7.3 If CLI: provide an exact terminal transcript

3.7.4 Failure Demo (Deterministic)

4. Solution Architecture

4.1 High-Level Design

4.2 Key Components

4.3 Data Structures (No Full Code)

4.4 Algorithm Overview

5. Implementation Guide

5.1 Development Environment Setup

5.2 Project Structure

5.3 The Core Question You’re Answering

5.4 Concepts You Must Understand First

5.5 Questions to Guide Your Design

5.6 Thinking Exercise

5.7 The Interview Questions They’ll Ask

5.8 Hints in Layers

5.9 Books That Will Help

5.10 Implementation Phases

Phase 1: Foundation

Phase 2: Core Functionality

Phase 3: Polish & Edge Cases

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

6.3 Test Data

7. Common Pitfalls & Debugging

8. Extensions & Challenges

8.1 Beginner Extensions

8.2 Intermediate Extensions

8.3 Advanced Extensions

9. Real-World Connections

9.1 Industry Applications

9.2 Related Open Source Projects

9.3 Interview Relevance

10. Resources

10.1 Essential Reading

10.2 Video Resources

10.3 Tools & Documentation

10.4 Related Projects in This Series

11. Self-Assessment Checklist

11.1 Understanding

11.2 Implementation

11.3 Growth

12. Submission / Completion Criteria