oakscriptjs 0.13.2 → 0.14.0

package/skills/oakscript/examples/ma-cross.js

@@ -27,8 +27,8 @@ fill(fastPlot, slowPlot, {
 
 const crossUp = ta.crossover(fast, slow);
 const crossDown = ta.crossunder(fast, slow);
-plotshape(crossUp, "Cross up", { style: "triangleup", location: "belowbar", color: color.teal, size: "small" });
-plotshape(crossDown, "Cross down", { style: "triangledown", location: "abovebar", color: color.red, size: "small" });
+plotshape(crossUp, "Cross up", { style: shape.triangleup, location: location.belowbar, color: color.teal, size: size.small });
+plotshape(crossDown, "Cross down", { style: shape.triangledown, location: location.abovebar, color: color.red, size: size.small });
 
 alertcondition(crossUp, "Cross up", "Fast MA crossed above the slow MA");
 alertcondition(crossDown, "Cross down", "Fast MA crossed below the slow MA");

package/skills/oakscript/examples/mtf-trend-filter.js

@@ -33,14 +33,14 @@ const signal = eachBar((c) => {
   return 0;
 });
 
-plotshape(signal.eq(1), "Long", { style: "labelup", location: "belowbar", color: color.teal, text: "L", textcolor: color.white });
-plotshape(signal.eq(-1), "Short", { style: "labeldown", location: "abovebar", color: color.red, text: "S", textcolor: color.white });
+plotshape(signal.eq(1), "Long", { style: shape.labelup, location: location.belowbar, color: color.teal, text: "L", textcolor: color.white });
+plotshape(signal.eq(-1), "Short", { style: shape.labeldown, location: location.abovebar, color: color.red, text: "S", textcolor: color.white });
 bgcolor(color.when(upTrend, color.new(color.teal, 92), color.new(color.red, 92)), { title: "Trend" });
 
 // One label on the last bar with the filter state.
 eachBar((c) => {
   if (c.i === c.n - 1) {
     const text = (c.get(upTrend) === 1 ? "Uptrend " : "Downtrend ") + filterTf;
-    label.new(c.i, c.high, text, "bar_index", "price", color.gray, "label_down", color.white);
+    label.new(c.i, c.high, text, { color: color.gray, style: label.style_label_down, textcolor: color.white });
   }
 });

package/skills/oakscript/reference/check.md

@@ -0,0 +1,150 @@
+# Checking a script: `oakscript check`
+
+`oakscript check` runs a script the way an app runs it (the declarations on zero bars, then a run on bars) and
+prints what it declares and what it outputs, the errors with their line, warnings for the mistakes that give no error,
+and the result of a spec: the inputs, outputs and signals the user asked for.
+
+```sh
+npx oakscript check my-indicator.js                       # synthetic bars (1,500, hourly)
+npx oakscript check my-indicator.js --spec spec.json      # + the user's spec (and its checks file)
+npx oakscript check my-indicator.js --scenarios           # + edge-case bars
+npx oakscript check my-port.js --export chart-export.csv  # + bars and expected values of a chart export
+```
+
+Exit code: `0` clean, `2` warnings only, `1` an error or a failed spec / reference check. Run it after each change
+until it gives `0` (or `2` with warnings you have read and explained).
+
+## Workflow
+
+1. Write the spec from the user's request **before** the script (below): title, pane, inputs with their defaults,
+   outputs, what the signals should look like; and a checks file for the behaviour the spec cannot count ("Buy only
+   when the RSI is below 30"). Add `"scenarios": true`.
+2. Write the script.
+3. `npx oakscript check script.js --spec spec.json`; fix the errors, then the failed spec items and checks, then
+   read the warnings.
+4. For a port of a Pine script with known values, add `--export` (or `--bars` and `--reference`).
+
+## What it checks
+
+| Stage | Reports |
+|---|---|
+| types | TypeScript errors of the script with the script globals (`TS2362` operator on a Series, `TS2551` unknown name...), when `typescript` is installed in the project; `--no-types` skips it |
+| syntax | the JavaScript syntax error and its line |
+| declaration | errors of the top-level code (the declaration run of an app), e.g. `close - open` |
+| run | errors on the bars (inside `eachBar`), with the line |
+| timeout | a run longer than `--timeout` (default 10 s) |
+| spec | an unknown key or a wrong value in the spec (`"signal"` for `"signals"`): a misspelt spec would check nothing |
+| scenario | an error on the edge-case bars of `--scenarios` |
+
+Then, on a clean run: the inputs (id, type, default, options), each plot (number of values, first bar, min / max,
+last 5 values, colours), each signal (shapes, characters, arrows, alert conditions, background and bar colours: bars,
+share, first and last bar), drawings, `alert()` calls, and for a strategy the trades (count, wins, net profit, the
+first trades) on a small built-in order engine (next-bar-open fills, stop / limit exits).
+
+## Warnings
+
+| Code | Meaning |
+|---|---|
+| `empty-plot` | a plot with no value (na on every bar) |
+| `constant-plot` | the same value on every bar (a level is an `hline()`) |
+| `late-start` | the first value after half of the bars |
+| `signal-never` | a signal that is never true |
+| `signal-everywhere` | a signal on more than half of the bars: often a Series used as a JavaScript boolean |
+| `one-colour` | per-bar colours that are the same on every bar |
+| `unused-input` | changing the input changes no output (the check runs again with each input changed) |
+| `input-error` | another valid value of the input stops the script |
+| `no-trades` | a strategy without any trade |
+| `no-output` | nothing is drawn |
+
+A warning is not always a mistake (a rare signal on 1,500 bars): read it and keep it when it is what the user wants.
+
+## The spec
+
+A JSON file; every entry is optional and only the given ones are checked. Inputs, plots and signals are found by id
+or title (case insensitive). An unknown key or a wrong value is an error (with the closest key), so a misspelt entry
+does not pass unchecked. Its JSON Schema is `node_modules/oakscriptjs/skills/oakscript/spec.schema.json`: point
+`$schema` at it to get the keys in an editor.
+
+```json
+{
+  "$schema": "./node_modules/oakscriptjs/skills/oakscript/spec.schema.json",
+  "kind": "indicator",
+  "title": "MACD Histogram",
+  "overlay": false,
+  "inputs": {
+    "fast_length": { "type": "int", "defval": 12 },
+    "Source": { "type": "source", "defval": "close" },
+    "MA type": { "options": ["SMA", "EMA"] }
+  },
+  "outputs": ["MACD", "Signal", { "title": "Zero", "kind": "hline" }],
+  "plots": { "MACD": { "warmup": 40 }, "RSI": { "min": 0, "max": 100 } },
+  "signals": { "Buy": { "min": 1, "maxShare": 0.1 } },
+  "trades": { "min": 1 },
+  "checks": "checks.js",
+  "scenarios": true,
+  "reference": "expected.csv",
+  "tolerance": 1e-10
+}
+```
+
+- `outputs`: titles that must exist; `kind` is one of `plot`, `shape`, `char`, `arrow`, `candle`, `bar`, `hline`,
+  `bgcolor`, `barcolor`, `alertcondition`.
+- `plots`: `min` / `max` bound every value, `warmup` is the latest bar of the first value.
+- `signals`: `min` / `max` count bars, `minShare` / `maxShare` the share of the bars (0 to 1).
+- `checks`, `scenarios`, `reference`, `export`, `tolerance`: as `--checks`, `--scenarios`, `--reference`, `--export`,
+  `--tolerance` (paths relative to the spec file).
+
+## Behaviour checks
+
+What a spec cannot write as counts and ranges goes in a checks file: plain JavaScript, the body of a function of `t`
+(no import or export). `t.plot(name)` gives a plot per bar (`values`, `at(i)`, `colors`), `t.signal(name)` the bars of
+a signal (`bars`, `on(i)`), `t.trades` the closed trades of a strategy, `t.input(name)` the value of an input, `t.bars`
+and `t.n` the bars. Record each check with `t.expect(name, ok, detail?)` or `t.everyBar(name, (i) => ..., { from, to })`
+(it fails on the first bar where the function is false).
+
+```js
+const rsi = t.plot("RSI");
+t.everyBar("RSI between 0 and 100", (i) => rsi.at(i) === null || (rsi.at(i) >= 0 && rsi.at(i) <= 100));
+t.expect("Buy only when the RSI is below 30", t.signal("Buy").bars.every((i) => rsi.at(i) < 30));
+t.expect("Buy right after the RSI was at or above 30", t.signal("Buy").bars.every((i) => rsi.at(i - 1) >= 30));
+```
+
+The checks run on the main run; their results come after the spec items. An error in the file (an unknown plot, a
+typo) fails the checks with its line.
+
+## Scenarios
+
+`--scenarios` (or `"scenarios": true`) runs the script again on edge-case bars: 30 bars (a short history), 800 daily
+bars, 1,000 one-minute bars, 200 flat bars (zero ranges, no volume), 500 bars without volume, and a 3-day gap. An
+error there fails the check; a plot with no value that the main run does not have is listed per scenario (on 30
+bars it is often expected, a division by a zero range is not).
+
+## Bars and reference files
+
+- `--bars`: CSV with the columns `time` (UNIX seconds or milliseconds, or a date), `open`, `high`, `low`, `close`,
+  optional `volume`; or a JSON array of `{ time, open, high, low, close, volume }`. The timeframe comes from the bar
+  spacing unless `--timeframe` gives it. Other symbols of `request.security` get synthetic bars.
+- `--reference`: CSV with a `time` column and one column per plot (id or title); empty or `na` is na. A value is
+  equal when `|a - b| <= tolerance * max(1, |a|, |b|)` (default `1e-10`) or both are na. Use the bars the reference
+  was computed on. The bar columns (`open`, `high`, `low`, `close`, `volume`) are skipped.
+- `--export`: one CSV with both: the chart data exported with the original script on the chart (a `time` column,
+  the bars, then one column per plot title, as charting apps export them). The bars are the bars of the run, the
+  other columns the expected values; a column with no plot of that title (another script on the chart) is ignored.
+
+## Other options
+
+`--inputs '{"length": 50}'` (input values by id), `--count 3000` (synthetic bars), `--timeframe D`, `--no-sweep`
+(no reruns for unused inputs), `--json` (the whole report as JSON).
+
+## From code
+
+```ts
+import { assertCheck, checkScript } from 'oakscriptjs/check';
+const report = checkScript(source, { spec, bars, scenarios: true, checks: (t) => { /* as a checks file */ } });
+// report.ok, errors, warnings, plots, signals, spec, reference, scenarios
+
+// in a test of any runner: throws the report as text when the check fails ({ warnings: false }: also on warnings)
+assertCheck(checkScript(source, { spec }));
+```
+
+`checkScript` runs anywhere (no Node API); the command adds the file lines, the time limit and the type check.

package/skills/oakscript/reference/errors.md

@@ -1,7 +1,22 @@
 # Errors and how to read them
 
 A script fails in one of three ways: it does not compile, it stops with a runtime error, or it runs and gives a
-wrong output. Fix them in that order, then check the values.
+wrong output. Fix them in that order, then check the values. `npx oakscript check script.js` ([check](check.md))
+reports all three, with the lines, and warns about the silent mistakes of the last table.
+
+## Type-check errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `TS2362` / `TS2363` `The left-hand (right-hand) side of an arithmetic operation must be of type...` | `close - open`, `rsi * 2` | Series methods: `close.sub(open)`, `rsi.mul(2)` |
+| `TS2365` `Operator '>' cannot be applied to types 'Series' and 'number'` | `rsi > 50`, `c.close > ta.sma(close, 5)` in a loop | `rsi.gt(50)`; in a loop `c.close > c.get(sma)` with `sma` computed before |
+| `TS2339` / `TS2551` `Property 'smaa' does not exist on type...` | a misspelt or Pine-only name | the name it suggests, [pine-differences.md](pine-differences.md) |
+| `TS2322` `Type '"triangel"' is not assignable to type 'ShapeStyle'` | a bad constant string | one of the strings it lists |
+| `TS2561` / `TS2353` `Object literal may only specify known properties` | a misspelt option (`colour`) | the option it suggests |
+| `TS2554` `Expected 4 arguments, but got 3` | a missing argument (`ta.stoch(close, high, low)`) | pass it: `ta.stoch(close, high, low, 14)` |
+| `TS2339` `Property 'entry_price' does not exist on type 'number'` | `strategy.opentrades.entry_price(0)` (`strategy.opentrades` is the count) | `strategy.opentrade(0)?.entry_price`, `strategy.closedtrade(i)?.profit` |
+| `TS2769` `No overload matches this call` on a drawing | a misspelt named argument (`{ textcolour: ... }`) | the Pine name (`textcolor`) |
+| `TS8010` `Type annotations can only be used in TypeScript files` | TypeScript syntax | remove the types |
 
 ## Compile errors (syntax)
 
@@ -22,9 +37,18 @@ The run stops at the first error; the message names the call. The ones you will
 
 | Message | Cause | Fix |
 |---|---|---|
-| `TypeError: series.toArray is not a function` | a number or NaN passed where a Series is expected: `plot(close - open)`, `plot(5)`, `ta.sma(a * 2, 10)` | Series methods: `close.sub(open)`, `a.mul(2)`; a constant level: `hline(5)` |
-| `TypeError: ta.xyz is not a function` / `xyz is not defined` | a name that does not exist (typo, Pine-only name such as `shape`, `location`, `size`, `xloc`, `bar_index`) | [pine-differences.md](pine-differences.md): strings for the constants, `c.i` for `bar_index` |
-| `TypeError: Cannot read properties of undefined (reading 'toArray')` | a missing Series argument, e.g. `ta.vwma(close, 20)` | pass it: `ta.vwma(close, 20, volume)` |
+| `TypeError: JavaScript operators (+ - * / % ** < > <= >= ==) do not work on a Series: use its methods...` | an operator on a Series: `close - open`, `rsi > 50`, `fast > slow ? a : b` | the method it lists: `close.sub(open)`, `rsi.gt(50)`, `fast.gt(slow).iff(a, b)`; a colour: `color.when(fast.gt(slow), a, b)` |
+| `TypeError: A Series is not a text...` | a Series in a text: `` `RSI ${rsi}` ``, `"RSI " + rsi` | in a loop: `str.tostring(c.get(rsi))` |
+| `ta.sma() was called inside eachBar(): a ta.* call computes the whole Series at once...` | a `ta.*` function in a bar callback | compute it before the loop, read it with `c.get(x)`; a Pine call in an `if` block: `callsite.*` |
+| `TypeError: ta.smaa does not exist. Did you mean ta.sma?` (also `math.`, `str.`, `color.`, `input.`, `request.`) | a misspelt or Pine-only member | a suggested name, [pine-differences.md](pine-differences.md) |
+| `TypeError: series.toArray is not a function` | a number or NaN passed where a Series is expected: `plot(5)`, `ta.sma(c.close, 10)` | a Series; a constant level: `hline(5)` |
+| `xyz is not defined` | a global that does not exist (Pine-only name such as `shape`, `location`, `size`, `xloc`, `bar_index`) | [pine-differences.md](pine-differences.md): strings for the constants, `c.i` for `bar_index` |
+| `TypeError: Cannot read properties of undefined (reading 'toArray')` | a missing Series argument, e.g. `ta.stoch(close, high, low)` | pass it: `ta.stoch(close, high, low, 14)` |
+| `TypeError: label.new(): unknown argument "textcolour". Did you mean textcolor?` | a misspelt named argument of a drawing | the name it suggests |
+| `TypeError: input.int(): unknown argument "min". Did you mean minval?` | an input option that is not Pine's (`min`, `max`, `choices`) | Pine's name: `minval`, `maxval`, `options` |
+| `TypeError: request.security(): unknown argument "lookahed"...` | a misspelt named argument of `request.security` | `gaps`, `lookahead`, `ignore_invalid_symbol` |
+| `TypeError: label.new(): argument 1 is a Series, a drawing takes one value: call label.new() inside eachBar()...` | a drawing created at the top level with a Series (`label.new(bar_index, high)`) | create it in a bar loop |
+| `TypeError: strategy.opentrades.entry_price is not a function` | `strategy.opentrades` is the count | `strategy.opentrade(0)?.entry_price` |
 | `Error on bar N: Invalid value of the 'length' argument (0.0) in the 'sma' function. It must be > 0.` | a length of 0, negative or NaN (often an input) | `minval: 1` on the input, or guard the value |
 | `Error on bar N: The 'sma' function references too many historical candles (6000), the limit is 5000.` | a window longer than 5000 bars | a shorter length |
 | `Error on bar N: The script attempts to reference historical data that is too far from the current bar (K bars back)...` | `x.offset(k)` / `c.get(x, k)` with k above 5000, or a history that keeps growing (`c.get(x, c.i)`) | bounded offsets |
@@ -49,9 +73,9 @@ The run stops at the first error; the message names the call. The ones you will
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| a branch taken on every bar, or never | `if (ta.crossover(a, b))`, `cond ? x : y`, `a > b` with Series at the top level: an object is always true, an object comparison always false | `cond.iff(x, y)`, `a.gt(b)`, or `c.get(cond) === 1` in a loop |
-| one colour on every bar | `color: fast > slow ? color.green : color.red` | `color.when(fast.gt(slow), color.green, color.red)` |
-| an empty plot | NaN on every bar: a `ta.*` Series returned from a bar loop, a division by zero, a NaN input | compute `ta.*` before the loop, guard divisions (`range.gt(0).iff(x.div(range), 0)`) |
+| a branch taken on every bar | `if (ta.crossover(a, b))`, `cond ? x : y`, `!cond`, `cond && x` with a Series `cond`: an object is always true | `cond.iff(x, y)`, `cond.not()`, `cond.and(x)`, or `c.get(cond) === 1` in a loop |
+| one colour on every bar | `color: cond ? color.green : color.red` with a Series `cond` | `color.when(cond, color.green, color.red)` |
+| an empty plot | NaN on every bar: a division by zero, a NaN input | guard divisions (`range.gt(0).iff(x.div(range), 0)`) |
 | a plot that starts late | the warm-up of long lengths, or of a higher timeframe (20 daily bars on an hourly chart is 480 bars) | expected; shorter lengths or more bars |
 | values that look like the future (backtests too good) | `barmerge.lookahead_on` on a series that is not offset | lookahead off, or `.offset(1)` inside the expression |
 | a strategy without trades | conditions read as `c.get(cond)` on NaN-only Series, orders placed outside the conditions you expect, `pyramiding: 0` blocking a second entry in the same direction | plot the conditions (`plotshape`) and check them first |

package/skills/oakscript/reference/pine-differences.md

@@ -10,8 +10,8 @@ from the vectorized execution.
 |---|---|
 | `//@version=6` | nothing |
 | `indicator("T", overlay=true)` | `indicator("T", { overlay: true })` |
-| `len = input.int(14, "Length", minval=1)` | `const len = input.int(14, "Length", { minval: 1 })` |
-| `src = input.source(close, "Source")` | `const src = input.source("close", "Source")` (the default is a name) |
+| `len = input.int(14, "Length", minval=1)` | `const len = input.int(14, "Length", { minval: 1 })` or `input.int(14, { title: "Length", minval: 1 })` |
+| `src = input.source(close, "Source")` | `const src = input.source(close, "Source")` |
 | `a + b`, `a - b`, `a * b`, `a / b` on series | `a.add(b)`, `a.sub(b)`, `a.mul(b)`, `a.div(b)` |
 | `a > b`, `a == b`, `a and b`, `not a` on series | `a.gt(b)`, `a.eq(b)`, `a.and(b)`, `a.not()` |
 | `cond ? x : y` on series | `cond.iff(x, y)` |
@@ -21,27 +21,30 @@ from the vectorized execution.
 | `if close > open` (per bar) | in a bar loop: `if (c.close > c.open)` |
 | `for i = 0 to n - 1` | `for (let i = 0; i < n; i++)` in a bar loop |
 | `switch` / `if` returning a value | JS `switch` / `if` in a bar loop, or `iff` chains on Series |
-| `bar_index`, `last_bar_index` | `c.i`, `c.n - 1` |
+| `bar_index`, `last_bar_index` | the Series `bar_index`, `last_bar_index`; in a bar loop `c.i`, `c.n - 1` |
 | `myFunc(x) => ...` | a JS `function`; on Series it composes Series methods |
 | `[a, b] = f()` | `const [a, b] = f()` |
 | `plot(x, "T", color=c, style=plot.style_columns)` | `plot(x, "T", { color: c, style: plot.style_columns })` |
 | `plot(x, color = cond ? c1 : c2)` | `plot(x, "T", { color: color.when(cond, c1, c2) })` |
-| `plotshape(cond, style=shape.triangleup, location=location.belowbar, size=size.small)` | `plotshape(cond, "T", { style: "triangleup", location: "belowbar", size: "small" })` |
-| `label.new(bar_index, high, "A", style=label.style_label_down)` | `label.new(c.i, c.high, "A", undefined, undefined, undefined, "label_down")` (positional) |
-| `line.new(x1, y1, x2, y2, extend=extend.right)` | `line.new(x1, y1, x2, y2, "bar_index", "right")` |
-| `xloc.bar_time`, `yloc.abovebar`, `line.style_dashed`, `format.volume`, `display.none` | `"bar_time"`, `"abovebar"`, `"dashed"`, `"volume"`, `"none"` |
-| `dayofweek.monday` | `2` (1 = Sunday ... 7 = Saturday) |
+| `plotshape(cond, style=shape.triangleup, location=location.belowbar, size=size.small)` | `plotshape(cond, "T", { style: shape.triangleup, location: location.belowbar, size: size.small })` |
+| `label.new(bar_index, high, "A", style=label.style_label_down)` (in an `if`) | in a bar loop: `label.new(bar_index, high, "A", { style: label.style_label_down })` (or `c.i`, `c.high`) |
+| `line.new(x1, y1, x2, y2, extend=extend.right)` | `line.new(x1, y1, x2, y2, { extend: extend.right })` |
+| `xloc.bar_time`, `yloc.abovebar`, `line.style_dashed`, `format.volume`, `display.none`, `dayofweek.monday` | the same |
 | `request.security(sym, "D", ta.ema(close, 20))` | `request.security(sym, "D", () => ta.ema(close, 20))` |
+| `request.security(sym, "W", high[1], lookahead = barmerge.lookahead_on)` | `request.security(sym, "W", () => high.offset(1), { lookahead: barmerge.lookahead_on })` |
 | `strategy.entry("L", strategy.long, when = cond)` | `strategy.eachBar((c) => { if (c.get(cond) === 1) strategy.entry("L", strategy.long); })` |
-| `strategy.opentrades.entry_price(0)` | `strategy.opentrade(0)?.entry_price` |
+| `strategy.opentrades.entry_price(0)` | `strategy.opentrade(0)?.entry_price` (`strategy.opentrades` is the count: a JavaScript number cannot also hold the functions) |
 | `strategy.closedtrades.profit(i)` | `strategy.closedtrade(i)?.profit` |
 | `array.new_float(10, 0)`, `matrix.new<float>()`, `map.new<string, float>()` | `import { array, matrix, map } from "oakscriptjs";` then `array.new_float(10, 0)`, `matrix.new_matrix(...)`, `map.new_map()`; or plain JS arrays / `Map` |
 | `log.info("x = " + str.tostring(x))` | not available: plot it with `display: "data_window"` or put it in a label |
 
-Constants that **do** exist as namespaces: `color.*`, `plot.style_*`, `plot.linestyle_*`, `hline.style_*`,
+The Pine constants exist with their Pine names: `shape.*`, `location.*`, `size.*`, `xloc.*`, `yloc.*`,
+`extend.*`, `display.*`, `format.*`, `font.family_*`, `scale.*`, `order.*`, `currency.*`, `adjustment.*`,
+`label.style_*`, `line.style_*`, `dayofweek.*`, `color.*`, `plot.style_*`, `plot.linestyle_*`, `hline.style_*`,
 `strategy.long / short / fixed / cash / percent_of_equity`, `strategy.commission.*`, `strategy.direction.*`,
 `strategy.oca.*`, `barmerge.*`, `position.*`, `text.align_* / wrap_* / format_*`, `alert.freq_*`,
-`session.regular / extended`, `math.pi / e / phi / rphi`.
+`session.regular / extended`, `math.pi / e / phi / rphi`. Their values are the strings the functions take
+(`shape.triangleup` is `"triangleup"`).
 
 ## Execution differences
 
@@ -62,16 +65,14 @@ Constants that **do** exist as namespaces: `color.*`, `plot.style_*`, `plot.line
 
 ## API differences
 
-- `ta.vwma(source, length, volume)` needs the volume Series (Pine reads the chart volume).
 - `color.from_gradient` takes numbers: build per-bar gradients in a bar loop.
-- `plot()` has no `offset`, `show_last`, `trackprice` or `join` option; shift a series right with
-  `x.offset(k)`. `plotshape`, `plotchar`, `plotarrow` and `bgcolor` accept `offset` (negative too).
+- `plot()` has no `show_last`, `trackprice` or `join` option. `offset` shifts the plot as in Pine (values past the
+  first or last bar are not drawn).
 - `fill()` accepts `show_last` / `fillgaps` / `display` and ignores them.
-- `input.enum` and `input.price` do not exist (use `input.string(..., { options })` and `input.float`).
+- `input.enum` does not exist (no `enum` declarations): use `input.string(..., { options })`.
 - `request.*`: only `request.security` and `request.security_lower_tf`. No `request.financial`,
   `request.dividends`, `request.earnings`, `request.splits`, `request.economic`, `request.seed`,
   `request.currency_rate`, `request.footprint`. `ticker.*`: only `ticker.heikinashi` and `ticker.standard`.
-- `box.set_xloc()` is not implemented.
 - `math.random(min, max, seed)`: with a seed, Pine's sequence, but one generator per seed value (Pine has one
   per call site): two calls with the same seed need `callsite.random(seed)`.
 - `math.log`, `math.exp`, `math.pow`, `math.sin`, `math.cos`, `math.tan`, `math.log10` can differ from Pine in

package/skills/oakscript/reference/plotting.md

@@ -75,10 +75,11 @@ Note: `ta.bb` returns `[basis, upper, lower]` as in Pine.
 ## Shapes, characters, arrows
 
 - `plotshape(cond, title, { style, location, color, text, textcolor, size, offset, tooltip })`: a shape on
-  each bar where `cond` is not 0 / na. `style`: `"xcross"` (default), `"cross"`, `"triangleup"`,
-  `"triangledown"`, `"flag"`, `"circle"`, `"arrowup"`, `"arrowdown"`, `"labelup"`, `"labeldown"`, `"square"`,
-  `"diamond"`. `location`: `"abovebar"` (default), `"belowbar"`, `"top"`, `"bottom"`, `"absolute"` (at the
-  series value). `size`: `"auto"`, `"tiny"`, `"small"`, `"normal"`, `"large"`, `"huge"`.
+  each bar where `cond` is not 0 / na. `style`: `shape.xcross` (default), `shape.cross`, `shape.triangleup`,
+  `shape.triangledown`, `shape.flag`, `shape.circle`, `shape.arrowup`, `shape.arrowdown`, `shape.labelup`,
+  `shape.labeldown`, `shape.square`, `shape.diamond`. `location`: `location.abovebar` (default), `location.belowbar`,
+  `location.top`, `location.bottom`, `location.absolute` (at the series value). `size`: `size.auto`, `size.tiny`,
+  `size.small`, `size.normal`, `size.large`, `size.huge`.
 - `plotchar(cond, title, { char, location, color, size, offset })`: a character.
 - `plotarrow(series, title, { colorup, colordown, minheight, maxheight })`: an up arrow for a positive value,
   a down arrow for a negative one.
@@ -86,11 +87,11 @@ Note: `ta.bb` returns `[basis, upper, lower]` as in Pine.
 ```js
 indicator("Markers", { overlay: true });
 const ema = ta.ema(close, 20);
-plotshape(ta.crossover(close, ema), "Buy", { style: "labelup", location: "belowbar", color: color.green, text: "Buy", textcolor: color.white });
-plotshape(ta.crossunder(close, ema), "Sell", { style: "labeldown", location: "abovebar", color: color.red, text: "Sell", textcolor: color.white });
+plotshape(ta.crossover(close, ema), "Buy", { style: shape.labelup, location: location.belowbar, color: color.green, text: "Buy", textcolor: color.white });
+plotshape(ta.crossunder(close, ema), "Sell", { style: shape.labeldown, location: location.abovebar, color: color.red, text: "Sell", textcolor: color.white });
 // a pivot is known 5 bars later: offset -5 puts the mark on the pivot bar; "absolute" places it at the value
-plotshape(ta.pivothigh(5, 5), "Pivot high", { style: "diamond", location: "absolute", offset: -5, color: color.orange, size: "tiny" });
-plotchar(ta.pivotlow(5, 5), "Pivot low", { char: "^", location: "belowbar", offset: -5, color: color.teal });
+plotshape(ta.pivothigh(5, 5), "Pivot high", { style: shape.diamond, location: location.absolute, offset: -5, color: color.orange, size: size.tiny });
+plotchar(ta.pivotlow(5, 5), "Pivot low", { char: "^", location: location.belowbar, offset: -5, color: color.teal });
 plotarrow(ta.change(close, 3), "3-bar change", { colorup: color.teal, colordown: color.red });
 plot(ema, "EMA");
 ```
@@ -131,21 +132,26 @@ plotcandle(haOpen, seriesOf(highs), seriesOf(lows), haClose, "HA", {
 
 ## Drawings
 
-Drawings are created in a bar loop, with **positional** arguments in the Pine order and string constants. Skip
-an argument with `undefined`.
+Drawings are created in a bar loop, with the Pine arguments: the first ones by position, the others by name in an
+object after them (Pine's named arguments), e.g. `label.new(c.i, c.high, "A", { style: label.style_label_down })`.
+Every argument can be named (`line.new({ x1, y1, x2, y2, extend: extend.right })`); an unknown name throws with the
+closest names. In the loop, a Series argument is its value on the current bar: `label.new(bar_index, high, "A")` is
+`label.new(c.i, c.high, "A")`.
 
 | Call | Arguments |
 |---|---|
-| `label.new` | `x, y, text, xloc ("bar_index" / "bar_time"), yloc ("price" / "abovebar" / "belowbar"), color, style, textcolor, size, textalign, tooltip` |
-| `line.new` | `x1, y1, x2, y2, xloc, extend ("none" / "left" / "right" / "both"), color, style ("solid" / "dashed" / "dotted" / "arrow_left" / "arrow_right" / "arrow_both"), width` |
-| `box.new` | `left, top, right, bottom, border_color, border_width, border_style, extend, xloc, bgcolor, text, text_size, text_color` |
+| `label.new` | `x, y, text, xloc (xloc.bar_index / xloc.bar_time), yloc (yloc.price / yloc.abovebar / yloc.belowbar), color, style, textcolor, size, textalign, tooltip, text_font_family, force_overlay, text_formatting` |
+| `line.new` | `x1, y1, x2, y2, xloc, extend (extend.none / left / right / both), color, style (line.style_solid / dashed / dotted / arrow_left / arrow_right / arrow_both), width, force_overlay` |
+| `box.new` | `left, top, right, bottom, border_color, border_width, border_style, extend, xloc, bgcolor, text, text_size, text_color, text_halign, text_valign, text_wrap, text_font_family, force_overlay, text_formatting` |
 | `table.new` | `position, columns, rows, bgcolor, frame_color, frame_width, border_color, border_width` |
-| `table.cell` | `table, column, row, text, width, height, text_color, text_halign, text_valign, text_size, bgcolor, tooltip` |
+| `table.cell` | `table_id, column, row, text, width, height, text_color, text_halign, text_valign, text_size, bgcolor, tooltip, text_font_family, text_formatting` |
 | `polyline.new` | `points (chart.point.from_index(i, price)...), curved, closed, xloc, line_color, fill_color, line_style, line_width` |
 | `linefill.new` | `line1, line2, color` |
 
-Label styles: `"label_down"`, `"label_up"`, `"label_left"`, `"label_right"`, `"label_center"`, `"none"`, and the
-shape names. `x` is a bar index (`c.i`, or `c.i + 10` for a future bar) or, with `"bar_time"`, a UNIX time in ms.
+Label styles: `label.style_label_down`, `label.style_label_up`, `label.style_label_left`, `label.style_label_right`,
+`label.style_label_center`, `label.style_none`, and `label.style_<shape>`. `x` is a bar index (`c.i`, or `c.i + 10`
+for a future bar) or, with `xloc.bar_time`, a UNIX time in ms. The constants are the strings (`"label_down"`), which
+also work.
 Positions of tables: `position.top_right`, `position.bottom_left`...
 
 ```js
@@ -156,11 +162,11 @@ const lo = ta.lowest(50);
 eachBar((c) => {
   const p = c.get(ph);
   if (!Number.isNaN(p)) {
-    label.new(c.i - 5, p, str.tostring(p, "#.##"), "bar_index", "price", color.red, "label_down", color.white, "small");
+    label.new(c.i - 5, p, str.tostring(p, "#.##"), { color: color.red, style: label.style_label_down, textcolor: color.white, size: size.small });
   }
   if (c.i === c.n - 1) {
-    line.new(c.i - 49, c.get(hi), c.i + 10, c.get(hi), "bar_index", "none", color.green, "dashed", 2);
-    box.new(c.i - 49, c.get(hi), c.i, c.get(lo), color.gray, 1, "dotted", "none", "bar_index", color.new(color.gray, 90), "50-bar range");
+    line.new(c.i - 49, c.get(hi), c.i + 10, c.get(hi), { color: color.green, style: line.style_dashed, width: 2 });
+    box.new(c.i - 49, c.get(hi), c.i, c.get(lo), { border_color: color.gray, border_style: line.style_dotted, bgcolor: color.new(color.gray, 90), text: "50-bar range" });
     const t = table.new(position.bottom_right, 1, 1, color.new(color.black, 30));
     table.cell(t, 0, 0, "Range " + str.tostring(c.get(hi) - c.get(lo), "#.##"), 0, 0, color.white);
   }

package/skills/oakscript/reference/script-structure.md

@@ -19,7 +19,7 @@ values they plot.
 ```js
 indicator("Average True Range Bands", {
   shorttitle: "ATR Bands", // legend title
-  overlay: true,           // default true: price pane; false: own pane
+  overlay: true,           // true: price pane; false (default): own pane
   precision: 2,            // decimals shown
   max_labels_count: 100,   // also max_lines_count, max_boxes_count, max_polylines_count (default 50)
 });
@@ -29,7 +29,7 @@ plot(close.sub(atr.mul(2)), "Lower");
 ```
 
 `strategy(title, options)` replaces `indicator()` for a strategy (default `overlay: false`); its properties are in
-[strategies.md](strategies.md). A script without a declaration runs with the title "Untitled" and overlay on.
+[strategies.md](strategies.md). A script without a declaration runs with the title "Untitled" in its own pane.
 
 ## Inputs
 
@@ -50,7 +50,10 @@ override when there is one, else the default.
 | `input.symbol("NASDAQ:AAPL", title)` | ticker id for `request.security` |
 | `input.time(timestamp("2024-01-01"), title)` | UNIX time in ms |
 
-Options of every kind: `group`, `inline`, `tooltip`, `confirm`, `display`, `active` (false greys the input out).
+Options of every kind: `group`, `inline`, `tooltip`, `confirm`, `display`, `active` (false greys the input out). They
+have Pine's names (`minval`, not `min`): an unknown name throws with the closest names. The title can also be in the
+options object (`input.int(14, { title: "Length", minval: 1 })`), or every argument named (`input.int({ defval: 14,
+title: "Length" })`).
 
 ```js
 indicator("Inputs demo");
@@ -132,7 +135,7 @@ const trail = eachBar((c) => {
 });
 const up = seriesOf(dirs).eq(1);
 plot(trail, "Stop", { style: plot.style_linebr, color: color.when(up, color.teal, color.red) });
-plotshape(up.and(up.offset(1).not()), "Flip up", { style: "circle", location: "belowbar", color: color.teal, size: "tiny" });
+plotshape(up.and(up.offset(1).not()), "Flip up", { style: shape.circle, location: location.belowbar, color: color.teal, size: size.tiny });
 ```
 
 - A `let` before the loop is Pine `var`: it keeps its value from bar to bar. A `const` inside the callback is a
@@ -169,7 +172,7 @@ executeScript(body, bars, inputs, { ... })".
 indicator("Session marks", { overlay: true });
 const newDay = timeframe.change("D");
 bgcolor(color.when(newDay, color.new(color.blue, 80)), { title: "New day" });
-plotchar(barstate.islast, "Last", { char: "L", location: "abovebar" });
+plotchar(barstate.islast, "Last", { char: "L", location: location.abovebar });
 plot(close, "Close", { display: "none" });
 ```
 

package/skills/oakscript/reference/timeframes-symbols.md

@@ -35,10 +35,14 @@ plot(prevLow, "Previous day low", { color: color.red, style: plot.style_linebr }
 
 ```js
 indicator("Weekly open", { overlay: true });
-const weekOpen = request.security("", "W", () => open, barmerge.gaps_off, barmerge.lookahead_on);
+const weekOpen = request.security("", "W", () => open, { lookahead: barmerge.lookahead_on });
 plot(weekOpen, "Week open", { color: color.purple, style: plot.style_stepline });
 ```
 
+The arguments after the expression are Pine's, by position (`gaps, lookahead, ignore_invalid_symbol`) or by name in an
+object (`{ gaps, lookahead, ignore_invalid_symbol }`); an unknown name throws with the closest names. `currency` and
+`calc_bars_count` are not supported (they throw).
+
 ### Other symbols
 
 ```js