@simahfud/pine-to-kline 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# 🌲 pine-to-kline
+
+An independent interpreter that compiles Pine Script (v5/v6) into indicators compatible with the [KlineChart](https://klinecharts.com/) charting library.
+
+Designed as a plugin for `@simahfud/klinecharts-pro`.
+
+## Features
+- **Clean-room implementation**: Converts Pine Script directly to KlineChart's `IndicatorTemplate` format
+- **Series Emulation**: Bar-by-bar evaluation to support `close[1]` historical access syntax
+- **Pine Functions**: Includes most-used `ta.*`, `math.*`, and `color.*` built-ins
+- **Inputs & Styling**: Maps `input.int()`, `plot()`, and `hline()` to KlineChart parameters and figures
+- **Zero Dependencies**: Independent pure-TS library
+
+## Installation
+
+```bash
+npm install pine-to-kline
+```
+
+*(Note: Requires `klinecharts >= 9.0.0` as a peer dependency)*
+
+## Basic Usage
+
+```ts
+import { PineInterpreter } from 'pine-to-kline'
+
+const pine = new PineInterpreter()
+
+// Compile Pine Script
+const result = pine.compile(`
+  //@version=5
+  indicator("My SMA", overlay=true)
+  length = input.int(14, "Length")
+  plot(ta.sma(close, length), "SMA", color=color.blue)
+`)
+
+if (result.success) {
+  // result.indicatorConfig is a valid KlineChart IndicatorTemplate
+  klineChart.addIndicator(result.indicatorConfig, true)
+}
+```
+
+## Plugin Integration with KlineChart Pro
+
+The library includes a dedicated plugin wrapper for `@simahfud/klinecharts-pro`.
+
+```ts
+import { createPinePlugin } from 'pine-to-kline/plugin'
+
+// Initialize the plugin
+const pineAPI = createPinePlugin()
+
+// 1. Compile and register the indicator
+const indicatorName = pineAPI.run(`
+  //@version=5
+  indicator("RSI", overlay=false)
+  length = input.int(14, "Length")
+  plot(ta.rsi(close, length), "RSI", color=color.purple)
+  hline(70, "OB", color=color.red)
+  hline(30, "OS", color=color.green)
+`)
+
+// 2. Add the registered indicator to your chart pane
+klineChart.createIndicator(indicatorName, true, { id: 'pane_1' })
+```
+
+## Supported Pine Features (Phase 1)
+
+### Built-in TA (`ta.*`)
+- **Moving Averages**: `sma`, `ema`, `rma`, `wma`, `hma`, `vwma`, `swma`, `dema`, `tema`
+- **Momentum**: `rsi`, `macd`, `stoch`, `cci`, `mom`, `roc`
+- **Volatility**: `atr`, `bb` (Bollinger Bands), `kc` (Keltner Channels), `donchian`, `tr`
+- **Crossover**: `crossover`, `crossunder`, `cross`, `change`, `rising`, `falling`
+- **Utility**: `highest`, `lowest`, `highestbars`, `lowestbars`, `barssince`, `valuewhen`, `pivothigh`, `pivotlow`, `cum`, `stdev`, `percentrank`
+
+### Math (`math.*`)
+- `abs`, `ceil`, `floor`, `round`, `log`, `log10`, `pow`, `sqrt`, `exp`, `max`, `min`, `sign`, `avg`, `sum`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `random`, `todegrees`, `toradians`
+
+### Colors (`color.*`)
+- All standard color constants (e.g. `color.red`, `color.blue`)
+- Functions: `color.new()`, `color.rgb()`, `color.from_gradient()`
+
+### Inputs
+- `input()`, `input.int()`, `input.float()`, `input.bool()`, `input.string()`, `input.color()`, `input.source()`
+
+## Architecture
+
+The interpreter pipeline works in 4 phases:
+1. **Lexer**: Tokenizes the source code, handling Pine's indentation blocks.
+2. **Parser**: A recursive-descent parser that builds an Abstract Syntax Tree (AST).
+3. **Runtime Engine**: Evaluates the AST using a `SeriesEmulator` to provide `var` persistence and `[]` lookbacks.
+4. **Adapter**: Transpiles the runtime's Intermediate Representation (IR) into a KlineChart `IndicatorTemplate`.
+
+## License
+Apache-2.0