模块与导入¶
本页描述当前实现的模块系统,对应 OP 0006。本版只支持由 Oort 编写的
.ort模块;宿主语言模块与跨语言 FFI 不在范围内。oort-core的同方言导入/接口见 11-core-probe.md。
模块身份¶
- 一个
.ort文件是一个模块。 - 模块名由文件路径决定,模块内容不需要(也不能)声明模块名。
- 同一个文件在一次运行中只编译、初始化一次;重复导入得到同一个模块对象。
- 缓存键是解析后的规范路径。
./a、./sub/../a.ort等写法指向同一文件时 共享缓存。
语法¶
import "./lib" # 绑定到 lib(文件名去掉 .ort)
import "./lib" as l # 绑定到 l
from "./lib" import a, b as c # 绑定 a 与 c
import只能出现在模块顶层。函数、块、类体中的import报Imports are only allowed at module top level.。- 顶层
import会被提升到模块最前执行:所有导入先按源码顺序完成解析与 初始化,然后才执行其余顶层语句(与 ES 模块、Go 的依赖初始化顺序一致)。 import "<spec>"的默认绑定名是路径最后一段去掉.ort。若该名字不是 合法标识符,必须使用as给出别名。- 所有顶层名字默认公开;导入进模块的名字也留在模块命名空间中,因此会 自动再导出。
扩展方法的导入¶
扩展不是普通名字,导入规则单独定义:
import "m"与from "m" import x都会激活模块m顶层定义的扩展 方法与扩展运算符。- 只激活
m本地定义的扩展;m自己导入的扩展不会传递式再导出。 - 扩展不是模块属性,不参与
from "m" import ...,也不出现在模块命名空间中。 - 同一作用域导入多个模块时,同类型同名的候选在使用点报歧义;详见 扩展方法。
路径解析¶
设入口文件所在目录为项目根(字符串输入与 REPL 使用当前工作目录)。
| 写法 | 解析方式 |
|---|---|
./x、../x |
相对当前模块所在目录 |
io、math、os、string |
内置原生标准库模块(优先于同名文件) |
x、lib/x |
依次在项目根、--module-path 目录中查找 |
x.ort |
保留扩展名;省略扩展名时自动补 .ort |
规则细节:
- 裸模块名不会在当前导入者目录中隐式查找;需要导入者相对路径时显式写
./或../。 io/math/os/string是运行时内部的原生标准库名称(见 08-stdlib.md);import "./math"仍可加载本地文件。 这不是用户可用的宿主模块/FFI 机制。- 其他扩展名(如
x.py)会被拒绝:模块路径只接受.ort或省略扩展名。 - 目录模块(
pkg/、pkg/__init__.ort)尚未支持,命中目录会报错。 - OS 绝对路径(
C:\...、/...)尚未支持;用./、../或--module-path指定位置。 - 找不到模块时,诊断会列出所有尝试过的路径。
CLI 可以用可重复的 -I/--module-path DIR 增加搜索目录:
--module-path 是正式名称;Oort 的 -I 与 Python 的 -I(isolated mode)
含义不同。
初始化与缓存¶
- 导入是急切的:
import解析后立即编译并执行模块顶层语句。 - 每个已加载模块只初始化一次;模块对象是命名空间的只读视图:
lib.x读取当前值,但lib.x = ...会被拒绝(native 对象不可写)。 - 内建名字不是模块属性:
lib.print不存在。 - 模块级变量可以重新赋值;模块顶层也允许重复
var声明(与入口模块的 顶层规则一致)。 - 循环导入在首版被禁止:
Circular import detected: main.ort -> a.ort -> main.ort.。 含入口文件参与的环同样会报告。
方言¶
- 每个模块独立解析首行
#lang。被导入模块可以是显式的#lang oort-object,也可以省略(缺省即oort-object)。 oort-core模块可以导入其他oort-core模块;导出接口由静态检查器 读取,支持import "m"/from "m" import ...与再导出。详见 11-core-probe.md。- object↔core 双向导入仍被拒绝;加载器在编译后比较导入方与目标模块的 方言,不同则提示需要显式 FFI 边界。跨方言调用见 OP 0005 的后续工作。
- 原生模块(
io/math/os/string)仍只对oort-object可用; core 导入 native 模块会报错。
导入错误¶
| 情况 | 诊断 |
|---|---|
| 模块不存在 | Cannot find module '...',列出搜索路径 |
| 目录模块 | Directory modules are not supported |
| 其他扩展名 | Module path '...' must use the .ort extension or none. |
from 缺少名字 |
Module '...' does not export '...' |
| 模块编译失败 | 模块自身诊断 + Failed to import module '...': compilation failed. |
| 循环导入 | Circular import detected: ... |
| 非顶层 import | Imports are only allowed at module top level. |
被导入模块中的语法、语义与运行时错误会带该模块的文件名与行号;运行时错误 不会改写成导入处的错误。
非目标(本版)¶
- 导入 Python/C 等宿主模块;未来通过独立提案的
foreign/ 宿主边界提供。 标准库的io/math/os/string是运行时内部的原生模块,不是用户 可加载的宿主模块。 - 目录包与包清单(
__init__.ort、oort.toml等)。 import lazy惰性导入(设计笔记 06 的后续方向,文法尚未提供)。- 标准库的
.ort源码模块;最小标准库见 08-stdlib.md。