实例构建器

InstanceBuilder 配置并将 Pine 脚本编译为可执行的 Instance。

基本用法

use openpine_vm::{Instance, TimeFrame};

let mut instance = Instance::builder(bars, source, TimeFrame::days(1), "NASDAQ:AAPL")
    .build().await?;

instance.run_to_end("NASDAQ:AAPL", TimeFrame::days(1)).await?;

数据提供者

Instance::builder() 的第一个参数是 DataProvider，服务于两个目的：

1. 主 chart K 线 — Instance::run() 从中消费数据驱动逐 bar 执行
2. request.security() 数据 — 多周期和跨标的 K 线流

Vec<Candlestick> 直接实现了 DataProvider，无需任何包装即可传入：

let mut instance = Instance::builder(bars, source, timeframe, "NASDAQ:AAPL")
    .build().await?;
instance.run_to_end("NASDAQ:AAPL", timeframe).await?;

多标的或实时数据，实现 DataProvider：

let mut instance = Instance::builder(MyProvider::new(), source, timeframe, "NASDAQ:AAPL")
    .build().await?;
instance.run_to_end("NASDAQ:AAPL", timeframe).await?;

标的字符串作为最后一个参数传入；标的元数据由 provider 自动解析。

构建器方法

方法	说明
with_path	脚本文件路径（用于错误信息）
with_locale	数字/日期格式化的区域设置
with_input_value	按 ID 覆盖脚本输入
with_input_sessions	过滤处理的交易时段
with_background_color	自定义图表背景颜色
with_last_info	最后一根 K 线的索引和时间戳
with_execution_limits	循环迭代次数和 security 调用次数限制
with_library_loader	import 语句的自定义加载器
with_output_mode	系列图形输出模式（Chart 或 Stream）

脚本元数据

with_path — 为脚本设置文件路径（用于错误信息）：

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_path("my_indicator.pine")
    .build().await?;

with_locale — 设置数字和日期格式化的区域设置：

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_locale("zh")
    .build().await?;

输入配置

with_input_value — 按 ID 覆盖默认输入值。输入 ID 从 0 开始按顺序分配，与脚本中 input.*() 调用的出现顺序一致。

如需在运行时查询各输入的 ID，可调用独立函数 script_info()——inputs 是按声明顺序排列的 Vec<Input>，索引即为 ID：

use openpine_vm::script_info;

let info = script_info(source)?;

for (id, input) in info.inputs.iter().enumerate() {
    println!("id={id}  input={input:?}");
}

然后按 ID 覆盖：

// Pine 脚本：
// length = input.int(14, "RSI Length")    // input id 0
// src = input.source(close, "Source")     // input id 1

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_input_value(0, 21)       // 将 RSI Length 覆盖为 21
    .build().await?;

with_input_sessions — 控制处理哪些交易时段：

use openpine_vm::InputSessions;

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_input_sessions(InputSessions::REGULAR | InputSessions::EXTENDED)
    .build().await?;

标志	描述
InputSessions::REGULAR	常规交易时段
InputSessions::EXTENDED	延长/盘前/盘后交易
InputSessions::OVERNIGHT	隔夜交易时段
InputSessions::ALL	所有交易时段

显示与环境

with_background_color — 设置自定义背景颜色：

use openpine_vm::ast::Color;

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_background_color(Color::new(255, 255, 255, 255))
    .build().await?;

with_last_info — 提供最后一根可用 K 线的信息（用于 barstate.islast）：

use openpine_vm::LastInfo;

let last = LastInfo::new(499, 1700000000000);
let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_last_info(last)
    .build().await?;

执行限制

with_execution_limits — 配置运行时限制，以防止脚本失控：

use openpine_vm::ExecutionLimits;

let limits = ExecutionLimits::default()
    .with_max_loop_iterations_per_bar(1_000_000);

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_execution_limits(limits)
    .build().await?;

若未调用此方法，默认每 Bar 最多 500,000 次循环迭代。详情请参阅安全与执行限制。

with_library_loader — 为 import 语句添加自定义库加载器：

use openpine_vm::loader::LibraryLoader;

struct MyLoader;
impl LibraryLoader for MyLoader {
    // ... 实现加载逻辑
}

let instance = Instance::builder(provider, source, timeframe, "NASDAQ:AAPL")
    .with_library_loader(MyLoader)
    .build().await?;

输出模式

with_output_mode — 控制 plot() 数据的产出方式。

模式	行为
OutputMode::Chart（默认）	系列图形数据写入 instance.chart()
OutputMode::Stream	系列图形数据以 DrawEvent 形式在事件流中发出

use openpine_vm::{Instance, OutputMode, TimeFrame};

let mut instance = Instance::builder(provider, source, TimeFrame::days(1), "NASDAQ:AAPL")
    .with_output_mode(OutputMode::Stream)
    .build().await?;

详见 执行脚本。

检查脚本信息

使用独立函数 script_info() 检查脚本的元数据，无需创建可执行实例，也不需要数据提供者、品种或周期：

use openpine_vm::script_info;

let info = script_info(source)?;

println!("Script type: {:?}", info.script_type);
println!("Is overlay: {}", info.overlay());
println!("Inputs: {} total", info.inputs.len());

for input in &info.inputs {
    // 检查输入定义
}

链式调用

use openpine_vm::{Instance, OutputMode, TimeFrame};

let mut instance = Instance::builder(bars, source, TimeFrame::minutes(5), "NASDAQ:AAPL")
    .with_path("strategy.pine")
    .with_locale("en")
    .with_input_value(0, 20)        // 覆盖第一个输入
    .with_input_value(1, 2.5)       // 覆盖第二个输入
    .with_input_sessions(InputSessions::REGULAR)
    .with_last_info(LastInfo::new(999, last_time))
    .with_output_mode(OutputMode::Stream)
    .build().await?;

instance.run_to_end("NASDAQ:AAPL", TimeFrame::minutes(5)).await?;

下一步

• 执行脚本 — 喂入数据并运行
• 读取输出 — 检查结果