Skip to main content

Documentation Index

Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt

Use this file to discover all available pages before exploring further.

扩展函数把 target::method() 映射到 Java 侧实现，用于为特定宿主类型增加上下文能力（文件、集合、游戏对象等）。 核心代码分布在 FluxonRuntime、ExtensionBuilder、Environment。

​
快速上手（Builder）

import static org.tabooproject.fluxon.runtime.FunctionSignature.returns;
import org.tabooproject.fluxon.runtime.Type;

FluxonRuntime runtime = FluxonRuntime.getInstance();
runtime.registerExtension(File.class, "fs:io")
       .function("exists", returns(Type.Z).noParams(), ctx -> {
           ctx.setReturnBool(ctx.getTarget().exists());
       })
       .asyncFunction("length", returns(Type.J).noParams(), ctx -> {
           ctx.setReturnLong(ctx.getTarget().length());
       })
       .syncFunction("getName", returns(Type.STRING).noParams(), ctx -> {
           ctx.setReturnRef(ctx.getTarget().getName());
       });
  • function：同步扩展。
  • asyncFunction：异步扩展（在线程池执行）。
  • syncFunction：主线程同步扩展（通过 primaryThreadExecutor 执行）。
  • sharedFunction：同步扩展 + 自动导出到跨 CL 共享注册表。
  • sharedAsyncFunction：异步扩展 + 自动导出。
  • sharedSyncFunction：主线程同步扩展 + 自动导出。
ExtensionBuilder 只是语法糖，底层仍调用 FluxonRuntime 的注册方法。

​
直接注册

使用 FluxonRuntime.registerExtensionFunction 方法直接注册扩展函数： 
runtime.registerExtensionFunction(
    extensionClass,   // 目标类型，如 File.class
    namespace,        // 命名空间，可为 null
    name,             // 函数名
    signature,        // FunctionSignature 签名
    implementation,   // NativeCallable 实现
    isAsync,          // 是否异步
    isPrimarySync     // 是否主线程同步
);
命名空间前缀会与函数名组合为脚本调用形态。 例如 fs:io + readText -> fs:io::readText()。

​
查找与匹配流程

  1. 解释器确定 target 的 Class<?>。
  2. Environment#getExtensionFunction 优先在烘焙的 systemExtensionFunctions 二维数组中按名称匹配。
  3. 若未命中，回退到 extensionFunctions（名称 -> Map<Class<?>, Function>）。
  4. 匹配顺序为精确类型，再尝试 isAssignableFrom，确保子类可复用父类扩展。

​
实战提示

  • 复杂类型示例可参考 core/src/main/java/org/tabooproject/fluxon/runtime/function/extension（Path、Collection 等）。
  • 想支持索引访问 (obj[index])，需实现 IndexAccessor（详见运行时章节）。
  • 调试：Environment#getRootExtensionFunctions() 查看当前映射。
  • 若调用失败，检查是否遗漏 import 或命名空间不一致。
  • dumpFluxonCatalog 可确认导出签名。

​
相关链接