openpinescript 0.0.0-stage → 0.1.0

package/dist/types/transpiler/v2/ToJsVisitor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pine Script v2 → JavaScript emitter.
+ *
+ * v2 inherits every line of emit logic from v1 and adds exactly one thing:
+ * reassignment with ':='.
+ *
+ * The operator is a v2 GRAMMAR addition (PineV2Lexer.g4 declares the token,
+ * PineV2Parser.g4 the rule), so v1 rejects `x := 1` as a syntax error — its
+ * grammar has never heard of the token. There is no "reassignment is not
+ * allowed in v1" guard anywhere, because v1 cannot reach one.
+ *
+ * SCOPE is the part a grammar cannot express, and the documented rule is a
+ * DECLARATION rule, not a scope one:
+ *
+ *   "Pine now supports mutable variables! Use the ':=' operator to assign a new
+ *    value to a variable that has already been defined."
+ *      — TradingView release notes, Pine v2
+ *   "A variable must be declared before you can set a value for it."
+ *      — Expressions, declarations and statements (v3 manual, which documents
+ *        ':=' as requiring only //@version=2)
+ *
+ * Neither source restricts ':=' by scope, and the corpus agrees: two published
+ * //@version=2 scripts reassign at script scope —
+ *
+ *     longStopPrice = 0.0                          gap_down_reversal_strategy
+ *     longStopPrice := if (strategy.position_size > 0)
+ *
+ *     if crossunder(corVix, -.1) or ...            VIX_bonds_strategy
+ *         signal1 := -100
+ *
+ * An earlier version of this file restricted ':=' to for-loop accumulators and
+ * rejected both. That restriction was inferred, not sourced, and it was wrong:
+ * TradingView compiled and published these scripts. What is enforced now is the
+ * rule the documentation actually states — assign only to a name that was
+ * declared.
+ *
+ * v3 inherits this guard unchanged. ':=' scope was never a v1→v2→v3 delta.
+ *
+ * ⚠ See the sourcing note in grammar/v2/PineV2Lexer.g4 on why ':=' is placed at v2
+ * rather than v1. If that turns out to be wrong, this class moves to v1 wholesale.
+ */
+import type { PineVersion } from "../common/version.js";
+import { V1ToJsVisitor } from "../v1/ToJsVisitor.js";
+import { Var_assignContext, Global_stmt_contentContext, Local_stmt_contentContext } from "../../parser/v2/generated/PineV2Parser.js";
+export type { Local_stmt_contentContext };
+export declare class V2ToJsVisitor extends V1ToJsVisitor {
+    protected readonly version: PineVersion;
+    /**
+     * ':=' assigns to a variable "that has already been defined". Assigning to a
+     * name that is never declared is the `Undeclared identifier` error, which is
+     * how `if x==1 / y := 2` fails on TradingView.
+     *
+     * Scope is deliberately NOT checked — see the sourcing note at the top of this
+     * file. POSITION is not checked here either: forward references are legal in
+     * v2, and v3 rejects them through `enforceNoForwardReference`, which already
+     * sees this id because `visitVar_assign` visits it.
+     */
+    protected enforceDeclaredBeforeReassignment(ctx: Var_assignContext): void;
+    /** Handle: x := 1 */
+    visitVar_assign(ctx: Var_assignContext): string;
+    /**
+     * v2's global_stmt_content / local_stmt_content gained a `var_assign`
+     * alternative, so the statement dispatcher has to route it. Everything else
+     * falls through to the inherited implementation.
+     */
+    protected visitContent(ctx: Global_stmt_contentContext | Local_stmt_contentContext): string;
+    /**
+     * ':=' is a binding form too, so a function body ending in one returns the
+     * reassigned variable. v1 only knows about '='.
+     */
+    protected trailingValueName(content: Local_stmt_contentContext): string | null;
+}

package/dist/types/transpiler/v3/ToJsVisitor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pine Script v3 → JavaScript emitter.
+ *
+ * ── THE WORKED EXAMPLE OF A VERSION DELTA ───────────────────────────────────
+ *
+ * v3 inherits every line of emit logic from v2 (and thus v1). This file
+ * contains ONLY what the v2→v3 migration guide documents:
+ *
+ *   1. A variable may not reference itself in its own '=' declaration.
+ *   2. An identifier may not be used before it is declared.
+ *   3. Bools no longer coerce to numbers in arithmetic.
+ *   4. A ':='-mutated variable may not be passed to security().
+ *
+ * Each is one `enforce*` method plus a two-line override that calls it and
+ * delegates to `super`. Nothing in v1 or v2 was touched to add any of them.
+ *
+ * Every one is a TIGHTENING. v3 relaxes nothing: an earlier draft listed
+ * "':=' becomes available at every scope" as a fifth delta, but v2 never had a
+ * scope restriction to lift — see the sourcing note in ../v2/ToJsVisitor.ts.
+ *
+ * The security() lookahead default also flips in v3, but that is a RUNTIME
+ * behaviour rather than an emit one — it lives in the v3 language profile and is
+ * read by runtime/v1/stdlib/mtf.ts.
+ *
+ * NOTE ON `:=` — inherited from v2 wholesale, operator and guard alike. v1
+ * rejects it as a syntax error because PineV1Lexer.g4 has no such token.
+ */
+import type { ParseTree } from "antlr4ng";
+import type { PineVersion } from "../common/version.js";
+import { V2ToJsVisitor } from "../v2/ToJsVisitor.js";
+import { Var_defContext, Add_exprContext, Mult_exprContext, Fun_callContext, IdContext } from "../../parser/v3/generated/PineV3Parser.js";
+/** Anything carrying a source position (see the v1 base for why it is structural). */
+interface SourceLocated {
+    start?: {
+        line: number;
+        column: number;
+    } | null;
+}
+export declare class V3ToJsVisitor extends V2ToJsVisitor {
+    protected readonly version: PineVersion;
+    /**
+     * `s = nz(s[1]) + close` was the v1/v2 state idiom. v3 requires declaring
+     * first (`s = 0.0`) and then assigning with ':='.
+     */
+    protected enforceNoSelfReference(name: string, value: ParseTree, ctx: SourceLocated): void;
+    visitVar_def(ctx: Var_defContext): string;
+    /** An identifier may not be used before its declaration. Checked lexically. */
+    protected enforceNoForwardReference(name: string, ctx: SourceLocated): void;
+    visitId(ctx: IdContext): string;
+    /**
+     * v1/v2 coerced true→1 and false→0; v3 requires an explicit `b ? 1 : 0`.
+     *
+     * Static detection only, and deliberately conservative — `isStaticallyBool`
+     * answers "provably bool", not "possibly bool". A false negative is caught by
+     * the runtime backstop in the arithmetic helpers; a false positive would
+     * reject valid code.
+     */
+    protected enforceNoBoolArithmetic(operand: ParseTree, ctx: SourceLocated, op: string): void;
+    /**
+     * The operator ADJACENT to operand `i`, in a flat `a + b - c` chain.
+     *
+     * Children alternate operand, operator, operand, …, so operand `i` is
+     * preceded by the operator at `i * 2 - 1`. Reading `getChild(1)`
+     * unconditionally named the FIRST operator every time, so `z = 1 + 2 - b`
+     * with a bool `b` reported "cannot use a bool as an operand of '+'" when the
+     * offending operator is '-'. Cosmetic, but a diagnostic that points at the
+     * wrong token sends the reader to the wrong place.
+     */
+    private operatorFor;
+    visitAdd_expr(ctx: Add_exprContext): string;
+    visitMult_expr(ctx: Mult_exprContext): string;
+    /**
+     * Its value at HTF evaluation time is not the value the chart context holds,
+     * so the result would be silently wrong. Wrap the calculation in a function.
+     */
+    protected enforceNoMutableSecurityArg(args: ParseTree | null, ctx: SourceLocated): void;
+    /**
+     * Does this security-family call carry the mutable-argument restriction?
+     *
+     * A seam, because v5 splits the family: `request.security_lower_tf` keeps the
+     * rule and `request.security` loses it. Answering here rather than in
+     * `emitSecurity` keeps the walk in one place.
+     */
+    protected securityRestrictsMutableArgs(_ctx: Fun_callContext): boolean;
+    protected emitSecurity(ctx: Fun_callContext): string;
+}
+export {};

package/dist/types/transpiler/v4/ToJsVisitor.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Pine Script v4 → JavaScript emitter.
+ *
+ * v4 inherits every guard v3 added — self-reference, forward reference, bool
+ * arithmetic, mutable `security()` argument — and every line of emit logic from
+ * v1. The migration guide relaxes none of them.
+ *
+ * What v4 adds is in two halves:
+ *
+ *   SYNTAX (this file)
+ *     `var` / `varip` declaration modifiers, and an optional type prefix.
+ *     `var` is the only one with emit consequences; the type prefix is checked
+ *     and discarded, and the qualifiers are discarded outright.
+ *
+ *     The five compound assignment operators, `+= -= *= /= %=` (March 2021).
+ *     Sourced from the v4 release notes; see PineV4Lexer.g4 for the quote.
+ *
+ *     `else if` (May 2020). Grammar in PineV4Parser.g4, emit below.
+ *
+ *   NAMES (transpiler/common/profiles/index.ts + runtime)
+ *     The 3a rename table — `n` → `bar_index`, `red` → `color.red`,
+ *     `period` → `timeframe.period`, and the rest. Those are lookups, not emit
+ *     rules, so they do not belong here.
+ *
+ * NOT in v4, despite an earlier draft of the delta spec saying so: `while` and
+ * `switch`. Both are v5. v4 adds no statement keyword at all, which is why this
+ * file overrides declarations and nothing else.
+ */
+import type { PineVersion } from "../common/version.js";
+import { V3ToJsVisitor } from "../v3/ToJsVisitor.js";
+import type { StdlibEntry } from "../../runtime/v1/stdlib/metadata.js";
+import { Var_defContext, Var_defsContext, Var_assignContext, If_exprContext, IdContext, Pos_argsContext, Pos_argContext, Fun_callContext } from "../../parser/v4/generated/PineV4Parser.js";
+/** Anything carrying a source position (see the v1 base for why it is structural). */
+interface SourceLocated {
+    start?: {
+        line: number;
+        column: number;
+    } | null;
+}
+/** A declaration's `var` / `varip` modifier, or null when it has neither. */
+type Persistence = "var" | "varip" | null;
+export declare class V4ToJsVisitor extends V3ToJsVisitor {
+    protected readonly version: PineVersion;
+    /**
+     * v4's view of the stdlib: the base, minus the spellings v4 removed, plus the
+     * namespaced ones it introduced.
+     *
+     * Subtracting matters as much as adding. Leaving `red` in alongside
+     * `color.red` would accept both dialects, and a script written half in each
+     * would compile here and fail on TradingView — the exact class of divergence
+     * this engine exists to avoid.
+     */
+    protected get registry(): Record<string, StdlibEntry>;
+    /**
+     * From v4, a user-defined function MAY return a tuple.
+     *
+     * SOURCING. From the manual's user-defined functions page: "Programmers can
+     * write functions that return multiple values or references by using a tuple
+     * as the final statement in the function's body", with
+     *
+     *     sumDiff(float val1, float val2) =>
+     *         [val1 + val2, val1 - val2]
+     *
+     *     [sum, diff] = sumDiff(math.random(), math.random())
+     *
+     * and the rule for reading one back: "the script must use a tuple declaration
+     * containing one NEW variable for each returned item. It is not possible to
+     * reassign existing tuples or to use previously declared variables within
+     * them."
+     *
+     * v1–v3 keep the refusal — `conformance/common/guards_by_version.test.ts` has
+     * always declared the guard for those three and left v4 and v5 unstated, and
+     * this is the override that was missing. Eight of TradingView's own published
+     * scripts were rejected by it, including the one on its own error-messages
+     * page about tuples.
+     *
+     * Lifting the guard is the WHOLE change: `[a, b]` already emits a JavaScript
+     * array through `visitArith_exprs`, a body's last statement is already what a
+     * function returns, and `ctx.new_vars` already unpacks a built-in's tuple.
+     */
+    protected enforceNoTupleReturn(): void;
+    /**
+     * Rejects a v1–v3 spelling with the name that replaced it.
+     *
+     * Hooked on `visitId` rather than driven off the registry, because a missing
+     * registry entry is not by itself an error — `visitId` emits any identifier
+     * it does not recognise, since most identifiers are the script's own
+     * variables. So `red` at v4 would just emit `opsv2_red` and read as
+     * `undefined`: a colour that is silently `na`, on a chart that still draws.
+     */
+    protected enforceRenamedInV4(name: string, ctx: SourceLocated): void;
+    /**
+     * Is this identifier the CALLEE of a function call, rather than a read?
+     *
+     * Structural rather than `instanceof` — every version generates its own
+     * context classes, so `instanceof` is false across the hierarchy (see the
+     * note on `isRule` in the v1 base).
+     */
+    protected isCalleeOf(ctx: SourceLocated): boolean;
+    visitId(ctx: IdContext): string;
+    /** Reads the modifier off a declaration. Absent on every v1–v3 declaration. */
+    protected persistenceOf(ctx: Var_defContext | Var_defsContext): Persistence;
+    /**
+     * `var x = expr` initialises once and then holds its value across bars.
+     *
+     * The initialiser is emitted as a THUNK. `ctx.var_def` runs it on the first
+     * bar only, so `expr` is not re-evaluated afterwards — which matters both for
+     * cost and for correctness: `var t = timenow` must keep the first bar's
+     * timestamp, and passing an already-evaluated value would silently make it
+     * the current one every bar while still looking like it worked.
+     *
+     * The @L:C key is the DECLARATION SITE, not the name. Two `var`s of the same
+     * name in different scopes are different variables and must not share an
+     * initialised flag.
+     */
+    visitVar_def(ctx: Var_defContext): string;
+    /**
+     * `var [a, b] = f()` — the tuple form.
+     *
+     * Rejected rather than emitted wrongly. `ctx.new_vars` destructures a fresh
+     * call result into several series, and there is no once-only form of it: the
+     * honest options are to build one, or to say so. A wrong `var` here would
+     * re-run `f()` every bar while the script says it must not, and nothing
+     * downstream could detect that.
+     */
+    visitVar_defs(ctx: Var_defsContext): string;
+    /** Script-scope names declared with an explicit `int`, bound once. */
+    private readonly declaredInts;
+    /**
+     * "Value with NA type cannot be assigned to a variable that was defined
+     * without type keyword" — `x = na`, and the `b = na` of `var float a = na, b = na`,
+     * where the keyword covers `a` only. v1–v3 accept it, so this lives in v4.
+     *
+     * `int q = close` — a float stored in a declared int. Only when the
+     * initialiser is PROVABLY a float (see TypeRules.ts).
+     */
+    protected enforceDeclarationTypes(ctx: Var_defContext): void;
+    /** TradingView's wording, which differs by version. */
+    protected declaredIntMessage(name: string): string;
+    /**
+     * A float argument where a `series int` length is required. The first
+     * positional slot of these functions is the source, so only the second is
+     * read — `ta.highest(10)` has its length first and is left alone.
+     */
+    protected enforceIntLengthArgument(ctx: Fun_callContext): void;
+    /**
+     * A float where a drawing constructor's x coordinate (a `series int`) is
+     * required: `label.new(bar_index - 10.7, ...)` is a compile error on v4, v5
+     * and v6. `w / 2` between ints is no proof (see isProvablyFloat), so it still
+     * compiles. The `chart.point` overloads (v5/v6) take points, not coordinates,
+     * so only the 4-coordinate form (4+ positional args, or the x1/x2 keywords)
+     * is read.
+     */
+    protected enforceIntCoordinateArguments(ctx: Fun_callContext): void;
+    /** TradingView names a binary expression `call 'operator -' (series float)`; anything else is shown as written. */
+    private describeFloatOperand;
+    visitFun_call(ctx: any): string;
+    /**
+     * `tostring(x)` / `str.tostring(x)` of a constant number prints differently
+     * from the same call on a series (runtime/v1/stdlib/str.ts `numberToString`),
+     * and only the source can tell them apart. A call with no format whose
+     * argument is provably constant gets the runtime's CONST_DEFAULT marker in
+     * the format position.
+     */
+    private markConstTostring;
+    /**
+     * The arithmetic half of a compound assignment — `"+"` for `+=` — or null
+     * when the statement is a plain `:=`.
+     */
+    protected compoundOperatorOf(ctx: Var_assignContext): string | null;
+    /**
+     * `current <op> value`, emitted EXACTLY as the binary operator would be.
+     *
+     * TradingView defines `x += y` as "an arithmetic operator combined with the
+     * reassignment operator", so it has to mean precisely `x := x + y` — which
+     * for `+` and `-` is not the JavaScript operator. `opsv2_safe_add` is what
+     * `visitAdd_expr` emits, and it is what makes `na + 1` come out `na` and
+     * `"a" + "b"` concatenate. Emitting a raw `+` here would have made compound
+     * assignment the one place in the language where `na` behaved differently.
+     *
+     * `value` is parenthesised because not every emitted expression is
+     * self-contained: a comparison comes out as bare `a > b`, so `x *= a > b`
+     * would otherwise bind as `(x * a) > b`. (`and` and `or` used to be the
+     * example here, back when they emitted `a && b`; they are now a call to
+     * `ctx.allOf`, which brackets itself — see visitAnd_expr.)
+     */
+    protected compoundValue(op: string, current: string, value: string): string;
+    /**
+     * `x += expr`.
+     *
+     * Routed through the same guard as `:=` — the target must already be
+     * declared, which for a compound assignment is not a formality: there is no
+     * previous value to add to otherwise.
+     */
+    visitVar_assign(ctx: Var_assignContext): string;
+    /**
+     * `else if cond` — the else branch is another `if` rather than a block.
+     *
+     * Emitted INLINE, as one more `else if` on the JavaScript side, instead of
+     * by visiting the nested `if` normally. That distinction is the whole of the
+     * work here, and it is not a matter of taste:
+     *
+     *     x = if a
+     *             1
+     *         else if b
+     *             2
+     *         else
+     *             3
+     *
+     * A normal visit would give the nested `if` its own IIFE, producing
+     * `(() => { if (a) { return 1; } else (() => { … })(); })()` — the inner
+     * function computes 2 or 3 and the outer one throws the result away, so `x`
+     * is `undefined` on every bar that takes the `else`. No error; just an `na`
+     * where a number belongs.
+     *
+     * Recursing HERE keeps the whole chain inside the single wrapper
+     * `visitIf_expr` already opened, and inside the one `suppressBlockReturn`
+     * level it already set — so every arm of the chain returns, or does not,
+     * together.
+     */
+    protected emitElseBranch(ctx: If_exprContext): string | null;
+    /**
+     * v4's `pos_args` is a list of `pos_arg`, not of `arith_expr`. Overriding the
+     * SEAM rather than `visitPos_args` means `emitSecurity` — which walks the
+     * same list to defer its third argument into a thunk — picks the change up
+     * without knowing about it.
+     */
+    protected positionalArgs(ctx: Pos_argsContext): any[];
+    /** `arith_expr | arith_exprs` — a transparent wrapper either way. */
+    visitPos_arg(ctx: Pos_argContext): string;
+    /**
+     * `[o, h, l, c] = security(sym, "D", [open, high, low, close])`.
+     *
+     * The tuple is the ARGUMENT's, so its width is read off the bracketed list
+     * rather than out of the registry — `security` returns one value or four
+     * depending on what it was handed, and no single registry entry can say that.
+     *
+     * Both spellings are read, positional and keyword, because both appear in
+     * TradingView's own examples.
+     */
+    protected tupleArityFromArgument(call: Fun_callContext): number | null;
+    /**
+     * How many values this `expression` argument yields, when that is knowable.
+     *
+     * Two shapes, and the second is why this is not just `.arith_exprs()`:
+     *
+     *     [o, h, l, c] = request.security(sym, "D", [open, high, low, close])
+     *     [bop, avg]   = request.security(sym, "1D", dataFunction())
+     *
+     * The manual's own error-messages page uses the second — a call to a
+     * user-defined function whose body ends in a tuple. Its width is a fact about
+     * that DEFINITION, which `ScopeInfo.tupleArity` collected for exactly this.
+     */
+    protected expressionArity(node: any): number | null;
+    /**
+     * The call this expression consists of ENTIRELY, or null.
+     *
+     * Only a single-child spine is followed, so `f() + 1` is not `f()`: the
+     * arithmetic makes it one value however many `f` returns.
+     */
+    protected soleCall(node: any): any | null;
+}
+export {};