實例建構器

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?;

下一步

• 執行腳本 — 餵入資料並執行
• 讀取輸出 — 檢查結果