Enums - HimxhMC/HimDSL GitHub Wiki

enum 用户枚举 / User Enums

枚举是什么 / What an Enum Is

枚举定义一组有限的取值。例如"红绿蓝"、"上右下左"、"待机/运行/停止"。用枚举比用字符串更安全——拼错了会报错，不会静默失败。

An enum defines a finite set of values: red/green/blue, up/right/down/left, idle/running/stopped. Enums beat strings because typos error instead of failing silently.

对比：

Compare:

// 用字符串：拼错了不会报错，逻辑默默失效
string state = "runing";        // 少了一个 n
if (state == "running") { ... }  // 永远不成立

// 用枚举：拼错了直接报错
var state = State.RUNNING;
if (state == State.RUNING) { ... }  // ✗ 编译或运行时能发现

定义枚举 / Defining an Enum

语法：

Syntax:

enum 名称 {
    常量1,
    常量2,
    常量3,
};

例子：

Example:

enum State {
    IDLE,
    RUNNING,
    STOPPED,
};

结尾的分号不能省。逗号在最后一个常量后面可以省略，也可以保留：

The trailing semicolon is mandatory. The comma after the last constant is optional:

enum Color {
    RED,
    GREEN,
    BLUE        // 最后一个常量后可以不加逗号
};

使用枚举 / Using an Enum

用 枚举名.常量名 引用：

Reference with EnumName.CONSTANT:

State s = State.IDLE;
Color c = Color.RED;

也可以配合 var：

Or with var:

var s = State.RUNNING;
var c = Color.BLUE;

比较 / Comparison

枚举常量之间用 == 比较：

Compare constants with ==:

if (s == State.RUNNING) {
    runcmd("CONSOLE", "say 正在运行");
}

与字符串比较 / Comparison with Strings

用户枚举与字符串可以直接比较，这一点是特地为脚本场景设计的，读起来更自然：

User enums compare directly with strings, a script-friendly feature:

if (s == "RUNNING") {
    runcmd("CONSOLE", "say 正在运行");
}

上例等价于 if (s == State.RUNNING)。两种写法都合法，推荐用枚举常量形式——拼错会报错，更安全。

The above equals if (s == State.RUNNING). Both work; prefer the constant form for typo safety.

一个完整的例子 / A Complete Example

用枚举实现一个简单的状态机：

A simple state machine with an enum:

enum State {
    IDLE,
    ACTIVE,
    FINISHED,
};

State current;

void setState(State s) {
    current = s;
    runcmd("CONSOLE", "say 状态: " + s.toString());
}

int main() {
    setState(State.IDLE);
    setState(State.ACTIVE);
    setState(State.FINISHED);

    if (current == State.FINISHED) {
        runcmd("CONSOLE", "say 任务完成");
    }
}

toString 返回形如 State.FINISHED 的文本，方便打印。

toString returns text like State.FINISHED, easy to print.

内置方法 / Built-in Methods

用户枚举提供几个常用方法：

User enums provide a few common methods:

var c = Color.RED;

string name = c.name();         // "RED"
string type = c.type();         // "Color"
string text = c.toString();     // "Color.RED"
bool same = c.equals("RED");    // true

name() —— 常量名。
type() —— 枚举类型名。
toString() —— 类型名.常量名。
equals(x) —— 与常量名或另一个常量比较。
name() — the constant name.
type() — the enum type name.
toString() — TypeName.CONSTANT.
equals(x) — compare against a name or another constant.

与 Java 枚举的关系 / Relation to Java Enums

HimDSL 里的枚举大部分来自 Java，例如：

Most enums in HimDSL come from Java, e.g.:

Material.DIAMOND
GameMode.CREATIVE
WeatherType.CLEAR

这些是 Java 枚举，行为和你自己定义的 enum 类似，也支持 name()、toString()、与字符串比较。

These are Java enums. They behave like your own enum: name(), toString(), and string comparison work the same.

区别在于：Java 枚举可能提供额外的方法，比如 Material.isItem()、GameMode.getName()——这些方法在用户枚举里没有。

The difference: Java enums may offer extra methods like Material.isItem() or GameMode.getName() — user enums do not.

什么时候用枚举 / When to Use Enums

用枚举的场景 / Good for

状态机：IDLE / RUNNING / DONE。
固定选项：颜色、方向、难度。
替代魔法字符串：避免 "running" 这种容易拼错的文本。
State machines: IDLE / RUNNING / DONE.
Fixed options: colors, directions, difficulty.
Replacing magic strings: avoid typo-prone "running".

不用枚举的场景 / Not for

用户输入的文本：那是字符串，不是枚举。
会动态增长的集合：枚举是编译期固定的。
需要附加数据：枚举只存"是哪个常量"，附加数据放到结构体里。
User-entered text: that is a string.
Dynamically growing sets: enums are fixed at declaration.
Extra data per value: put that in a struct.

默认用字符串，只有出现"有限集合"时再考虑枚举。不要在脚本里把什么都塞进枚举，那样反而更麻烦。

Default to strings. Consider an enum only for a finite set. Do not force every value into an enum; that makes scripts harder to maintain.

小结 / Summary

定义：enum 名称 { 常量1, 常量2, ... };，结尾分号。
引用：名称.常量。
常量之间用 == 比较，也能与字符串比较。
内置方法：name / type / toString / equals。
用户枚举与 Java 枚举用法相似。
适合固定、有限的取值集合，不适合动态数据。
Define: enum Name { A, B, ... }; with a trailing semicolon.
Reference: Name.CONSTANT.
Compare with ==; strings also work.
Built-ins: name / type / toString / equals.
User enums behave like Java enums.
Ideal for fixed, small sets; not for dynamic data.

下一步 / Next Steps

下一章 [Java 互操作 / Java-Interop] 介绍如何从脚本创建 Java 对象、调用静态方法、引用 Java 枚举。

Next, [Java 互操作 / Java-Interop] shows creating Java objects, calling static methods, and referencing Java enums from scripts.