I/O: serial ASCII by default, numeric I/O behind -n/--numbers

The library can now print decimal digits (ROT-8's clb_digits/undigits), so a tape
usually wants characters out -- and serial was the one mode you had to remember
to ask for.  Flip that around:

    rot8_test tape          serial ASCII (cell >= 8 bits)
    rot8_test -n tape       the old decimal numbers

The default follows the geometry: a serial character needs 8 bits (7 data + 1
spare), so a 1..7 bit cell gets the numeric I/O instead -- 1-bit tapes keep
working with no extra flag.  Asking for -s/--serial (or --parity/--stop/--7e1) on
such a cell is still an error (exit 2), and -n together with a serial option is
now rejected as contradictory (exit 2).

--input follows the mode: text in serial, numbers with -n.  It was already
deferred until the whole command line was parsed, so order does not matter.

Docs: the README's I/O section is rewritten around the new default, the option
table gains -n/--numbers, the examples that feed numbers now pass -n, and the
INP/OUT note at the top explains the two modes.  --7e1 is unchanged apart from
being an explicit frame on top of a default that is already serial.

Also fixes the usage() printf: the examples had seven %s and only six program
arguments, one short (a stale bug, now matched up).
This commit is contained in:
dsh committed 2026-11-09 16:25:02 +08:00
1 parent 6e51df5240
commit a083a3422c
2 files changed
+70 -26

No files matched your search

+31 -16
View File
@@ -22,7 +22,8 @@ ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无ALU的各
| `INP` | `,` | 从输入读取到当前 Cell |
> 方便起见,INP与OUT的实现不做定义,只要INP能改变整个Cell而OUT能读取整个Cell即可.\
> 例如本项目以输入/输出十进制整数作为INP/OUT.
> 本项目**默认按 7 位 ASCII 串行**做 I/O(8 位及以上的 cell,一个字符一次);更窄的 cell 和
> `-n` / `--numbers` 用"整格十进制整数"的老行为 —— 见下面的「I/O 模式」.
> Cell 的位宽不属于指令集:任何位宽都成立(LSB 永远是那一位,`ROR` 在这个位宽里循环).\
> 本项目默认 8 bit,但位宽和纸带长度都能在运行时改 —— 见下面的「纸带尺寸与 Cell 位宽」.
@@ -33,6 +34,9 @@ ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无ALU的各
rot8_test tape
```
默认跟着位宽走:**8 位及以上的 cell 用串行字符 I/O**(`OUT` 就是 `putchar`),更窄的 cell 用
数值 I/O. 想显式指定就加 `-n` / `--numbers`(永远是数值)或 `-s` / `--serial`(要求 ≥ 8 位).
## 可视化内存
虚拟机可以一边执行 tape,一边把整条纸带(默认 259 个 Cell x 11 bit,`--mem` / `--cell` 可改)
@@ -95,12 +99,14 @@ ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无ALU的各
| `-t`, `--tty` / `--no-tty` | 强制当成/不当成终端(见下) |
| `-k`, `--compact` / `--full` | 强制精简画面/完整画面 |
| `-c`, `--color` / `--no-color` | 强制开/关 ANSI 颜色(默认跟随终端) |
| `-i`, `--input <v...>` | 预先喂给 `INP` 的值(空格或逗号分隔) |
| `-i`, `--input <v...>` | 预先喂给 `INP` 的值(串行下是字符串,`-n` 下是数字列表) |
| `-n`, `--numbers` | 数值 I/O:`OUT` 打整格十进制、`INP` 读一个十进制数 |
| `-s`, `--serial` | 串行字符 I/O(默认;写出来只是把默认说一遍) |
| `-m`, `--mem <n>` | 纸带长度(单位 Cell),任意值,默认 259,范围 1..1048576 |
| `-b`, `--cell <bits>` | Cell 位宽,任意值,默认 11,范围 1..32 |
| `-h`, `--help` | 帮助 |
不加 `--live` 与 `--dump` 时行为与以前完全一致:直接跑完,只留下 `OUT` 的输出.\
不加 `--live` 与 `--dump` 时直接跑完,只留下 `OUT` 的输出(默认是串行字符流,见「I/O 模式」).\
`--live` 期间 `OUT` 会被画面接管,程序结束后再原样补打出来,所以重定向到文件依然拿到完整的输出.\
输出不是终端(被管道/文件接管)时,`--live` 会退化成逐帧打印,可以直接 `less` 着看;程序也会在 stderr 上提一句.
@@ -116,7 +122,7 @@ ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无ALU的各
```sh
rot8_test --mem 300 tapes/wave.rot8 # 300 格(不是 2 的幂也行)
rot8_test --mem 1000 --cell 16 tapes/wave.rot8
rot8_test --mem 64 --cell 1 tapes/wave.rot8 # 1 bit 的 Cell
rot8_test --mem 64 --cell 1 tapes/wave.rot8 # 1 bit 的 Cell(默认走数值 I/O)
rot8_test --mem 100 --cell 12 --live tapes/wave.rot8
```
@@ -158,13 +164,16 @@ ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无ALU的各
## 输入
`INP` 现在按这个顺序取值:先吃 `--input` 排好的队列,再问现场(live 模式),最后才回落到
stdin —— 所以不带 `--input`、也不开 `--live` 时行为与以前完全一样.
stdin —— 所以不带 `--input`、也不开 `--live` 时输入那头和以前一样(输出模式见下一节).
```sh
rot8_test --input 7,5 tapes/full_adder.rot8 # 脚本/测试:一次喂完
rot8_test -n --input 7,5 tapes/full_adder.rot8 # 脚本/测试:一次喂完(数值)
rot8_test --input "hi" tapes/serial_echo.rot8 # 串行:一个字符一个 INP
rot8_test --live tapes/echo.rot8 # 现场:画面下方问 input>
```
下面这张是 `-n`(数值)模式的画面;串行模式长什么样见「I/O 模式」那一节.
live 模式下画面分两层,框里只**记录**已经产生的输入输出,提示在框**外面**:
```
@@ -194,28 +203,34 @@ output> 65
stdin 已经关掉(管道读完)时喂 0 并照常跑完,不会卡住. `tapes/echo.rot8`(内容就是 `,.`)是
拿来试这个的最小例子.
## 串行 I/O:7 位 ASCII 模式
## I/O 模式:默认串行(7 位 ASCII),`-n` 切回十进制
`-s` / `--serial` 把 `INP`/`OUT` 从"十进制整数"切成"一个字符":
`INP`/`OUT` **默认按一个字符**走(8 位及以上的 cell):tape 里放一个 `'R'`(82)出去就是一个 `R`.
以前那套"整格十进制整数 + 换行"还在,用 `-n` / `--numbers` 打开:
| | 十进制(默认) | 串行(`-s`) |
| | 串行(默认,cell ≥ 8 位) | 十进制(`-n` / `--numbers`) |
|---|---|---|
| `OUT` | 整格的值 + 换行 | **低 7 位**当字符,直接 `putchar`,不加换行 |
| `INP` | 读一个十进制数,整格覆盖 | 读**一个字符**,只写低 7 位 |
| `--input` | 数字列表 `7,5` | **字符串**,一个字符一个 `INP` |
| `OUT` | **低 7 位**当字符,直接 `putchar`,不加换行 | 整格的值 + 换行 |
| `INP` | 读**一个字符**,只写低 7 位 | 读一个十进制数,整格覆盖 |
| `--input` | **字符串**,一个字符一个 `INP` | 数字列表 `7,5` |
**第 8 位(bit 7)以及更高的位不归 I/O 管**:`INP` 只改低 7 位,把原来的高半个 cell 原样留着 ——
所以 tape 可以拿 bit 7 当标志位、长度位或者别的什么,而读写字符时它不会被冲掉. 想要 char
以外的数据,就放在那上面.
要求 **cell 至少 8 位**;不够会直接报错退出(exit 2),因为 7 位字符加 1 位标志才勉强放得下:
**默认由位宽决定**:cell ≥ 8 位走串行(7 位字符 + 1 位余量),< 8 位走数值 I/O —— 所以 1 bit
那种机器照旧跑,不需要额外参数. 显式写了 `-s` / `--serial` 又不够宽,才报错退出(exit 2);
`-n` 想跟串行选项一起写也会被拒(exit 2)—— 两种模式互斥.
```sh
rot8_test --serial --input "R8F" tapes/serial_echo.rot8 # 打 R8F
echo A | rot8_test -s tapes/echo.rot8 # 管道里喂一个字符
rot8_test -s --live --input "hi" tapes/serial_echo.rot8 # 画面里也显示成字符
rot8_test --input "R8F" tapes/serial_echo.rot8 # 打 R8F
echo A | rot8_test tapes/echo.rot8 # 管道里喂一个字符
rot8_test --live --input "hi" tapes/serial_echo.rot8 # 画面里也显示成字符
rot8_test -n --input 65 tapes/echo.rot8 # 要十进制:65,不是 A
```
老脚本里写的 `-s` 仍然能用:串行已经是默认,它只是把默认再说一遍.
`tapes/serial_echo.rot8` 就是 `,.,.,.`(读三个字符、原样打三个字符). 串行模式下字符是**连着**显示的
(字符流不该被空格拆开),数字模式才用空格分隔;画面里长这样:
+39 -10
View File
@@ -40,10 +40,14 @@ static void usage(const char *program) {
" --full always draw the full frame\n"
" -i, --input <v...> feed INP values up front (spaces or commas)\n"
" anything left over is asked for on the terminal\n"
" -s, --serial serial ASCII: OUT writes the low 7 bits of the\n"
" cell as one character, INP reads one character\n"
" into them and leaves bit 7 alone (cell >= 8 bits);\n"
" --input then takes characters, not numbers\n"
" -n, --numbers numeric I/O: OUT prints the whole cell in decimal\n"
" and INP reads one decimal number (this is what the\n"
" machine used before serial became the default);\n"
" --input then takes numbers, not characters\n"
" -s, --serial serial ASCII I/O, the default when a cell holds at\n"
" least 8 bits: OUT writes the low 7 bits of the cell\n"
" as one character, INP reads one character into them\n"
" and leaves bit 7 alone; --input takes text\n"
" --parity <p> serial framing: none (default), even (7E) or odd\n"
" (7O); INP fills bit 7, OUT checks it\n"
" --stop serial framing: bit 8 is the stop bit and must be\n"
@@ -57,14 +61,14 @@ static void usage(const char *program) {
"examples:\n"
" %s --live tapes/full_adder.rot8\n"
" %s --dump tapes/and.rot8\n"
" %s --live --input 7,5 tapes/full_adder.rot8\n"
" %s -n --input 7,5 tapes/full_adder.rot8\n"
" %s --cell 16 --dump tapes/wave.rot8\n"
" %s --mem 4096 --live tapes/wave.rot8\n"
" %s --serial --cell 8 tapes/echo.rot8\n"
" %s tapes/serial_echo.rot8\n"
" %s --7e1 --input R8F tapes/serial_echo.rot8\n",
program, (unsigned)ROT8_DEFAULT_MEM_SIZE, (unsigned)ROT8_MAX_MEM_SIZE,
(unsigned)ROT8_MAX_CELL_SIZE, (unsigned)ROT8_DEFAULT_CELL_SIZE, program,
program, program, program, program, program);
program, program, program, program, program, program);
}
static bool parse_uint(const char *text, unsigned int *out) {
@@ -128,10 +132,16 @@ int main(int argc, char **argv) {
rot8_viz *viz;
/* --input is collected and only pushed once the whole command line is
* known: in serial mode the same argument means characters, not numbers,
* and --serial may come after it */
* and the I/O mode may come after it */
const char *input_texts[64];
int input_text_count = 0;
bool serial = false;
/* Serial ASCII is the default -- the library can print decimal digits
* (ROT-8's clb_digits), so a tape usually wants characters out. A cell
* below 8 bits cannot carry one, and then numeric I/O is the only thing
* that fits: see the cell_size check further down. */
bool serial = true;
bool serial_chosen = false; /* --serial / --parity / --stop / --7e1 */
bool numbers_chosen = false;
bool stop = false;
rot8_parity parity = ROT8_PARITY_NONE;
@@ -158,8 +168,12 @@ int main(int argc, char **argv) {
return (2);
}
input_texts[input_text_count++] = argv[++i];
} else if (strcmp(arg, "-n") == 0 || strcmp(arg, "--numbers") == 0) {
serial = false;
numbers_chosen = true;
} else if (strcmp(arg, "-s") == 0 || strcmp(arg, "--serial") == 0) {
serial = true;
serial_chosen = true;
} else if (strcmp(arg, "--parity") == 0) {
const char *p = i + 1 < argc ? argv[++i] : NULL;
if (p == NULL) {
@@ -178,11 +192,14 @@ int main(int argc, char **argv) {
return (2);
}
serial = true; /* framing only exists in serial mode */
serial_chosen = true;
} else if (strcmp(arg, "--stop") == 0) {
stop = true;
serial = true;
serial_chosen = true;
} else if (strcmp(arg, "--7e1") == 0) {
serial = true;
serial_chosen = true;
parity = ROT8_PARITY_EVEN;
stop = true;
} else if (strcmp(arg, "-l") == 0 || strcmp(arg, "--live") == 0) {
@@ -255,7 +272,13 @@ int main(int argc, char **argv) {
program, cfg.mem_size, cfg.cell_size);
return (2);
}
if (serial && cfg.cell_size < 8) {
if (numbers_chosen && serial_chosen) {
fprintf(stderr,
"%s: --numbers and the serial options are mutually exclusive\n",
program);
return (2);
}
if (serial_chosen && cfg.cell_size < 8) {
fprintf(stderr,
"%s: serial I/O needs at least 8 bits per cell (got %u)\n",
program, cfg.cell_size);
@@ -267,6 +290,12 @@ int main(int argc, char **argv) {
program, cfg.cell_size);
return (2);
}
if (!numbers_chosen && !serial_chosen) {
/* Nobody said which I/O to use, so the geometry decides: a serial
* character needs 8 bits (7 data + 1 spare), and a narrower cell gets
* the numeric I/O -- that is what 1-bit tapes have always used. */
serial = cfg.cell_size >= 8;
}
rot8_io_set_serial(serial);
rot8_io_set_parity(parity);
rot8_io_set_stop(stop);