Основы языка

Структура скрипта

Скрипт в Pine обычно состоит из:

• //@version=4 Версии компилятора в комментарии, которая указывает, какую версию Pine будет использовать скрипт. Если в @version указание версии отсутствует, будет использоваться версия 1. Настоятельно рекомендуется всегда использовать последнюю доступную версию.
• Вызов аннотаций study (индикатор) или strategy (стратегия). Эти параметры определяют заголовок и другие свойства скрипта.
• Серия операторов, реализующих алгоритм скрипта. Каждый оператор обычно помещается в отдельную строку. Можно разместить и больше одного оператора в строке, используя запятую (,) в качестве разделителя. Строки, содержащие операторы, не являющиеся частью локальных блоков, не могут начинаться с пробела. Их первый символ также должен быть первым символом строки. Высказывания могут быть одного из трех видов:
  • объявления переменных
  • объявления функций
  • вызовы функций и аннотаций

Индикатор должен содержать по крайней мере одну функцию / аннотацию вызова, который производит вывод на графике (например: plot, plotshape, barcolor, line.new и т.д.). Стратегия должна содержать хотя бы один  вызов strategy.*, например strategy.entry.
Простейший работающий индикатор Pine v4 может быть создан с помощью Редактор Pine → Новый → Пустой скрипт индикатора :

//@version=4
study("My Script")
plot(close)

Простую работающую стратегию Pine v4 можно создать с помощью Pine Editor → Создать → Пустой скрипт стратегии :

//@version=4
strategy("My Strategy", overlay=true)
longCondition = crossover(sma(close, 14), sma(close, 28))
if (longCondition)
    strategy.entry("My Long Entry Id", strategy.long)
shortCondition = crossunder(sma(close, 14), sma(close, 28))
if (shortCondition)
    strategy.entry("My Short Entry Id", strategy.short)

Версии

В настоящее время существует четыре версии языка Pine Script. Директива компилятора должна использоваться в первой строке скрипта, чтобы указать версию Pine, используемую скриптом: //@version=N где N номер версии (1–4). Обратите внимание, что разные версии Pine Script Language несовместимы друг с другом.

Комментарии

Pine Script поддерживает однострочные комментарии. Любой текст от символа // до конца строки считается комментарием.

Пример:

//@version=4
study("Test")
// This line is a comment
a = close // This is also a comment
plot(a)

Редактор Pine имеет горячую клавишу для комментариев Ctrl + /. Выделите фрагмент кода и нажмите Ctrl + /, чтобы комментировать / раскомментировать целые блоки кода одновременно.

Комментарии не могут быть помещены в середине оператора, длинною несколько строк.

Идентификаторы

Идентификаторы — это имена, используемые для пользовательских переменных и функций. Они могут состоять из:

• заглавные ( A-Z) или строчные ( a-z) буквы,
• подчеркивание ( _),
• цифры ( 0-9).

Идентификатор не может начинаться с цифры. Идентификаторы чувствительны к регистру. Вот несколько примеров допустимых идентификаторов:

• myVar
• _myVar
• my123Var
• MAX_LEN
• max_len

Перенос строки 

Любая слишком длинная запись оператора в Pine Script, может быть помещена в более чем одну строку. Синтаксически, оператор должен начинаться с начала строки. Если он переносится на следующую строку, то продолжение оператора должно начинаться с одного или нескольких (отличных от четырех) пробелов.

Например:

a = open + high + low + close

можно записать как:

a = open +
      high +
          low +
             close

Длинная запись вызова plot может быть записана как:

plot(correlation(src, ovr, length),
   color=color.purple,
   style=plot.style_area,
   transp=40)

Операторы внутри пользовательских функций также могут быть перенесены. Однако, поскольку локальный оператор должен синтаксически начинаться с отступа (4 пробела или 1 табуляция), при перенесении его на следующую строку продолжение оператора должно начинаться с более чем одного отступа (не равного кратному 4 пробелам).

Например:

updown(s) =>
    isEqual = s == s[1]
    isGrowing = s > s[1]
    ud = isEqual ?
           0 :
           isGrowing ?
               (nz(ud[1]) <= 0 ?
                     1 :
                   nz(ud[1])+1) :
               (nz(ud[1]) >= 0 ?
                   -1 :
                   nz(ud[1])-1)

Не используйте комментарии с переносом строк. Следующий код НЕ компилируется:

//@version=4
study("My Script")
c = open > close ? color.red :
  high > high[1] ? color.lime : // a comment
  low < low[1] ? color.blue : color.black
bgcolor(c)

Компилятор выдаст ошибку: Add to Chart operation failed, reason: line 3: syntax error at input ‘end of line without line continuation’. Чтобы этот код компилировался, просто удалите комментарий  // a comment.

Типы систем

Pine имеет 9 основных типов данных. Это: int, float, bool, color, string, line, label, plot, hline. Все эти типы данных существуют в нескольких формах. Существует 5 типов форм:  literal, const, input, simple и series. Мы будем часто ссылаться на тип парной формы как на тип. Компилятор Pine различает типы: literal bool, input bool, series bool и так далее.

Существует также тип void, значение na (not available) и составной тип tuple.

Типы форм

Literal

literal это специальное обозначение для представления фиксированного значения в Pine. Это фиксированное значение само по себе является выражением, и такие буквальные выражения всегда имеют один из 5 следующих типов:

• literal float (3.14, 6.02E-23, 3e8)
• literal int (42)
• literal bool (true, false)
• literal string («A text literal»)
• literal color (#FF55C6)

Замечание

В Pine, встроенные имена open, high, low, close, volume, time, hl2, hlc3, ohlc4 не являются типом формы literal. Они имеют форму серии.

Const

Значения формы const:

• не изменяются во время выполнения скрипта
• известны или могут быть рассчитаны во время компиляции

Например:

c1 = 0
c2 = c1 + 1
c3 = c1 + 1
if open > close
    c3 := 0

Тип c1 является const int, поскольку он инициализируется с literal int выражением. Тип c2 также является const int, потому что он инициализируется арифметическим выражением типа const int. Тип c3 это series int, поскольку он изменяется во время выполнения.

Input

Значения формы input:

• не изменяются во время выполнения скрипта
• неизвестны во время компиляции
• берутся из функции input

Например:

p = input(10, title="Period")

Тип p переменной — входное целое число.

Simple

Значения формы simple:

• не изменяются во время выполнения скрипта
• неизвестны во время компиляции

Это значения, которые берутся из символьной информации основного графика. Например, встроенная переменная syminfo.mintick представляет собой простое число с плавающей точкой. Слово simple обычно опускается при обращении к этой форме, поэтому мы используем float, а не simple float.

Series

Значения формы series:

• изменяются во время выполнения скрипта
• хранят последовательность исторических значений, связанных с барами основного графика
• можно получить с помощью [] оператора. Обратите внимание, что только последнее значение в серии, то есть значение, связанное с текущим баром, доступно как для чтения, так и для записи.

Форма series является наиболее распространенной формой в Pine. Примеры встроенных серий переменных: open, high, low, close, volume и time. Размер этих серий равен количеству доступных баров для текущего тикера и таймфрейма. Серия может содержать числа или специальное значение: na, означающее, что значение недоступно. Любое выражение, содержащее переменную серии, будет рассматриваться как сама серия.

Например:

a = open + close // Добавление двух серий
b = high / 2     // Деление серии на
                 // целочисленную фиксированную константу
c = close[1]     // Ссылка на предыдущее значение ``close``

Примечание

Оператор [] также возвращает значение формы серии.

Основные типы

Int

Целочисленные литералы должны быть записаны в десятичной записи. Например:

• 1
• 750
• 94572
• 100

В Pine есть 5 форм типа int:

• literal int
• const int
• input int
• ini
• series int

Float

Литералы с плавающей точкой содержат разделитель (символ .) и могут также содержать символ e (что означает «умножить на 10 в степени X», где X — число после символа e).

Примеры:

• 3.14159    // 3.14159
• 6.02e23    // 6.02 * 10^23
• 1.6e-19    // 1.6 * 10^-19
• 3.0        // 3.0

Первое число является округленным числом Pi (π), второе число очень большое, а третье очень мало. Четвертое число — просто число 3 как число с плавающей точкой.

Примечание

Можно использовать прописные буквы E вместо строчных e.

В Pine есть 5 видов форм чисел с плавающей точкой типа:

• literal float
• const float
• input float
• float
• series float

Внутренняя точность чисел с плавающей точкой в Pine составляет 1e-10.

Bool

Есть только два литерала, представляющих значения bool :

• true    // истинное значение
• false   // ложное значение

В Pine есть 5 форм типа bool:

• literal bool
• const bool
• input bool
• bool
• series bool

Color

Цветные литералы имеют следующий формат: # за ними следуют 6 или 8 шестнадцатеричных цифр, соответствующих значению RGB или RGBA. Первые две цифры определяют значение для компонента красного цвета, следующие две — зелёный, последние две — синий. Каждое значение компонента должно быть шестнадцатеричным числом от 00 до FF (от 0 до 255 в десятичном виде).

Четвертая пара цифр является необязательной. При использовании он указывает компонент альфа (непрозрачность), значение также от 00 (полностью прозрачное) до FF (полностью непрозрачное).

Примеры:

Примечание

Шестнадцатеричная запись не чувствительна к регистру.

В Pine есть 5 видов цветного типа:

• literal color
• const color
• input color
• color
• series color

Кто-то может спросить, как значение может иметь тип input color, если невозможно использовать input для ввода цвета в Pine. Ответ: через арифметическое выражение с другими типами ввода и цветными литералами / константами.

Например:

b = input(true, "Use red color")
c = b ? color.red : #000000  // с имеет режим ввод цвета

Это арифметическое выражение, использующее условный (тернарный) оператор Pine ?:, в котором используются три различных типа значений: b тип input bool, color.red тип const color и #000000 тип literal color. При определении типа результата компилятор Pine учитывает свои правила автоматического приведения типов (см. Конец этого раздела) и доступные перегрузки ?: оператора. Результирующий тип является самым узким типом, соответствующим этим критериям: ввод цвета.

Следующие встроенные цветовые переменные могут быть использованы, чтобы избежать шестнадцатеричных цветовых литералов: 

• color.black
• color.silver
• color.gray
• color.white
• color.maroon
• color.red
• color.purple
• color.fuchsia
• color.green
• color.lime
• color.olive
• color.yellow
• color.navy
• color.blue
• color.teal
• color.aqua
• color.orange

Можно изменить прозрачность цвета с помощью встроенной функции color.new.

Вот пример:

//@version=4
study(title="Shading the chart's background", overlay=true)
c = color.navy
bgColor = (dayofweek == dayofweek.monday) ? color.new(c, 50) :
(dayofweek == dayofweek.tuesday) ? color.new(c, 60) :
(dayofweek == dayofweek.wednesday) ? color.new(c, 70) :
(dayofweek == dayofweek.thursday) ? color.new(c, 80) :
(dayofweek == dayofweek.friday) ? color.new(c, 90) :
color.new(color.blue, 80)
bgcolor(color=bgColor)

String

Строковые литералы могут быть заключены в одинарные или двойные кавычки.

Примеры:

• «This is a double quoted string literal»
• ‘This is a single quoted string literal’

Одинарные и двойные кавычки функционально эквивалентны. Строка, заключенная в двойные кавычки, может содержать любое количество одинарных кавычек и наоборот:

• «It’s an example»
• ‘The «Star» indicator’

Если вам нужно заключить в строку разделитель строки, ему должен предшествовать обратный слеш. Например:

• ‘It\’s an example’
• «The \»Star\» indicator»

В Pine есть 5 форм строкового типа:

• literal string
• const string
• input string
• string
• series string

Line and label 

Новые графические объекты были введены в Pine v4. Эти объекты создаются с помощью функций  line.new и label.new. Их тип — серийная линия и серийная метка соответственно. В Pine есть только одна форма линий и типов меток : серия.

Plot and hline 

Несколько аннотаций функций (в частности, plot и hline) возвращают значения, которые представляют объекты, созданные на диаграмме. Функция plot возвращает объект типа plot, представленный в виде линии или диаграммы на графике. Функция hline возвращает объект типа hline, представленный в виде горизонтальной линии. Эти объекты могут быть переданы в функцию заполнения (fill), чтобы закрасить область между ними.

Void 

В Pine Script есть тип void. Большинство функций и функций аннотаций, которые производят побочный эффект, возвращают пустой результат. Например, Strategy.entry, Plotshape и т. д.

Пустой результат не может быть использован в каком-либо арифметическом выражении или назначен переменной.

Na value

В Pine есть специальная встроенная переменная na, которая является аббревиатурой от not available (недоступно), то есть выражение или переменная не имеют значения. Это очень похоже на null значение в Java или None в Python.

Есть несколько вещей, которые нужно знать о преимуществах na. Во-первых, значение na может быть автоматически приведено практически к любому типу.

Во-вторых, в некоторых случаях Pine-компилятор не может автоматически определить тип значения  na, поскольку может быть применено несколько правил автоматического приведения типов.

Например:

myVar = na // Compilation error!

Здесь компилятор не может определить, будет ли myVar использоваться для построения чего-нибудь, например, plot(myVar) где его тип будет серией с плавающей точкой, или например для установки какого то текста как в label.set_text(lb, text=myVar), где его тип будет последовательностью строки, или для какой-то другой цели. Такие случаи должны быть явно разрешены одним из двух способов:

float myVar = na

или:

myVar = float(na)

В-третьих, чтобы проверить, не доступно ли какое-либо значение, необходимо использовать специальную функцию: na.

Например:

myClose = na(myVar) ? 0 : close

Не используйте оператор == для проверки na, нет гарантий что это будет работать.

Tuples (кортежи)

В Pine Script ограничена поддержка типа кортежа. Кортеж — это неизменяемая последовательность значений, используемая, когда функция должна возвращать более одной переменной в результате.

Например:

calcSumAndMul(a, b) =>
    sum = a + b
    mul = a * b
    [sum, mul]

В этом примере есть 2 кортежа в последнем утверждении функции calcSumAndMul. Элементы кортежа могут быть любого типа. Существует также специальный синтаксис для вызова функций, которые возвращают кортежи. Например, calcSumAndMul должен быть вызван следующим образом:

[s, m] = calcSumAndMul(high, low)

где значение локальных переменных sum и mul будут записаны в s и m переменных внешнего диапазона.

Type casting

В Pine Script есть механизм автоматического приведения типов. На следующем рисунке стрелка обозначает способность компилятора Pine автоматически приводить один тип к другому:

Например:

//@version=4
study("My Script")
plotshape(series=close)

Типом series параметра функции plotshape является series bool. Но функция вызывается с close аргументом типа float. Типы не совпадают, но правильное преобразование выполняет автоматическое правило приведения типов серии float → series bool (см. Диаграмму).

Иногда не существует автоматического правила приведения типов X → Y. Для этих случаев функции явного приведения типов были введены в Pine v4. Вот они:

• int
• float
• string
• bool
• color
• line
• label

Вот пример:

//@version=4
study("My Script")
len = 10.0
s = sma(close, len) // Compilation error!
plot(s)

Этот код не компилируется с ошибкой: Add to Chart operation failed, reason: line 4: Cannot call sma with arguments (series[float], const float); available overloads: sma(series[float], integer) => series[float]; Компилятор говорит, что, хотя тип len переменной const float, sma функция ожидает integer. Не существует автоматического приведения типов из const с плавающей точкой в целое, но можно использовать явную функцию приведения типа:

//@version=4
study("My Script")
len = 10.0
s = sma(close, int(len))
plot(s)