# ark vim

**Repository Path**: xw19981010/ark-vim

## Basic Information

- **Project Name**: ark vim
- **Description**: 此项目为SVCRTOS的ark c Compiler衍生项目，用于文件编写的操作，方便实现在stm32上编译stm32程序
- **Primary Language**: C/C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArkVim

**ArkVim** 是一个用严格 C99 编写的轻量级模态文本编辑器,可在任意
命令行 shell 中运行,也可作为独立程序运行。它专为嵌入式系统
(STM32、RISC-V MCU)和 PC 模拟设计,零动态内存分配,移植接口
极小且定义清晰。

```
ArkVim v1.0  "main.c"  142L                              1:1
```

## 为什么选 ArkVim?

| 目标 | 实现方式 |
|------|----------|
| 可在任意 shell 中运行 | 仅需 6 个函数的 `arkvim_port_t` 传输接口,不依赖任何 shell 头文件 |
| MCU 友好 | 全静态缓冲区,无 `malloc`,所有尺寸集中在一个头文件配置 |
| 严格 C99 / 兼容 armcc | 无 GCC 扩展,`-Wall -Wextra` 零警告 |
| 真正的编辑能力 | Normal/Insert/Command 三模态、撤销/重做、搜索、复制粘贴、语法高亮 |
| 可插拔文件后端 | PC 上用 POSIX,MCU 上可换 LittleFS/SPI Flash |

## 快速开始(PC 独立运行)

```sh
make
./arkvim             # 空白缓冲区
./arkvim file.c      # 编辑文件
./arkvim cat file.c  # 打印文件
./arkvim ls          # 列出文件
```

编辑器内操作:

```
i           进入 Insert 模式
Esc         回到 Normal 模式
hjkl        移动光标
:w :q :wq   保存 / 退出 / 保存并退出
:q!         强制退出(不保存)
u  Ctrl-R   撤销 / 重做
dd yy p     删除 / 复制 / 粘贴整行
/pat  n     向前搜索,重复搜索
:ver        显示 ArkVim 版本
```

## 快速开始(在 Ark Shell 中运行)

将 Ark Shell 源码克隆到本仓库同级目录:

```sh
git clone https://gitee.com/xw19981010/ark-shell.git ark-shell-ref
make -f Makefile.arkshell
./arkvim_shell
```

在 `ark>` 提示符下:

```
ark> vim main.c       # 打开编辑器
ark> cat README.md    # 打印文件
ark> ls               # 列出文件
ark> help             # 查看所有命令
```

## 架构

```
              +-------------------+
   宿主 ----> |  arkvim_port_t    |  6 个函数指针 (send/recv/tick)
              +-------------------+
                       |
              +-------------------+
              | arkvim_terminal    |  ANSI 发射 + 按键解码
              +-------------------+
                       |
   +----------+ +---------------+ +-------------+
   | gapbuffer| |  line_table   | |  renderer   |
   +----------+ +---------------+ +-------------+
                       |
              +-------------------+
              |   arkvim_modes    |  Normal/Insert/Command 状态机
              +-------------------+
                       |
          +------------+------------+
          |  undo   syntax  fileio  |
          +-------------------------+
                       |
              +-------------------+
              |    arkvim.h API    |  arkvim_editor_run / arkvim_main
              +-------------------+
```

编辑器所有内存均为静态分配。gap buffer 由编辑器结构体内的固定
`char` 数组支撑;撤销/重做使用固定大小栈;屏幕使用两个固定单元
缓冲区。全程无 `malloc`。

## 仓库结构

```
arkvim/
  src/                     编辑器核心(与 shell 无关)
    arkvim.h               公共 API
    arkvim_config.h        所有可调尺寸 / 功能开关
    arkvim_port.h/.c       传输接口(6 个函数指针)
    arkvim_terminal.h/.c   ANSI 发射 + CSI/SS3 按键解码
    arkvim_gap_buffer.h/.c O(1) 插删的文本缓冲区
    arkvim_line_table.h/.c 懒重建的行偏移索引
    arkvim_renderer.h/.c   双缓冲屏幕渲染,脏行差异刷新
    arkvim_fileio.h/.c     可插拔文件后端
    arkvim_fileio_posix.c  POSIX 文件后端(PC)
    arkvim_undo.h/.c       撤销/重做栈
    arkvim_syntax.h/.c     C 语法高亮
    arkvim_modes.h/.c      模态编辑器核心
    arkvim.c               API 粘合:arkvim_main、arkvim_register_posix_backend
  ports/                   宿主适配层
    arkvim_port_minimal.h/.c    独立运行(termios/Win32,无需 shell)
    arkvim_port_arkshell.h/.c   Ark Shell 适配器 + 命令注册
    arkvim_port_template.c      任意新 shell 的注释骨架
  demo/
    standalone.c           独立 CLI 演示
    arkshell_main.c        Ark Shell 集成演示
  Makefile                 独立构建
  Makefile.arkshell        Ark Shell 集成构建
```

## 集成到自己的 shell

ArkVim **不依赖任何 shell**。集成只需三步:

**1. 实现端口(6 个函数):**

```c
#include "arkvim_port.h"

static void my_send_byte(uint8_t b)      { uart_write(&b, 1); }
static void my_send_string(const char *s){ uart_write_str(s); }
static void my_send_buf(const uint8_t *buf, uint16_t len) { uart_write(buf, len); }
static int  my_recv_byte(void)           { return uart_read_byte(); }  /* 无数据返回 -1 */
static uint32_t my_tick_ms(void)         { return get_tick_ms(); }
static void my_cleanup(void)             { /* 可选 */ }

static const arkvim_port_t my_port = {
    my_send_byte, my_send_string, my_send_buf,
    my_recv_byte, my_tick_ms, my_cleanup
};
```

**2. 安装端口 + 文件后端:**

```c
arkvim_port_init(&my_port);
arkvim_register_posix_backend();   /* PC 用;MCU 上换自己的后端 */
```

**3. 接入 shell 命令处理器:**

```c
int my_vim_cmd(int argc, char *argv[]) {
    return arkvim_main(argc, argv);   /* 分发 "vim"/"cat"/"ls" */
}
```

或直接调用编辑器:

```c
arkvim_editor_run("config.ini");   /* 阻塞直到 :q */
```

详见 [ports/arkvim_port_template.c](ports/arkvim_port_template.c),
其中包含完整注释骨架。

## 配置

所有可调参数集中在 [src/arkvim_config.h](src/arkvim_config.h)。
可用编译命令行 `-D` 覆盖任意 `#define`。关键参数:

| 宏 | 默认值 | 含义 |
|----|--------|------|
| `ARKVIM_SCREEN_ROWS` | 24 | 终端行数 |
| `ARKVIM_SCREEN_COLS` | 80 | 终端列数 |
| `ARKVIM_GB_MAX_SIZE` | 16384 | gap buffer 后备存储(字节) |
| `ARKVIM_LT_MAX_LINES` | 1024 | 最大跟踪行数 |
| `ARKVIM_UNDO_MAX_DEPTH` | 64 | 撤销栈深度 |
| `ARKVIM_ENABLE_SYNTAX` | 1 | C 语法高亮 |
| `ARKVIM_ENABLE_UNDO` | 1 | 撤销/重做支持 |
| `ARKVIM_ENABLE_LINE_NUMBERS` | 0 | `:set nu` 默认值 |

## MCU 移植要点

- 缩减 `ARKVIM_GB_MAX_SIZE` 以适应 RAM(如 STM32F401 上用 4KB)。
- 不编译 `arkvim_fileio_posix.c`;通过 `arkvim_fileio_set_backend()`
  注册 LittleFS/SPI Flash 后端。
- 提供基于 UART HAL 的端口(轮询/中断/DMA 均可——`recv_byte`
  只需在环形缓冲区为空时返回 `-1`)。
- 编辑器运行时接管终端,在 `:q`/`:wq`/`:q!` 后返回控制权。

## 构建要求

- C99 编译器(已测试 gcc、clang、armcc、MinGW)
- `make`
- 独立 PC 演示:无其他依赖
- Ark Shell 演示:需要 [ark-shell](https://gitee.com/xw19981010/ark-shell) 源码树

## 许可证

MIT。见各源文件头部。

## 链接

- Ark Shell: https://gitee.com/xw19981010/ark-shell
- ArkVim 仓库: https://gitee.com/xw19981010/ark-vim