tiny8.cli module¶

Terminal-based visualizer for tiny8 CPU step traces.

Simplified and enhanced CLI with Vim-style controls, marks, search, and more.

tiny8.cli.key_handler(*keys)[source]¶

Decorator to register a function as a handler for specific key(s).

Parameters:: *keys (int | str) – One or more keys (as int or string) to bind to this handler.

Example

@key_handler(ord(‘q’), 27) # q and ESC def quit_handler(state, …):

return True # Signal to exit

class tiny8.cli.ViewState(step_idx=0, scroll_offset=0, playing=False, last_advance_time=0.0, delay=0.15, show_all_regs=True, show_all_mem=False, command_mode=False, command_buffer='', marks=<factory>, status_msg='', status_time=0.0)[source]¶

Bases: object

State container for the CLI visualizer.

Parameters:

step_idx (int)
scroll_offset (int)
playing (bool)
last_advance_time (float)
delay (float)
show_all_regs (bool)
show_all_mem (bool)
command_mode (bool)
command_buffer (str)
marks (dict[str, int])
status_msg (str)
status_time (float)

step_idx¶

Current step index in trace.

Type:: int

scroll_offset¶

Vertical scroll offset for memory view.

Type:: int

playing¶

Whether auto-play is active.

Type:: bool

last_advance_time¶

Timestamp of last auto-advance.

Type:: float

delay¶

Delay between auto-advance steps in seconds.

Type:: float

show_all_regs¶

Show all 32 registers vs only changed.

Type:: bool

show_all_mem¶

Show non-zero memory vs all memory.

Type:: bool

command_mode¶

Whether in command input mode.

Type:: bool

command_buffer¶

Current command being typed.

Type:: str

marks¶

Dictionary of named position marks.

Type:: dict[str, int]

status_msg¶

Current status message to display.

Type:: str

status_time¶

Timestamp when status message was set.

Type:: float

step_idx: int = 0¶

scroll_offset: int = 0¶

playing: bool = False¶

last_advance_time: float = 0.0¶

delay: float = 0.15¶

show_all_regs: bool = True¶

show_all_mem: bool = False¶

command_mode: bool = False¶

command_buffer: str = ''¶

marks: dict[str, int]¶

status_msg: str = ''¶

status_time: float = 0.0¶

__init__(step_idx=0, scroll_offset=0, playing=False, last_advance_time=0.0, delay=0.15, show_all_regs=True, show_all_mem=False, command_mode=False, command_buffer='', marks=<factory>, status_msg='', status_time=0.0)¶

Parameters:

step_idx (int)
scroll_offset (int)
playing (bool)
last_advance_time (float)
delay (float)
show_all_regs (bool)
show_all_mem (bool)
command_mode (bool)
command_buffer (str)
marks (dict[str, int])
status_msg (str)
status_time (float)

Return type:

None

class tiny8.cli.KeyContext(state, scr, traces, cpu, mem_addr_start, mem_addr_end, source_lines, n)[source]¶

Bases: object

Context passed to key handlers.

Parameters:

state (ViewState)
scr (Any)
traces (list)
cpu (Any)
mem_addr_start (int)
mem_addr_end (int)
source_lines (list[str] | None)
n (int)

state: ViewState¶

scr: Any¶

traces: list¶

cpu: Any¶

mem_addr_start: int¶

mem_addr_end: int¶

source_lines: list[str] | None¶

n: int¶

redraw()[source]¶

Redraw screen and return height.

Return type:: int

set_status(msg)[source]¶

Set status message.

Parameters:: msg (str)
Return type:: None

__init__(state, scr, traces, cpu, mem_addr_start, mem_addr_end, source_lines, n)¶

Parameters:

state (ViewState)
scr (Any)
traces (list)
cpu (Any)
mem_addr_start (int)
mem_addr_end (int)
source_lines (list[str] | None)
n (int)

Return type:

None

tiny8.cli.format_byte(value)[source]¶

Format byte value as two-digit hex string.

Parameters:: value (int) – Byte value to format (0-255).
Returns:: Two-character uppercase hex string.
Return type:: str

tiny8.cli.safe_add(scr, y, x, text, attr=0, max_x=None)[source]¶

Safely add text to screen, handling boundary conditions.

Parameters:

scr – Curses screen object.
y (int) – Y coordinate (row).
x (int) – X coordinate (column).
text (str) – Text to display.
attr (int) – Display attributes (e.g., curses.A_BOLD).
max_x (int | None) – Maximum x coordinate, or None to use screen width.

Return type:

None

tiny8.cli.draw_step(scr, state, traces, cpu, mem_start, mem_end, source_lines=None)[source]¶

Draw the current execution step to screen.

Displays header, SREG flags, assembly source code, registers, and memory for the current step. Highlights changes from previous step and the currently executing source line.

Parameters:

scr – Curses screen object.
state (ViewState) – Current view state.
traces (list) – List of execution trace entries.
cpu – CPU instance (unused, for consistency).
mem_start (int) – Start address for memory display.
mem_end (int) – End address for memory display.
source_lines (list[str] | None) – Optional list of original assembly source lines for display.

Returns:

Total number of lines drawn (for scroll calculations).

Return type:

int

tiny8.cli.show_help(scr)[source]¶

Display help screen with all available commands and controls.

Shows comprehensive documentation of keyboard shortcuts, commands, and features. Waits for user keypress before returning.

Parameters:: scr – Curses screen object.
Return type:: None

tiny8.cli.show_info(scr, entry, idx)[source]¶

Display detailed information about a specific step.

Shows PC, SP, instruction, SREG, and all non-zero registers and memory for the given step. Waits for user keypress before returning.

Parameters:

scr – Curses screen object.
entry (dict) – Trace entry dictionary containing step data.
idx (int) – Step index number.

Return type:

None

tiny8.cli.run_command(state, traces)[source]¶

Execute a command and return status message.

Handles all command types including navigation, search, and tracking. Updates state.step_idx and state.scroll_offset as needed.

Parameters:

state (ViewState) – Current ViewState object to modify.
traces (list[dict]) – List of trace entry dictionaries.

Returns:

Status message string describing the result.

Return type:

str

Command Types:

Numeric (123): Jump to step 123
Relative (±50): Jump forward/backward 50 steps
Forward search (/add): Find instruction containing “add”
Backward search (?ldi): Search backward for “ldi”
PC jump (@100): Jump to PC address 0x64
Register track (r10): Find next change to R10
Register search (r10=42): Find where R10 equals 42
Memory track (m100): Find next change to memory[100]
Memory search (m100=0xFF): Find where memory[100] equals 0xFF
Flag track (fZ): Find next change to flag Z
Flag search (fC=1): Find where flag C equals 1
Help (h, help): Show command documentation

tiny8.cli.handle_quit(ctx)[source]¶

Quit the visualizer.

Parameters:: ctx (KeyContext)
Return type:: bool

tiny8.cli.handle_play_pause(ctx)[source]¶

Toggle play/pause.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_step_forward(ctx)[source]¶

Step forward.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_step_backward(ctx)[source]¶

Step backward.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_jump_forward(ctx)[source]¶

Jump forward 10 steps.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_jump_backward(ctx)[source]¶

Jump backward 10 steps.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_goto_first(ctx)[source]¶

Go to first step.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_goto_last(ctx)[source]¶

Go to last step.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_toggle_regs(ctx)[source]¶

Toggle showing all registers.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_toggle_mem(ctx)[source]¶

Toggle showing all memory.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_slower(ctx)[source]¶

Decrease playback speed.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_faster(ctx)[source]¶

Increase playback speed.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_show_info(ctx)[source]¶

Show detailed step information.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_show_help(ctx)[source]¶

Show help screen.

Parameters:: ctx (KeyContext)
Return type:: int

tiny8.cli.handle_scroll_down(ctx, h)[source]¶

Scroll memory view down.

Parameters:

ctx (KeyContext)
h (int)

Return type:

int

tiny8.cli.handle_scroll_up(ctx, h)[source]¶

Scroll memory view up.

Parameters:

ctx (KeyContext)
h (int)

Return type:

int

tiny8.cli.run_cli(cpu, mem_addr_start=0, mem_addr_end=31, delay=0.15, source_lines=None)[source]¶

Run interactive CLI visualizer in terminal.

Displays CPU state, registers, memory, and assembly source in a curses-based interface with keyboard navigation and playback controls.

Parameters:

cpu – CPU instance with step_trace attribute containing execution history.
mem_addr_start (int) – Starting memory address to display (default: 0).
mem_addr_end (int) – Ending memory address to display (default: 31).
delay (float) – Initial playback delay in seconds (default: 0.15).
source_lines (list[str] | None) – Optional list of original assembly source lines for display.

Raises:

RuntimeError – If cpu.step_trace is empty or missing.

Return type:

None

tiny8.cli.main()[source]¶

Entry point for CLI command-line interface.

Parses command-line arguments, assembles the input file, runs the CPU, and launches either CLI or animation mode visualization.

The function supports two modes: - CLI mode: Interactive terminal-based step-through debugger - Animation mode: Generate video/GIF visualization of execution

Command-line arguments are organized into groups for better clarity: - Execution options: Control CPU behavior (max-steps) - Memory display: Configure memory address range (supports hex notation) - CLI mode: Interactive playback settings - Animation mode: Video generation parameters

Return type:: None