mql4-sma/README.md

# KnitPkg for MetaTrader — SMA Indicator Demo

## Overview

This project, `sma`, serves as a practical demonstration of how to build a custom Simple Moving Average (SMA) indicator in MQL4 using the **KnitPkg for MetaTrader** package manager. It showcases the integration of core KnitPkg libraries, specifically `@douglasrechia/calc` for mathematical operations and `@douglasrechia/bar` for robust bar data access, to create modular and maintainable trading solutions. It is **not** meant to be a production-grade trading system, but rather an **educational example** of how to reuse packages from the community or your own library.

The indicator calculates and displays a Simple Moving Average based on a user-defined period and a specified price type (typically close price). It leverages the `ITimeSeries` interface and the `TimeSeriesArray` class from `@douglasrechia/bar` to provide a standardized, object-oriented approach to feeding price data into the SMA calculation, ensuring data is always presented in a series-ordered fashion (newest element at index 0).

## Features

*   **Simple Moving Average (SMA) Calculation**: Implements the SMA indicator using the `douglasrechia::SMA` function from the `@douglasrechia/calc` package.
*   **Type-Safe Time Series Data Access**: Demonstrates the use of the `ITimeSeries<T>` interface and `TimeSeriesArray<T>` class (from `@douglasrechia/bar`) for flexible and series-ordered access to price data, where `ValueAtShift(0)` always refers to the most recent data point.
*   **KnitPkg Dependency Management**: Illustrates how an MQL4 project can declare and utilize external dependencies managed by the KnitPkg CLI.
*   **Modular and Maintainable Code**: Presents a project structure that promotes code reusability and simplifies maintenance by separating concerns into distinct libraries.
*   **MetaTrader 4 Integration**: A fully functional MQL4 indicator ready to be compiled and used within the MetaTrader 4 terminal.

## Prerequisites

To compile and run this project, you will need:

1.  [**MetaTrader 4**](https://www.mql5.com/) installed.
2.  **KnitPkg CLI**: The KnitPkg package manager for MetaTrader. If you don't have it, you can install it by following the instructions in the [main KnitPkg repository](https://github.com/knitpkg-dev/knitpkg-mt.git).

## Downloading and install `sma` in your MetaTrader

To learn how to structure your own indicator with KnitPkg packages, clone this repository:

```bash
# Change to your MetaTrader 'Indicators' directory.
# How to find it: in the MetaEditor navigator, right‑click the `Indicators` folder and select "Open Folder".
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\D0E8209F77C8CF37AD8BF550E51FF075\MQL4\Indicators"

# Clone the repository
git clone https://forge.mql5.io/DouglasRechia/mql4-sma.git
cd sma

# Install dependencies (downloads @douglasrechia/calc and @douglasrechia/bar automatically)
knitpkg-mt install

# Compile the Indicator
knitpkg-mt compile

# Close MetaTrader and launch it again (needed to refresh navigator Indicators).
# The compiled binary `KnitPkgSMA.ex4` will appear in MetaTrader navigator under the Indicators/sma/bin entry.
# Attach it to a chart to plot the SMA line.
```

Alternatively, execute the `get` command to query the registry for project metadata, enabling the automatic 
download and compilation of the latest stable version.

``` bash
# Change to your MetaTrader Data folder directory. This is step is required only if you have
# more than one MetaTrader instalation.
# How to find it: in the MetaTrader navigator, click on menu File/Open data folder.
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\D0E8209F77C8CF37AD8BF550E51FF075"

kp get mql4 @douglasrechia/sma

# Close MetaTrader and launch it again (needed to refresh navigator Indicators).
# The compiled binary `KnitPkgSMA.ex4` will appear in MetaTrader navigator under the Indicators/sma/bin entry.
# Attach it to a chart to plot the SMA line.
```


## License

This project is released under the **MIT License**. See the `LICENSE` file for the full text.

## Disclaimer

*The author provides this code **as‑is**, for **educational purposes only*.  
No warranty, express or implied, is given. The author assumes **no liability** for any damages, losses, or legal consequences that may arise from using, modifying, or distributing this software. Use it at your own risk.*