calc/README.md

# Package calc

**Common indicators built on @douglasrechia/bar**  
*MIT License*  

---

## What is this?

Package `calc` is a **demonstration project** that showcases how to build a KnitPkg package that depends on another KnitPkg package.  
It provides a small, self‑contained library that implements common technical analysis functions (SMA, ATR, etc.) on top of the 
`IBar` and `ITimeSeries` interfaces from `@douglasrechia/bar`.  The project is intended **only as an educational example** of how to 
structure, package and compile MQL5 code with KnitPkg – it is **not** meant to be a production‑grade library for large‑scale use.

## Features

- **Package type** (`type: package`) – header‑only library that can be consumed by other KnitPkg projects.  
- **Transitive dependencies** – automatically resolves and includes `@douglasrechia/bar` when imported.  
- **mql5 target** – works with MetaTrader 5.  
- **Compile support** – `kp compile` compiles the test suite.  

## Adding `calc` as a dependency in your project

To incorporate the latest stable release of `calc` into your KnitPkg project, use the `add` command to include it as a dependency in your `knitpkg.yaml` file:

```bash
kp add @douglasrechia/calc
```

Note that the caret (^) prefixing the version number in the `knitpkg.yaml` manifest indicates that your project will receive minor and patch updates for `calc` during installation commands.

After adding the dependency, execute `kp install` to download `calc` and its required dependency `@douglasrechia/bar`. For reproducible builds, you may opt to use `kp install --locked` to adhere to the locked version. Refer to the KnitPkg documentation for additional information.


## Downloading `calc` and running unit tests (optional)

If you're interested in exploring how a KnitPkg package with dependencies is structured, do the following:

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

# Clone the repository
git clone https://forge.mql5.io/DouglasRechia/calc.git

cd calc

# Install dependencies (downloads @douglasrechia/bar into .knitpkg/cache/).
# This step is optional; autocomplete will do it for you automatically.
kp install

# Generate autocomplete (resolves dependencies of the test script and enables MetaEditor IntelliSense)
kp autocomplete

# Compile the test script
kp compile

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The compiled binary `UnitTests.ex5` will appear in MetaTrader navigator under the Scripts/calc/bin entry.
# Double‑click it to run the tests. See test results in the 'Scripts' tab.
```

Alternatively, execute the `get` command to query the registry for package 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 mql5 @douglasrechia/calc

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The compiled binary `UnitTests.ex5` will appear in MetaTrader navigator under the Scripts/calc/bin entry.
# Double‑click it to run the tests. See test results in the 'Scripts' tab.
```

## 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.*