Lexical Structure - HimxhMC/HimDSL GitHub Wiki

词法结构 / Lexical Structure

什么是词法 / What Lexical Means

写脚本的时候，你看到的是"一行行代码"。但在解析器眼里，代码首先是一串字符，然后被切分成一个个最小的意义单位——注释、数字、字符串、标识符、符号。这一层称为词法。本章讲的就是这一层里你需要知道的规则：怎么写注释、怎么写数字、怎么写字符串、名字该怎么起。

When you write a script, you see "lines of code." But to the parser, code is first a stream of characters, then chopped into minimal meaningful units — comments, numbers, strings, identifiers, symbols. This layer is called the lexicon. This chapter covers the rules you need at that layer: comments, number literals, string literals, and naming.

注释 / Comments

HimDSL 支持两种注释，写法与 Java 完全一致。

HimDSL supports two comment styles, identical to Java.

// 单行注释，从 // 到行尾全部忽略

/*
   多行注释
   可以跨越多行
*/

注释会被解析器直接丢弃，不产生任何运行时开销。写脚本时尽量给复杂逻辑加注释，尤其是给未来的自己看。

Comments are discarded by the parser and produce no runtime overhead. Comment complex logic liberally, especially for your future self.

标识符 / Identifiers

标识符是你给变量、函数、结构体、枚举起的名字。规则是：

  • 首字符必须是字母或下划线。
  • 后续字符可以是字母、数字或下划线。
  • 大小写敏感。

Identifiers name variables, functions, structs, and enums. Rules:

  • First character must be a letter or underscore.
  • Following characters may be letters, digits, or underscores.
  • Case-sensitive.
int hp = 20;          // ✓
int _temp = 0;        // ✓
int hpMax = 100;      // ✓
int 1hp = 20;         // ✗ 不能以数字开头
int my-var = 0;       // ✗ 中划线不合法

推荐用驼峰命名法（farmTimer、playerCount），与 Java 习惯一致。中文标识符目前不支持，请用英文。

Prefer camelCase (farmTimer, playerCount) as in Java. Chinese identifiers are currently not supported; use English.

数字字面量 / Number Literals

HimDSL 的数字字面量只有一种语法：可选的负号、整数部分、可选的小数部分。

HimDSL has one numeric literal syntax: an optional sign, an integer part, and an optional fractional part.

int a = 42;
int b = 0;
double c = 3.14;
double d = 0.5;
int neg = -7;

注意几点：

  • 不支持科学计数法（1e5 会报错），需要的话请写全数字。
  • 不支持十六进制、八进制、二进制字面量。
  • 不支持下划线分隔（1_000 会报错）。
  • 小数部分必须紧跟小数点，1. 和 .5 都不合法，请写 1.0 和 0.5。

Notes:

  • No scientific notation (1e5 errors); write the digits out.
  • No hex, octal, or binary literals.
  • No underscore separators (1_000 errors).
  • The fractional part must follow the dot directly; 1. and .5 are both invalid — write 1.0 and 0.5.

数字默认为 int（整数）或 double（带小数点）。整数字面量如果超出 int 范围，实际会被解析为 double，这一点在跟 Java 交互时需要注意。

Numbers are int (whole) or double (with a fractional part). An integer literal that exceeds the int range is parsed as double, worth remembering when interoperating with Java.

字符串字面量 / String Literals

字符串用双引号包围。字符串可以包含任意字符，包括中文。特殊字符通过反斜杠转义表示。

Strings are wrapped in double quotes. They may contain any character, including Chinese. Special characters use backslash escapes.

string s1 = "Hello";
string s2 = "你好，世界";
string s3 = "第一行\n第二行";
string s4 = "带引号：\"引号\"";
string s5 = "路径：C:\\Users\\Steve";

支持的转义序列有：

转义 含义
\n 换行
\t 制表符
\r 回车
\" 双引号
\\ 反斜杠

Supported escapes:

Escape Meaning
\n newline
\t tab
\r carriage return
\" double quote
\\ backslash

其他以反斜杠开头的组合不会报错，但反斜杠会被保留。所以写 "a\qb" 得到的是 a\qb，不会变成别的。

Other backslash combinations do not error, but the backslash is preserved. So "a\qb" yields a\qb, not something else.

字符串中可以直接写 § 加上颜色代码（例如 "§c红色警告"），Minecraft 客户端会渲染颜色。这在广播消息时很常用。

You may write § color codes directly inside strings (e.g. "§cRed warning"); the Minecraft client renders the color. This is common in broadcast messages.

字符字面量 / Character Literals

单个字符用单引号包围：

A single character is wrapped in single quotes:

char c = 'A';
char zh = '中';
char nl = '\n';

字符与字符串的区别：字符是单个，字符串是一串。字符主要用在处理文本的场合，例如读取玩家名里的第一个字母。日常脚本里用到字符的机会不多。

The difference between a character and a string: a character is one character, a string is a sequence. Characters mainly appear when processing text, such as reading the first letter of a player name. Everyday scripts rarely need them.

关键字 / Keywords

下面这些词是 HimDSL 的保留字，不能用作变量名、函数名或标识符：

Below are HimDSL reserved words; they cannot be used as variable, function, or identifier names:

var       player    world     server    boss      haveVar
enum      struct    static    new
int       double    bool      string    void
if        else      for       while     do
return    true      false     null

保留字大小写敏感，例如 if 是关键字，If 和 IF 是普通标识符。不过为了避免混淆，建议不要用与关键字只差大小写的名字。

Reserved words are case-sensitive: if is a keyword, while If and IF are ordinary identifiers. Still, avoid names that differ from a keyword only by case, to prevent confusion.

player 这个关键字比较特殊，允许小写 p 开头的 Player 也是合法的声明关键字——不过建议统一用小写 player。

The player keyword is special: Player (capital P) is also accepted. Stick to lowercase player for consistency.

分号与空白 / Semicolons and Whitespace

HimDSL 的语句以分号结尾。函数声明、if、for、while 的外层不带分号，但内部的每条语句都带分号。

HimDSL statements end with semicolons. Function declarations and the outer layer of if / for / while do not end with semicolons, but every statement inside them does.

int main() {              // 函数声明，无分号
    int x = 5;            // 变量声明，有分号
    if (x > 0) {          // if 外层，无分号
        x = x + 1;        // 内部语句，有分号
    }
    return 0;             // return 有分号
}

空白字符（空格、制表符、换行）被完全忽略。你可以把语句写成一行，也可以折成多行。缩进只是给人看的，编译器不在乎。

Whitespace (spaces, tabs, newlines) is entirely ignored. You may put statements on one line or split them across many. Indentation is for humans only; the compiler does not care.

小结 / Summary

  • 注释用 // 或 /* */。

  • 标识符用字母或下划线开头，大小写敏感。

  • 数字不支持科学计数法、十六进制、下划线分隔。

  • 字符串用双引号，支持 \n \t \r \" \\ 五种转义。

  • 字符用单引号。

  • 语句以分号结尾，函数和 if 外层不带分号。

  • Comments: // or /* */.

  • Identifiers start with a letter or underscore; case-sensitive.

  • Numbers: no scientific notation, hex, or separators.

  • Strings use double quotes; five escapes supported.

  • Characters use single quotes.

  • Statements end with semicolons; function and if outer layers do not.

下一步 / Next Steps

下一章 [变量与类型 / Variables-and-Types] 进入语言的核心：怎么声明变量、有哪些类型、什么时候用 var、类型不对会发生什么。

Next, [变量与类型 / Variables-and-Types] covers the core: how to declare variables, what types exist, when to use var, and what happens on type mismatches.