talib/README.md

# talib

Go wrapper for selected [TA-Lib](https://ta-lib.org/) functions using [`purego`](https://github.com/ebitengine/purego) to dynamically load the native TA-Lib shared library at runtime.

This project currently exposes a focused subset of TA-Lib functions:

**Cycle Indicators (Hilbert Transform)**
- `HT_DCPERIOD`
- `HT_DCPHASE`
- `HT_PHASOR`
- `HT_SINE`
- `HT_TRENDMODE`

**Math Operators**
- `Add`, `Sub`, `Mult`, `Div`
- `Max`, `MaxIndex`, `Min`, `MinIndex`
- `MinMax`, `MinMaxIndex`
- `Sum`

**Math Transforms**
- Trigonometric: `Cos`, `Sin`, `Tan`, `ACos`, `ASin`, `ATan`
- Hyperbolic: `CosH`, `SinH`, `TanH`
- Exponential/Logarithmic: `Exp`, `Ln`, `Log10`
- Rounding: `Ceil`, `Floor`, `Sqrt`

**Momentum Indicators**
- Directional Movement: `ADX`, `ADXR`, `DX`, `MinusDI`, `MinusDM`, `PlusDI`, `PlusDM`
- Oscillators: `APO`, `Aroon`, `AroonOsc`, `BOP`, `CCI`, `CMO`, `CMOU`, `IMI`, `MFI`, `MOM`, `PPO`, `RSI`, `Trix`, `WillR`, `UltOsc`
- Rate of Change: `ROC`, `ROCP`, `ROCR`, `ROCR100`
- MACD family: `MACD`, `MACDExt`, `MACDFix`
- Stochastic family: `Stoch`, `StochF`, `StochRSI`

**Overlap Studies**
- `AccBands`, `BBands`, `DEMA`, `EMA`, `HT_TRENDLINE`, `KAMA`, `MA`, `MAMA`, `MAVP`, `MidPoint`, `MidPrice`, `SAR`, `SARExt`, `SMA`, `T3`, `TEMA`, `TRIMA`, `WMA`

**Price Transforms**
- `AvgPrice`, `MedPrice`, `TypPrice`, `WCLPrice`

**Statistic Functions**
- `AvgDev`, `Beta`, `Correl`, `LinearReg`, `LinearRegAngle`, `LinearRegIntercept`, `LinearRegSlope`, `StdDev`, `TSF`, `Var`

**Volatility Indicators**
- `ATR`, `NATR`, `TRANGE`

**Volume Indicators**
- `AD`, `ADOsc`, `CMF`, `NVI`, `OBV`, `PVI`, `PVO`

**Pattern Recognition**
- `Cdl2Crows`, `Cdl3BlackCrows`, `Cdl3Inside`, `Cdl3LineStrike`, `Cdl3Outside`, `Cdl3StarsInSouth`, `Cdl3WhiteSoldiers`
- `CdlAbandonedBaby`, `CdlAdvanceBlock`, `CdlBeltHold`, `CdlBreakaway`, `CdlClosingMarubozu`, `CdlConcealBabysWall`, `CdlCounterAttack`
- `CdlDarkCloudCover`, `CdlDoji`, `CdlDojiStar`, `CdlDragonflyDoji`, `CdlEngulfing`, `CdlEveningDojiStar`, `CdlEveningStar`
- `CdlGapSideBySideWhite`, `CdlGravestoneDoji`, `CdlHammer`, `CdlHangingMan`, `CdlHarami`, `CdlHaramiCross`, `CdlHighWave`
- `CdlHikkake`, `CdlHikkakeMod`, `CdlHomingPigeon`, `CdlIdentical3Crows`, `CdlInNeck`, `CdlInvertedHammer`, `CdlKicking`, `CdlKickingByLength`

## Requirements

- Go `1.26`
- A native TA-Lib shared library installed on the host system

This package does **not** bundle TA-Lib itself. You must install the native library separately.

## How library loading works

Call `talib.Load()` once before using any indicator function. After loading, you can call `talib.Version()` to read the native TA-Lib version string. The loader looks for the platform-specific library name:

- macOS: `libta-lib.dylib`
- Linux: `libta-lib.so`
- Windows: `libta-lib.dll`

Lookup order:

1. `$TA_LIB_PATH/<library file>`
2. `./<library file>`
3. `/usr/local/lib/<library file>`
4. `/usr/lib/<library file>`

## Installing TA-Lib

### macOS

If you use Homebrew:

```bash
brew install ta-lib
```

If the library is installed outside the default lookup paths, set:

```bash
export TA_LIB_PATH=/path/to/lib
```

### Linux

Install TA-Lib with your package manager if available, or build it from source and place the shared library in a standard library directory such as `/usr/local/lib`.

### Windows

Install the TA-Lib DLL and make sure `libta-lib.dll` is reachable through `TA_LIB_PATH` or from the current working directory.

## Usage

```go
package main

import (
	"fmt"
	"log"
	"math"

	"beejay.kim/lib/talib"
)

func main() {
	if _, err := talib.Load(); err != nil {
		log.Fatal(err)
	}

	fmt.Println("TA-Lib version:", talib.Version())

	var series []float64
	for i := 0; i < 100; i++ {
        series = append(series, math.Sin(float64(i)/7)*4.5+math.Cos(float64(i)/19)*1.75)
    }

	period := talib.HT_DCPERIOD(series)
	fmt.Println(period)

	sum := talib.Add(series, series)
	fmt.Println(sum)

	rollingMax := talib.Max(series, 14)
	fmt.Println(rollingMax)
}
```

## API notes

- Indicator functions return `nil` when the underlying TA-Lib call fails.
- `Version()` returns the TA-Lib version string exposed by `TA_GetVersionString` (call after `Load()`).
- Native TA-Lib functions are exposed with Go-style exported names such as `Add`, `Div`, `Max`, and `Sum`.
- Functions accepting a moving-average type use the `MAType` constant (`MA_SMA`, `MA_EMA`, `MA_WMA`, `MA_DEMA`, `MA_TEMA`, `MA_TRIMA`, `MA_KAMA`, `MA_MAMA`, `MA_T3`).
- Functions returning multiple outputs (e.g. `Aroon`, `MACD`, `Stoch`) return multiple slices; all are `nil` on failure.
- Pattern-recognition functions (`Cdl*`) return `[]int32` signals; typical values are `-100` (bearish), `0` (no pattern), and `100` (bullish).

## Project status

This is currently a focused wrapper around a limited subset of TA-Lib. Additional indicators can be added by registering more native functions in `Load()` and exposing Go wrappers for them.