kz80_ws 0.1.1

WordStar clone for Z80 - Retro word processor on the RetroShield
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

# kz80_ws - WordStar Clone for Z80

A WordStar-compatible text editor for the RetroShield Z80. This project generates a Z80 ROM binary that implements a classic WordStar-style text editor with VT100 terminal output.

## Features

- **Classic WordStar key bindings** - Familiar control key sequences for navigation and editing
- **VT100/ANSI terminal support** - Works with any VT100-compatible terminal
- **Block operations** - Mark, copy, move, and delete text blocks
- **File operations** - Save files to SD card storage (via RetroShield I/O)
- **Help system** - Built-in help screen (^J)
- **Status bar** - Shows filename, cursor position, insert/overwrite mode, and modified indicator
- **WordStar file format** - Authentic file format with high-bit word markers

## Building

### Prerequisites

- Rust toolchain (1.70 or later)
- The `retroshield-z80-workbench` crate (automatically fetched from crates.io)

### Build and Generate ROM

```bash
cargo build --release
./target/release/kz80_ws output.bin
```

Or simply:

```bash
cargo run -- output.bin
```

This generates a Z80 ROM binary file (~4KB) that can be loaded into a RetroShield Z80 or compatible emulator.

### Running in the Emulator

```bash
# Using the RetroShield emulator
../emulator/rust/target/release/retroshield output.bin

# Or with the TUI debugger (recommended)
../emulator/rust/target/release/retroshield_tui --vt220 output.bin

# Or with the C emulator
../emulator/retroshield output.bin
```

## Key Bindings

### Cursor Movement

| Key | Action |
|-----|--------|
| ^E | Cursor up |
| ^X | Cursor down |
| ^S | Cursor left |
| ^D | Cursor right |
| ^A | Word left |
| ^F | Word right |
| ^QS | Beginning of line |
| ^QD | End of line |
| ^QR | Top of file |
| ^QC | End of file |

Arrow keys are also supported via VT100 escape sequences.

### Editing

| Key | Action |
|-----|--------|
| ^G | Delete character right |
| DEL/^H | Delete character left (backspace) |
| ^Y | Delete entire line |
| ^N | Insert new line |
| ^V | Toggle insert/overwrite mode |
| Enter | New line |

### Block Operations (^K prefix)

| Key | Action |
|-----|--------|
| ^KB | Mark block begin |
| ^KK | Mark block end |
| ^KC | Copy block to cursor position |
| ^KV | Move block to cursor position |
| ^KY | Delete marked block |

### File Operations (^K prefix)

| Key | Action |
|-----|--------|
| ^KS | Save file |
| ^KD | Save and exit |
| ^KQ | Quit without saving |

### Quick Commands (^Q prefix)

| Key | Action |
|-----|--------|
| ^QR | Go to top of file |
| ^QC | Go to end of file |
| ^QS | Go to start of line |
| ^QD | Go to end of line |
| ^QF | Find text |

### Other

| Key | Action |
|-----|--------|
| ^J | Show help screen |
| ESC | Escape key prefix (for arrow keys) |

## Screen Layout

```
+------------------------------------------------------------------+
| Status: filename | L:nnn C:nnn Ins/Ovr [*]                       | <- Row 1
+------------------------------------------------------------------+
| ^K=Block ^Q=Quick ^S=Left ^D=Right ^E=Up ^X=Down ^Y=DelLn ^J=Help | <- Row 2
+------------------------------------------------------------------+
| (separator line)                                                  | <- Row 3
+------------------------------------------------------------------+
|                                                                   |
|                         Text editing area                         | <- Rows 4-22
|                           (19 lines)                              |
|                                                                   |
+------------------------------------------------------------------+
| (separator line)                                                  | <- Row 23
+------------------------------------------------------------------+
| Messages appear here                                              | <- Row 24
+------------------------------------------------------------------+
```

## Memory Map

| Address Range | Size | Usage |
|--------------|------|-------|
| 0x0000-0x1FFF | 8KB | ROM (generated code and data) |
| 0x2000-0x20FF | 256B | System variables |
| 0x2100-0x21FF | 256B | Input buffer |
| 0x2200-0x22FF | 256B | Filename buffer |
| 0x2300-0x23FF | 256B | Search/replace strings |
| 0x2800-0x3BFF | 5KB | Text buffer |
| 0x3C00-0x3DFF | 512B | Line index table |
| 0x3E00-0x3FFF | 512B | Stack |

## Technical Details

### Terminal Requirements

The editor requires a VT100-compatible terminal with:
- 80x24 minimum screen size
- Cursor positioning (ESC[row;colH)
- Clear screen (ESC[2J)
- Clear to end of line (ESC[K)
- Reverse video (ESC[7m) and reset (ESC[0m)

### I/O Ports

| Port | Usage |
|------|-------|
| 0x80 | MC6850 ACIA status register |
| 0x81 | MC6850 ACIA data register |
| 0x10-0x1F | SD card storage interface |

### WordStar File Format

Files are saved in authentic WordStar format:
- High bit set on last character of each word (for soft hyphenation)
- Soft returns (0x8D 0x0A) for word-wrapped lines
- Hard returns (0x0D 0x0A) for paragraph breaks
- Control codes for formatting: ^B=bold, ^S=underline, ^Y=italic

## Limitations

- Maximum ~5KB text buffer
- Maximum 256 lines
- Block operations are line-based only
- Single file editing (no multiple buffers)
- No undo functionality
- No print support

## Project Structure

```
kz80_ws/
├── Cargo.toml          # Rust package configuration
├── LICENSE             # BSD 3-Clause license
├── README.md           # This file
└── src/
    ├── main.rs         # Entry point - generates ROM file
    ├── lib.rs          # Library exports
    └── codegen.rs      # Z80 code generation (~2800 lines)
```

## How It Works

The project uses a code generation approach rather than cross-compilation:

1. **Code Generation**: The `WordStarCodeGen` struct builds Z80 machine code by emitting raw bytes
2. **Label System**: Labels and forward references are tracked and resolved after all code is emitted
3. **Standard Library**: Uses routines from `retroshield-z80-workbench` for I/O and terminal control
4. **ROM Output**: The final binary is a raw Z80 ROM image starting at address 0x0000

This approach provides:
- Fine-grained control over code layout and optimization
- No dependency on external Z80 assembler toolchain
- Easy integration with the Rust ecosystem
- Compile-time code generation with full type safety

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

BSD 3-Clause License - see [LICENSE](LICENSE) for details.

## Acknowledgments

- Inspired by MicroPro's WordStar (1978), the first widely-used word processor
- Built on the [retroshield-z80-workbench](https://crates.io/crates/retroshield-z80-workbench) framework
- Designed for the [RetroShield](https://www.tindie.com/products/8bitforce/retroshield-for-arduino-mega/) Z80 platform by 8-Bit Force

## See Also

- [RetroShield Z80 Workbench](https://github.com/ajokela/retroshield-z80-workbench) - The code generation framework
- [RetroShield Z80 Emulator](https://github.com/ajokela/retro-z80-emulator) - Z80 emulator with TUI debugger
- [WordStar on Wikipedia](https://en.wikipedia.org/wiki/WordStar) - History of the original WordStar