docs(*): update a new document

1. change the naming convention of codes
2. update a new document
please refer to the work log for details

Author: CLimber-Rong

.vscode/settings.json

@@ -70,7 +70,8 @@
         "stop_token": "cpp",
         "thread": "cpp",
         "regex": "cpp",
-        "valarray": "cpp"
+        "valarray": "cpp",
+        "typeindex": "cpp"
     },
     "C_Cpp.errorSquiggles": "disabled",
 }

demos/demo.stvc

@@ -0,0 +1,146 @@
+# Stamon错误及警告信息修复指南
+
+用户在编写代码时，若出现编译期或运行时错误（或警告），本指南就可以提供更详细的解释信息以及修复方向。
+
+## 编译端有关信息
+
+### 错误信息
+
+#### the string was entered incorrectly
+
+字符串格式有误。例如转义字符输入错误时有可能触发此错误。请检查字符串是否由一对双引号包裹，转义字符是否输入正确。
+
+#### the floating point was entered incorrectly
+
+浮点数输入错误。当小数点后没有跟着数字时，会触发此错误，请检查浮点数的输入格式是否正确。
+
+#### unknown token: 'XXX'
+
+未知的词法单元。当用户输入非法字符（例如英文问号）时会触发此错误，请检查代码中是否包含非法字符。
+
+#### invalid syntax
+
+综合语法错误。该报错的触发条件多种多样，在Stamon的语法当中，会出现一些固定的语法搭配，当用户输入的语法搭配与规定的不一致时，会触发此错误，例如语句末尾未加分号。请用户根据编译器报告的错误位置，对照《Stamon语法教程手册》，检查语法搭配是否一致。值得注意的是：有些错误实际需要解决的位置，或许和编译器报告的错误位置并不完全一样，但两者肯定存在对应关系，所以请用户认真检查错误位置所在行及其关联的代码是否有误。
+
+#### variable "XXX" are declared repeatedly
+
+变量被重复强定义。关于“强定义”的解释可以参照《Stamon语法教程手册》中的相关内容。对于此类错误，推荐一种解决方案——**前置定义设计**：
+先为专门建立一个源码文件（被称为前置定义文件），并使用**def**关键字来强定义所有全局标识符（即前置定义）；并在其他源文件的开头先引用这个前置定义文件，在其他源文件中，不直接使用**def**关键字来强定义全局标识符，而是采用直接赋值或弱定义的形式。这种代码设计思路，可以确保所有全局标识符只被强定义一次。对于局部标识符，请确保最多被强定义一次。有关如何使用强定义、弱定义和赋值，也可以参照《Stamon语法教程手册》中的相关内容。值得注意的是：请确保需要用到的全局标识符在**def**之后有相关的实现，否则在使用被强定义但未赋值的标识符时，会出现对空值进行操作的情况，从而引起运行时错误。
+
+#### the port or argument of the SFN statement must be an identifier
+
+SFN语句的端口或参数必须是标识符。有关“SFN语句”的解释可以参照《Stamon语法教程手册》中的相关内容。
+
+#### 'continue' outside loop
+
+continue语句在循环体外。continue语句作为循环流程控制相关的语句，必须在循环语句之内出现。
+
+#### 'break' outside loop
+
+break语句在循环体外。break语句作为循环流程控制相关的语句，必须在循环语句之内出现。
+
+#### the member name must be an identifier
+
+类成员名必须是标识符。有关标识符的命名规范可以参照《Stamon语法教程手册》中的相关内容。
+
+#### the name of the variable must be an identifier
+
+变量名必须是标识符。有关标识符的命名规范可以参照《Stamon语法教程手册》中的相关内容。
+
+#### the brace are not closed
+
+花括号未闭合，请检查错误位置及其关联位置是否存在未闭合的花括号对。
+
+#### the square bracket are not closed
+
+方括号未闭合，请检查错误位置及其关联位置是否存在未闭合的方括号对。
+
+#### the round bracket are not closed
+
+圆括号未闭合，请检查错误位置及其关联位置是否存在未闭合的圆括号对。
+
+#### only functions, classes and variables can be defined in a class
+
+类定义中，只能定义成员函数、成员类和成员变量。有关类定义的规范可以参照《Stamon语法教程手册》中的相关内容。
+
+#### cannot import
+
+不能引用其他源码。只有当编译器被指定为不能引用其他文件的模式，并且源码中调用了其他文件时，才会触发此错误。有关参数指定的内容可以参照《Stamon发行版使用指南》。
+
+#### the left operand of an assignment must be an lvalue
+
+表达式的左操作数必须是左值。引用《Stamon语法教程手册》中的注意事项：“请确保赋值的左操作数是左值，其中对左值的严格定义是：一个变量取任意次元素和成员的表达式”。
+
+#### undefined variable: "XXX"
+
+未定义变量。请在使用变量前先使用强定义或弱定义的方式定义变量。
+
+### 警告信息
+
+#### the integer is too large
+
+整数过大从而导致溢出。这会导致程序执行时出现数值与代码中数值不同的情况。
+
+#### the floating point is too large
+
+浮点数过大从而导致溢出。这会导致程序执行时出现数值与代码中数值不同的情况。
+
+## 运行端（AstRunner）有关信息
+
+### 错误信息
+
+#### an error of data type 'XXX' occurred in the calculation
+
+错误的数据类型被参与计算。例如字符串与整数相加时会触发此错误。
+
+#### unknown type of postfix
+
+未知后缀类型。这是运行端内部错误，请检查传递给运行端的二进制文件是否合理。
+
+#### list index out of range
+
+数列访问越界。当访问的下标大等于数列长度时会触发此错误。
+
+#### wrong index of constants
+
+错误的常量表下标。这是运行端内部错误，请检查传递给运行端的二进制文件是否合理。
+
+#### division by zero
+
+零作为除数。请检查运算过程中是否出现零作为除数的现象。
+
+#### 'continue' outside loop
+
+continue语句在循环体外。continue语句作为循环流程控制相关的语句，必须在循环语句之内出现。原则上该报错会在编译端出现，因此如果运行端才出现此报错，请检查编译端是否正常，以及传递给运行端的二进制文件是否合理。
+
+#### 'break' outside loop
+
+break语句在循环体外。break语句作为循环流程控制相关的语句，必须在循环语句之内出现。原则上该报错会在编译端出现，因此如果运行端才出现此报错，请检查编译端是否正常，以及传递给运行端的二进制文件是否合理。
+
+#### takes A form arguments but B was given
+
+调用该函数需要A个参数，但传递了B个参数。请检查调用函数的过程中是否出现参数传递错误。
+
+#### 'return' outside function
+
+return语句在函数外。return语句作为函数相关的语句，必须在函数体之内出现。
+
+#### unknown operator
+
+未知运算符。这是运行端内部错误，请检查传递给运行端的二进制文件是否合理。
+
+#### object has no member 'XXX'
+
+对象没有名为XXX的成员，请检查成员标识符是否输入正确
+
+#### the length must be non-negative
+
+长度必须是非负数。请检查申请数列的长度是否是负数。
+
+#### negative shift count
+
+负数位移。位移运算中的位移数必须是非负数，请检查位移运算中的位移数是否是负数。
+
+### 警告信息
+
+暂无。

demos/demo1.stvc

@@ -15,19 +15,19 @@ Stamon目前支持以下指令：
 
 <br>
 
-* ``stamon version``
+* ``stamon version``或``stamon -v``
 
 该指令用于输出Stamon当前的版本号。
 
 <br>
 
-* ``stamon help``
+* ``stamon help``或``stamon -h``
 
 该指令用于输出Stamon的用法以及各种参数的介绍。
 
 <br>
 
-* ``stamon build [src] [dst] [options...]``
+* ``stamon build [src] [dst] [options...]``或``stamon -b [src] [dst] [options...]``
 
 该指令用于编译Stamon代码，其中src为必要参数，表示编译的Stamon文件名，dst为可选参数，表示生成的字节码文件名（默认a.stvc），options为可选参数，他们包括：
 
@@ -44,7 +44,7 @@ Stamon目前支持以下指令：
 
 <br>
 
-* ``stamon run [src] [options...]``
+* ``stamon run [src] [options...]``或``stamon -r [src] [options...]``
 
 该指令用于运行STVC文件，其中src为必要参数，表示编译的Stamon文件名，options为可选参数，他们包括：
 
@@ -60,9 +60,14 @@ Stamon目前支持以下指令：
 
 <br>
 
-* ``stamon strip [src]``
+* ``stamon strip [src] [options...]``或``stamon -s [src]``
 
-该指令用于剥削STVC调试信息，其中src为必要参数，表示待剥削的STVC文件。
+该指令用于剥削STVC调试信息，其中src为必要参数，表示待剥削的STVC文件，options为可选参数，他们包括：
 
+|参数用法|功能|默认值|支持此参数的最低版本|
+|-|-|-|-|
+|--IgnoreWarning|忽略警告|默认只进行警告|2.4.28|
+|--JustWarn|只进行警告|默认只进行警告|2.4.28|
+|--FatalWarning|将警告作为致命错误|默认只进行警告|2.4.28|
 
 > ——摘自``工作日志/20240616.md``，有改动

demos/demo2.stvc

@@ -0,0 +1,15 @@
+# 2025/04/06 工作日志
+
+本次更新不会修改任何版本。
+
+### 对报错信息进行调整
+
+细化报错信息，让用户可以更具体的知道错误所在的位置以及修复方法。同时整理了一些遗漏的报错信息。
+
+### 修改了命名规范，微调了代码
+
+对于``Lexer.cpp``中对Token编号的命名进行了微调，``Compiler.cpp``也进行了微调。
+
+### 提交新的文档
+
+上传了``Stamon错误及警告信息修复指南.md``，该指南能给用户提供错误信息的解释和修复方向。

doc/Stamon错误及警告信息修复指南.md

@@ -19,7 +19,6 @@ class Compiler {
 	STMException *ex;
 	ArrayList<String> *ErrorMsg;
 	ArrayList<String> *WarningMsg;
-	bool ImportFlag = false;
 
 	Compiler() {
 	}
@@ -30,10 +29,10 @@ class Compiler {
 		src = right.src;
 		ex = right.ex;
 		ErrorMsg = right.ErrorMsg;
-		ImportFlag = right.ImportFlag;
 	}
 
-	Compiler(STMException *e, ArrayList<String> *error_msg, ArrayList<String> *warning_msg)
+	Compiler(STMException *e, ArrayList<String> *error_msg,
+			 ArrayList<String> *warning_msg)
 		: filemap(e)
 		, global_scope(e) {
 
@@ -45,7 +44,6 @@ class Compiler {
 	}
 
 	void compile(String filename, bool isSupportImport) {
-		ImportFlag = isSupportImport;
 
 		LineReader reader = filemap.mark(filename);
 
@@ -98,7 +96,8 @@ class Compiler {
 
 		Matcher matcher(lexer, ex);
 		Parser *parser = new Parser(
-				matcher, ex, global_scope, filename, src, filemap, ErrorMsg, ImportFlag);
+				matcher, ex, global_scope, filename, src, filemap, ErrorMsg,
+				isSupportImport);
 
 		ast::AstNode *node = parser->Parse(); // 语法分析
 

doc/发行版使用指南.md

@@ -99,12 +99,12 @@ namespace stamon::c {   //编译器命名空间
 	    KEYWORDS_MAX,   //关键词个数
 	    TokenAssign,//赋值
 	    TokenSemi,  //分号
-	    TokenLBC,   //左花括号
-	    TokenRBC,   //右花括号
-	    TokenLBR,   //左括号
-	    TokenRBR,   //右括号
-	    TokenLSB,   //左方括号
-	    TokenRSB,   //右方括号
+	    TokenLBC,   //左花括号（Left BraCe）
+	    TokenRBC,   //右花括号（Right BraCe）
+	    TokenLRB,   //左括号（Left Round Bracket）
+	    TokenRRB,   //右括号（Right Round Bracket）
+	    TokenLSB,   //左方括号（Left Square Bracket）
+	    TokenRSB,   //右方括号（RightSquare Bracket）
 	    TokenCmm,   //逗号
 	    TokenColon,	//冒号
 	    TokenMember,//小数点
@@ -540,8 +540,8 @@ namespace stamon::c {   //编译器命名空间
 						CHECK_OPERATOR(';', TokenSemi)
 						CHECK_OPERATOR('{', TokenLBC)
 						CHECK_OPERATOR('}', TokenRBC)
-						CHECK_OPERATOR('(', TokenLBR)
-						CHECK_OPERATOR(')', TokenRBR)
+						CHECK_OPERATOR('(', TokenLRB)
+						CHECK_OPERATOR(')', TokenRRB)
 						CHECK_OPERATOR('[', TokenLSB)
 						CHECK_OPERATOR(']', TokenRSB)
 						CHECK_OPERATOR(',', TokenCmm)