Skip to content

Commit

Permalink
docs: add usage, adjust content
Browse files Browse the repository at this point in the history
  • Loading branch information
ErnestThePoet committed Mar 26, 2024
1 parent eb3930d commit c96cc85
Showing 1 changed file with 32 additions and 7 deletions.
39 changes: 32 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,39 @@
## 特点
- ✅给出了精确的IR语法定义
- ✅支持批量加载IR代码文件,**可直接将多个IR文件拖入**
- ✅交互界面友好,IR代码编辑器支持语法高亮、智能补全、搜索替换与可视化错误提示等多种功能
- ✅以标签页的形式切换多个虚拟机实例
- ✅支持全局变量的定义与使用
- ✅完善的错误检查,详细的错误提示
- ✅在线运行,无需配置环境
- ✅友好的交互界面
- ✅完整展示全局变量表和调用栈中所有函数的局部变量表
- ✅可设置的运行选项:最大执行步数限制(防止无限循环/递归);虚拟机内存大小、栈大小
- ✅良好的移动端适配
-**提供CLI命令行版本供自动化测试使用**

## 使用方法
### 导入.ir文件
打开虚拟机页面后,您可以通过以下任何一种方式开始使用虚拟机:
- 使用左侧菜单中的`新建`选项,创建一个空白的.ir文件
- 使用左侧菜单中的`导入`选项,导入想要运行的本地.ir文件
- 直接将本地的.ir文件拖入页面中
- 使用左侧菜单中的`示例`选项,在对话框中选取您感兴趣的示例IR程序

对于每个导入的.ir文件,系统都会创建一个新的虚拟机实例,您可以在页面中以标签页的形式切换这些实例。

### 编辑IR代码
虚拟机实例界面的左侧是IR代码编辑器,它使用的是与VSCode同款的[Monaco Editor](https://github.com/microsoft/monaco-editor),支持IR代码的语法高亮、智能补全、搜索替换与可视化错误提示等多种功能。您可以在其中编辑IR代码,并且方便地发现和修正IR代码的静态检查错误。

### 运行IR代码
虚拟机实例界面的中间是虚拟机控制台。点击控制台顶部的`运行`按钮,虚拟机将运行IR程序;点击`单步`按钮,虚拟机则将一步一步执行IR程序。在单步执行过程中,点击`运行`按钮可以切换到连续运行模式。当执行到`READ`指令时,控制台中会显示输入提示消息,您完成输入后按下`Enter`键即可。虚拟机采用流式输入,您可以在一行中用任意空白符号分隔多组数据。程序执行结束时,控制台会输出程序`main`函数的返回值和运行统计信息。
新创建的虚拟机处于`初始`状态,此状态下可以点击`运行``单步`按钮开始虚拟机的运行。IR程序执行完毕后,虚拟机会处于`正常退出``不正常退出`状态,在这些状态下都可以直接点击`运行``单步`按钮,开始下一轮运行。在开始执行前,虚拟机将首先对IR程序进行静态检查,如果存在错误,则会变为`IR静态分析错误`状态;运行时遇到错误,虚拟机将进入`运行时错误`状态;运行步数超过设置的上限值,虚拟机就会进入`达到步数限制`状态。在这些状态下,不能继续运行虚拟机,需要点击控制台上方的`重置`按钮将虚拟机恢复到`初始`状态。

### 修改虚拟机设置
虚拟机实例界面的右侧是虚拟机监视器,在其中可以设置虚拟机的执行步数上限和内存大小,也可以查看虚拟机当前的运行状态、执行步数、内存使用和变量表。
只有当虚拟机处于`初始`状态时,您才可以修改虚拟机的设置。如果您不希望限制虚拟机的执行步数,则可以将执行步数上限设置为`0`

## IR程序样例
IR虽然简单,其实无所不能。难道你不想试试`示例`选项里那些有意思的IR程序吗~
IR虽然简单,其实无所不能。难道你不想试试左侧菜单中`示例`选项里那些有意思的IR程序吗~
注:示例IR程序及其cmm源代码位于仓库的`public\demos`目录下

## 虚拟机信息
Expand Down Expand Up @@ -108,15 +129,19 @@ node irvm.mjs rand.ir -p -s
```
node irvm.mjs rand.ir
```
- 运行IR程序,将`stdout`上的输出写入文件(PowerShell环境):
- 运行IR程序,将`stdout`上的输出写入文件:
```
node irvm.mjs rand.ir > out.txt
```
- 运行IR程序,从文件读取输入,将`stdout`上的输出写入文件(Windows CMD/PowerShell环境):
```
node irvm.mjs rand.ir > rand.out
type in.txt | node irvm.mjs rand.ir > out.txt
```
- 运行IR程序,从文件读取输入,将`stdout`上的输出写入文件(PowerShell环境):
- 运行IR程序,从文件读取输入,将`stdout`上的输出写入文件(Linux环境):
```
type rand.in | node irvm.mjs rand.ir > rand.out
cat in.txt | node irvm.mjs rand.ir > out.txt
```
请注意,输入文件中,各个输入需要以换行分隔。同一行中的多个输入会被当成一次输入处理
虚拟机以流的方式读取输入,控制台或者输入文件中的各个数据之间可用任意空白符号分隔

## 一些设计理念与讨论
- **全局变量相互不能重名,同一函数内的变量、形参相互不能重名,函数内的变量、形参可以但不建议和全局变量重名,不同函数内的变量、形参可以但不建议重名**
Expand Down

0 comments on commit c96cc85

Please sign in to comment.