Skip to content

Docs

Jump to bottom
是雫雫酱呦 edited this page Feb 11, 2026 · 1 revision

HPL 语法文档

完整的语法参考和 API 文档

📋 目录

  1. 文件结构
  2. 数据类型
  3. 变量与操作符
  4. 控制流
  5. 函数与类
  6. 模块系统
  7. 异常处理
  8. 内置函数
  9. 标准库
  10. 快速参考卡

文件结构

HPL 程序以 YAML 文件形式编写，包含以下顶级键：

includes:   # 包含其他 HPL 文件
imports:    # 导入标准库模块
classes:    # 定义类
objects:    # 实例化对象
main:       # 主函数（程序入口）
call:       # 调用入口函数

最小程序结构

main: () => {
    echo "Hello, HPL!"
  }

call: main()

完整程序结构

# 1. 文件包含
includes:
  - utils.hpl

# 2. 模块导入
imports:
  - math
  - io

# 3. 类定义
classes:
  Calculator:
    add: (a, b) => {
        return a + b
      }

# 4. 对象实例化
objects:
  calc: Calculator()

# 5. 主函数
main: () => {
    result = calc.add(10, 20)
    echo "Result: " + result
  }

# 6. 程序入口
call: main()

数据类型

类型 示例 说明
整数 42, -10 整数值
浮点数 3.14, -0.5, 1.5e10 小数，支持科学计数法
字符串 "Hello", "Line\n" 双引号包围，支持转义
布尔值 true, false 真/假
空值 null 空值或未定义
数组 [1, 2, 3] 有序集合，索引从0开始
字典 {"a": 1, "b": 2} 键值对，键必须是字符串

数组操作

arr = [10, 20, 30]

# 访问元素
first = arr[0]      # 10

# 修改元素
arr[0] = 100        # [100, 20, 30]

# 数组拼接
newArr = arr + [40] # [100, 20, 30, 40]

# 获取长度
length = len(arr)   # 3

字典操作

person = {"name": "Alice", "age": 30}

# 访问元素
name = person["name"]  # "Alice"

# 修改/添加元素
person["age"] = 31
person["city"] = "Beijing"

# 遍历键
for (key in person) :
  echo key + ": " + person[key]

变量与操作符

变量赋值

x = 10              # 整数
pi = 3.14159        # 浮点数
name = "HPL"        # 字符串
flag = true         # 布尔值
data = null         # 空值

算术操作符

操作符 说明 示例
+ 加法/字符串拼接/数组拼接 10 + 20, "a" + "b", [1] + [2]
- 减法 20 - 10
* 乘法 5 * 6
/ 除法 10 / 3
% 取模 10 % 3
++ 后缀自增 i++
-x 一元负号 -5

比较操作符

操作符 说明
== 等于
!= 不等于
< 小于
> 大于
<= 小于等于
>= 大于等于

逻辑操作符

操作符 说明 示例
! 逻辑非 !flag
&& 逻辑与 a && b
|| 逻辑或 a || b

控制流

条件语句 (if-else)

if (condition) :
  # 条件为真时执行
  code
else :
  # 条件为假时执行
  code

示例：

score = 85
if (score >= 90) :
  grade = "A"
else :
  if (score >= 80) :
    grade = "B"
  else :
    grade = "C"

循环语句 (for in)

for (variable in iterable) :
  code

遍历范围：

for (i in range(5)) :
  echo i    # 输出 0, 1, 2, 3, 4

遍历数组：

arr = [10, 20, 30]
for (item in arr) :
  echo item

遍历字典（键）：

person = {"name": "Alice", "age": 30}
for (key in person) :
  echo key    # 输出 "name", "age"

遍历字符串：

text = "Hello"
for (char in text) :
  echo char   # 输出 H, e, l, l, o

While 循环

while (condition) :
  code

示例：

i = 0
while (i < 5) :
  echo i
  i++

Break 和 Continue

# break - 立即退出循环
for (i in range(10)) :
  if (i == 5) :
    break
  echo i

# continue - 跳过当前迭代
for (i in range(5)) :
  if (i == 2) :
    continue
  echo i

函数与类

顶层函数

functionName: (param1, param2) => {
    # 函数体
    return result
  }

示例：

add: (a, b) => {
    return a + b
  }

greet: (name) => {
    echo "Hello, " + name + "!"
  }

# 调用任意函数
call: add(5, 3)

类定义

classes:
  ClassName:
    # 构造函数（init 或 __init__）
    init: (param) => {
        this.property = param
      }
    
    # 方法定义
    methodName: () => {
        code
      }
    
    methodWithParams: (a, b) => {
        return a + b
      }

继承

classes:
  BaseClass:
    baseMethod: () => {
        code
      }

  DerivedClass:
    parent: BaseClass
    init: () => {
        this.parent.init()    # 调用父类构造函数
      }
    derivedMethod: () => {
        this.baseMethod()     # 调用父类方法
      }

对象实例化

objects:
  objectName: ClassName()
  objectWithParams: ClassName(arg1, arg2)

完整 OOP 示例

classes:
  Rectangle:
    init: (width, height) => {
        this.width = width
        this.height = height
      }
    
    getArea: () => {
        return this.width * this.height
      }

objects:
  rect: Rectangle(10, 5)

main: () => {
    area = rect.getArea()
    echo "Area: " + area    # 输出 50
  }

call: main()

模块系统

文件包含 (includes)

用于包含其他 HPL 源代码文件：

includes:
  - utils.hpl
  - subdir/helpers.hpl
  - ../common.hpl

模块导入 (imports)

用于导入标准库或第三方模块：

imports:
  - math
  - io
  - json
  - os
  - time

别名导入

imports:
  - math: m        # 使用 m 代替 math
  - time: t        # 使用 t 代替 time

main: () => {
    echo m.PI           # 使用别名访问
    echo t.now()
  }

模块使用示例

imports:
  - math
  - io
  - json

main: () => {
    # math 模块
    result = math.sqrt(16)
    
    # io 模块
    content = io.read_file("data.txt")
    io.write_file("output.txt", "Hello")
    
    # json 模块
    data = json.parse('{"a": 1}')
    json.write("data.json", data)
  }

异常处理

Try-Catch

try :
  # 可能出错的代码
  code
catch (error) :
  # 错误处理
  code

Throw 语句

try :
  if (x == 0) :
    throw "除数不能为零"
  result = 10 / x
catch (error) :
  echo "错误: " + error

嵌套异常处理

try :
  echo "外层 try"
  try :
    throw "内层错误"
  catch (innerError) :
    echo "内层捕获: " + innerError
catch (outerError) :
  echo "外层捕获: " + outerError

内置函数

输入输出

函数 说明 示例
echo value 输出到控制台 echo "Hello"
input() 获取用户输入 name = input()
input(prompt) 带提示的输入 age = input("Enter age: ")

类型转换

函数 说明 示例
int(value) 转为整数 int("123") → 123
str(value) 转为字符串 str(42) → "42"

数组/字符串操作

函数 说明 示例
len(arr_or_str) 获取长度 len([1,2,3]) → 3
type(value) 获取类型 type(42) → "int"

数值函数

函数 说明 示例
abs(x) 绝对值 abs(-42) → 42
max(a, b, ...) 最大值 max(10, 20, 5) → 20
min(a, b, ...) 最小值 min(10, 20, 5) → 5

标准库

math 模块 - 数学函数

常量

常量 值 说明
math.PI 3.14159... 圆周率
math.E 2.71828... 自然常数 e
math.TAU 6.28318... 2*PI
math.INF ∞ 正无穷大
math.NAN NaN 非数字

函数

函数 参数 返回值 说明
math.sqrt(x) number float 平方根
math.pow(base, exp) number, number float 幂运算
math.abs(x) number number 绝对值
math.max(a, b, ...) number... number 最大值
math.min(a, b, ...) number... number 最小值
math.sin(x) number (弧度) float 正弦
math.cos(x) number (弧度) float 余弦
math.tan(x) number (弧度) float 正切
math.log(x, base?) number, number? float 对数
math.exp(x) number float e 的 x 次幂
math.floor(x) number int 向下取整
math.ceil(x) number int 向上取整
math.round(x, ndigits?) number, int? number 四舍五入

io 模块 - 文件操作

函数 说明
io.read_file(path) 读取文件内容为字符串
io.write_file(path, content) 写入字符串到文件
io.append_file(path, content) 追加字符串到文件
io.file_exists(path) 检查文件是否存在
io.get_file_size(path) 获取文件大小（字节）
io.delete_file(path) 删除文件
io.create_dir(path) 创建目录
io.list_dir(path) 列出目录内容（返回数组）

json 模块 - JSON 处理

函数 说明
json.parse(json_str) 解析 JSON 字符串为 HPL 值
json.stringify(value, indent) 将 HPL 值转为 JSON 字符串
json.read(path) 从文件读取并解析 JSON
json.write(path, value, indent) 将值写入 JSON 文件
json.is_valid(json_str) 检查字符串是否为有效 JSON

os 模块 - 操作系统接口

函数 说明
os.get_env(name, default) 获取环境变量
os.set_env(name, value) 设置环境变量
os.get_cwd() 获取当前工作目录
os.change_dir(path) 改变当前目录
os.get_platform() 获取操作系统平台
os.cpu_count() 获取 CPU 核心数
os.execute(command) 执行系统命令
os.exit(code) 退出程序

time 模块 - 日期时间处理

函数 说明
time.now() 获取当前时间戳（秒）
time.now_ms() 获取当前时间戳（毫秒）
time.sleep(seconds) 休眠指定秒数
time.format(timestamp, format) 格式化时间
time.get_year(timestamp) 获取年份
time.get_month(timestamp) 获取月份 (1-12)
time.get_day(timestamp) 获取日期 (1-31)

快速参考卡

┌─────────────────────────────────────────────────────────┐
│  HPL 语法快速参考                                        │
├─────────────────────────────────────────────────────────┤
│  数据类型: int, float, string, bool, array, dict         │
│  变量: x = 10                                           │
│  数组: arr = [1, 2, 3], arr[0], arr + [4]               │
│  字典: d = {"a": 1}, d["a"], d["b"] = 2                 │
├─────────────────────────────────────────────────────────┤
│  算术: +  -  *  /  %  ++  -x                             │
│  比较: ==  !=  <  >  <=  >=                              │
│  逻辑: !  &&  ||                                         │
├─────────────────────────────────────────────────────────┤
│  条件: if (cond) : ... else : ...                        │
│  循环: for (i in range(n)) : ...                         │
│        for (item in arr) : ...                           │
│        while (cond) : ...                                │
│  控制: break, continue                                   │
├─────────────────────────────────────────────────────────┤
│  函数: func: (p) => { return x }                         │
│  类:   Class: { init: () => { ... } }                    │
│  继承: parent: BaseClass                                │
│  对象: obj: Class()                                     │
├─────────────────────────────────────────────────────────┤
│  包含: includes: [- file.hpl]                           │
│  导入: imports: [- math, - io]                          │
│  别名: imports: [- math: m]                             │
├─────────────────────────────────────────────────────────┤
│  异常: try : ... catch (e) : ...                       │
│  抛出: throw "message"                                  │
├─────────────────────────────────────────────────────────┤
│  内置: echo, input, len, type, int, str                 │
│        abs, max, min, range                             │
└─────────────────────────────────────────────────────────┘

完整示例

# 文件包含和模块导入
includes:
  - base.hpl

imports:
  - math: m

# 类定义
classes:
  Calculator:
    init: () => {
        this.result = 0
      }
    
    add: (n) => {
        this.result = this.result + n
        return this.result
      }
    
    getResult: () => {
        return this.result
      }

# 对象实例化
objects:
  calc: Calculator()

# 主函数
main: () => {
    try :
      calc.add(10)
      calc.add(20)
      echo "Result: " + calc.getResult()
      
      # 使用 math 模块
      echo "PI: " + m.PI
      echo "sqrt(16): " + m.sqrt(16)
      
    catch (error) :
      echo "Error: " + error
  }

# 程序入口
call: main()

注意事项

  • HPL 基于 YAML，缩进至关重要（建议使用 2 个空格）
  • 字符串使用双引号包围，支持转义序列（\n, \t, \\, \"）
  • 代码块使用大括号 {} 包围，内部使用缩进组织
  • 控制流语句使用冒号 : 表示代码块开始
  • 数组索引从 0 开始
  • 逻辑运算符 && 和 || 具有短路求值特性

导航

提示: 更多详细信息请参考 HPL语法概览.md 和 HPL语法手册.md

Clone this wiki locally