跳至主要內容

Pine v6 的型別系統:實務筆記

約 10 分鐘閱讀

PineScript v6 比你想的更強型別。走一遍規則與推導、常見坑——以及我們做 transpiler 後學到的:哪些規則在執行期才真正重要。

Pine Script 常被說成是弱型別語言。這個名聲有幾分道理,但大致上是錯的。它之所以被貼上這個標籤,是因為 int 會默默擴展成 float、na 幾乎在哪裡都能用,而且這個語言很少要求你寫出明確的型別註記。但在寬鬆的表面底下,是一套真正有約束力的型別系統——一旦你得把它轉譯成靜態型別語言,每一條約束都要認真對待。

本文會說明 Pine v6 的型別到底有哪些、推論層把複雜度藏在哪裡,以及把 Pine 編譯成 C++ 時需要注意的三個坑。

名聲與現實

一位剛接觸 Pine 的開發者寫下:

x = 5
y = close + x

沒有型別註記,編譯器也沒有抱怨。這位開發者於是得出結論:「Pine 沒有型別。」但 Pine 其實精確推論出了這些變數的型別:x 是 const int(字面值,編譯期就已知),y 是 series float(逐根 K 線變化的浮點數值)。推論確實在做事,只是你看不到而已。

const int 和 series float 的差別不只是表面上的。兩者的執行期行為不同、運算子相容規則不同,在轉譯輸出裡的表示方式也不同。這個語言是有型別的,只是不強迫你把型別寫出來。

型別的種類

本文把 Pine v6 的型別系統分成四層來看,多數使用者只會碰到第一層。

基本型別

基本型別有 int、float、bool、string 和 color。另外還有 na,下面會另闢一節討論。這些是葉節點型別,也就是存放純量值的型別。

int 和 float 之間有隱式擴展:在同一個運算式裡混用時,int 會擴展成 float。Pine 正是因為這個行為被貼上「弱型別」的標籤,但這是一條刻意且一致的規則,而不是特例。C++ 對數值型別也是這麼做的。

複合型別

Pine v6 支援三種複合型別:array<T>、matrix<T> 和 map<K, V>。三者都以元素型別作為參數,元素型別可以是 UDT;但 map 的鍵是例外,必須是 int 或 string 這類實值型別。你可以有 array<float>、array<int>,甚至是 array<MyUDT>。

複合型別是可變物件。說它們是參考型別,意思是:把 array<float> 傳給函式時,函式拿到的是指向同一塊底層儲存空間的 handle。函式修改了陣列,呼叫端也看得到變化。

使用者自訂型別(UDT)

Pine v5 在 2022 年 12 月加入 type 關鍵字、2023 年 2 月加入 method 關鍵字,兩者搭配起來,就能定義具名的紀錄型別,其中包含欄位與選用的方法:

type Order
    float price
    int   qty
    bool  filled = false
 
method fill(Order this, float fillPrice) =>
    this.price  := fillPrice
    this.filled := true

UDT 是 Pine 裡最接近 struct 的東西。欄位可以有預設值(如 filled = false)。方法以點號語法呼叫,UDT 實例會作為方法的第一個參數傳入,這個例子把它命名為 this。欄位可以透過 := 指派來修改。

形態限定詞:series 與 simple

Pine 裡的每一個值——不只是基本型別,也包括複合型別和 UDT——都帶有一個形態限定詞,描述它和 K 線時間軸的關係。

  • series:值可以逐根 K 線變化,而且有歷史:x[1] 會給你 x 在前一根 K 線上的值。大多數涉及價格資料的運算式,預設都是這個形態。
  • simple:值在第一根 K 線就設定好,之後整個執行期間都固定不變,例如 syminfo.ticker。
  • input:值來自腳本的設定,透過 input.int() 及其同類函式取得:整個執行期間固定,腳本啟動時就已知。
  • const:值在編譯期就已知,包括所有字面值,以及任何像 const int VERSION = 6 這樣宣告的東西。codegen 可以把它直接寫進 C++(下面第一個坑會示範怎麼做)。

這些限定詞構成一個層級 const < input < simple < series,而運算式會採用其組成部分中最強的限定詞:simple int + series float 的結果是 series float。

na 的語意

na 不是萬用的 null:Pine 仍然需要知道缺少的是哪一種型別的值。所以下面這行無法編譯:

x = na

因為沒有任何東西可以用來推論型別。請改成明確宣告:

float x = na

對 na 做算術會一路傳遞下去:na + 1 的結果是 na。這是刻意且一致的設計——如果一個值是未知的,任何依賴它的運算式也都是未知的。脫身的方法是 nz(x, 0),它會用預設值取代 na。

比較運算則不一樣:只要有一個運算元的值是 na,==、!= 以及其他所有比較運算的結果都會是 false;而直接把 na 本身當成運算元,像 x == na 這樣寫,根本無法編譯。請改用內建的判斷函式 na(x)。

在 PineForge 產生的 C++ 裡,na 是變數自身型別的哨兵值(sentinel),而 na(x) 會變成 is_na(x)。產生的比較運算會先用 is_na 檢查兩邊,所以和 na 比較的結果會是 false。

型別推論細節

Pine 從指派式的右側推論型別。只要掌握形態限定詞的層級,規則就很直接:

a = 5           // const int
b = 5.0         // const float
c = close       // series float  (close is always series float)
d = close + 1   // series float  (int widens to float; series promotes)
e = bar_index   // series int    (bar_index is series int, always)

比較有意思的是跨分支的推論:

x = condition ? close : 0

condition 可能是 series bool,close 是 series float,0 是 const int。Pine 會把 0 擴展成 series float,結果就是 series float。編譯器永遠會挑選最一般的形態,以及涵蓋範圍最廣的型別。

函式引數也會限制推論。如果某個內建函式要求 simple int,你卻傳入 bar_index(它是 series int),就會出現編譯錯誤。型別系統的嚴格就在這裡浮上檯面:你不能把逐根 K 線變化的值,傳給要求在啟動時就固定的參數。

C++ codegen 如何表示這些型別

要把 Pine 的型別系統轉譯成 C++,就得把每一種 Pine 形態與型別,對應到具有正確執行期行為的 C++ 表示方式。

以下細節對應引擎 v1.0.0 的標頭檔,以及 codegen 1.0.0 產生的 C++。

基本型別對應到 C++ 的純量型別:float 對應 double,int 對應 int 或 int64_t(有些計算出來的 int 值,例如 bar_index 和 hour,會存成 double),bool 對應 bool,string 對應 std::string,color 則對應 int64_t。

Series 是保存歷史的環形緩衝區。以下是引擎的類別,出自 include/pineforge/series.hpp:

template <typename T>
class Series {
public:
    void push(T value);             // a new bar
    void update(T value);           // the same bar again (bar magnifier)
    T operator[](int offset) const; // offset bars back; na if out of range
    T current() const;
};

Pine 程式碼寫 close[2] 時,產生的 C++ 會讀取 _s_close[2]。

na 是值自身型別的哨兵值(include/pineforge/na.hpp):na<double>() 是 quiet NaN,na<int>() 是最小的 int,na<bool>() 則是 false。is_na(x) 用來檢查它,而 nz(x, y) 會直接展開成 is_na(x) ? y : x。

UDT 會變成 handle:產生的 struct 保存的是一個 id,欄位存放在策略所擁有的紀錄裡(這樣檢查點才能把它們還原),每個方法則變成一個接收 handle 的函式,例如 _udt_Acc_add(Acc self, double v)。欄位寫入就是對紀錄欄位的指派,沒有 setter。

陣列會變成 std::vector<T>。矩陣方面,matrix<float> 使用引擎的 NumericMatrix(底層是 Eigen 的 MatrixXd),其他元素型別則一律使用 GenericMatrix<T>,matrix<int> 也不例外;產生的程式碼仍沿用 PineMatrix 和 PineGenericMatrix<T> 這兩個名稱,引擎 v1.0.0 也仍保留它們作為別名。

三個坑

1. 永遠不變的值,不一定是 const

atrLen     = 14
fastLength = input.int(22, "Fast EMA Length")
atr  = ta.atr(atrLen)
fast = ta.ema(close, fastLength)

兩個長度在執行期間都不會改變,但只有其中一個在編譯期就已知。atrLen 是 const int:字面值是 const,用字面值初始化的變數也會繼承這個限定詞。fastLength 則是 input int:它的值在腳本啟動時,才從腳本設定取得。

產生的 C++ 也畫出了同一條界線。在開放語料庫裡,atrLen = 14 接著 ta.atr(atrLen),會編譯成 ta::ATR(14),14 直接寫進程式碼裡。fastLength = input.int(22, "Fast EMA Length") 則編譯成 get_input_int("Fast EMA Length", 22),在回測開始時讀取。正是這一點,讓同一支轉譯好的策略能用不同的輸入執行:本機 MCP 伺服器的 backtest_pine_grid 只轉譯一次 Pine,再拿同一份 C++,把每一種輸入值組合都跑一遍。

2. UDT 欄位指派不會觸發方法——而且這是刻意的

type Box
    float value
 
method doubled(Box this) =>
    this.value * 2
 
b = Box.new(value = 10.0)
b.value := 20.0   // direct field write, no notification

在物件導向語言裡,你可能會預期 b.value := 20.0 會經過一個 setter,進而呼叫 doubled() 或觸發其他行為。在 Pine 裡不會。欄位是公開的,可以直接修改;方法只是掛在該型別底下的函式。如果你在 UDT 裡打造狀態機,又希望寫入時做驗證,就必須明確呼叫負責驗證的方法——欄位寫入會繞過一切。

這是 Pine 程式看起來有封裝、其實沒有的主要地方。產生的 C++ 也反映了這一點:欄位寫入就是對紀錄欄位的指派,中間不經過任何方法。

3. request.security 預設是因果的——但 lookahead 的預設值隨版本變過

htf_close = request.security(syminfo.tickerid, "D", close)

這個呼叫在型別上是正確的,編譯也不會有任何警告。它回傳的是以目前這根 K 線的時間點來看的日線收盤價。如果目前這根是盤中的 15 分鐘 K 線,htf_close 在新的日 K 收盤之前,都會帶著前一天的收盤價——這就是因果的解讀方式。

歷史上的坑:在 Pine v2 裡,security 的預設是 lookahead=barmerge.lookahead_on,允許在未來的日 K 收盤前就偷看它。這讓使用高時間週期(HTF)資料的策略,回測結果被灌水。Pine v3 把預設改成 lookahead_off(因果),這才是正確的行為;之後的每個版本,包括 v6,都沿用這個預設。

型別系統不會提醒你這一點,因為兩種模式在型別上都正確。沒有傳入 lookahead 引數時,PineForge codegen 會套用 lookahead_off 語意,與 Pine v6 的預設一致。

為什麼轉譯 Pine 讓我們更嚴謹

Pine 型別規則裡的每一處模糊地帶,都必須在 C++ codegen 裡變成一個明確的決定。當 Pine 的參考文件寫著「由實作定義」,或兩種行為在技術上都符合規格時,我們不能隨便挑一個然後祈禱。我們必須拿 TradingView 的實際輸出來測試,弄清楚 TradingView 走的是哪一條分支,再實作那條分支。

這個過程讓我們把 Pine v6 語言參考讀得比任何使用者都仔細。開放語料庫裡的許多策略也是這樣來的:每當我們在 request.security 或 strategy.exit 上發現 codegen 與 TradingView 不一致的邊角情況,就寫一個最小重現案例、加進語料庫,然後修正 codegen,直到兩邊的輸出一致。

型別系統就是邊角情況的溫床。形態限定詞——series、simple、const——看起來像微不足道的實作細節,卻決定了哪些運算合法、哪些值能傳給哪些函式,以及哪些運算式能在編譯期求值、而不必逐根 K 線計算。把它們做對,就是「一個轉譯器」和「一個好的轉譯器」之間的差別。

下一步

  • 從 Claude 或 Cursor 轉譯:本機 MCP 伺服器的 transpile_pine 工具會回傳 C++,方便你檢視這些表示方式。
  • 瀏覽畫廊:開放語料庫的 312 支策略,每一支都會顯示 Pine 原始碼,以及由它產生的 C++。
  • 看看我們為什麼打造它——引擎的緣起,以及選擇 C++ 作為轉譯目標的決定。