mql4-bar/README.md

# Package bar

**Simple, fast and reliable bar access with time series and new bar detection**  
*MIT License*  

---

## What is this?

`bar` is a **demonstration project** that showcases how to use **KnitPkg for MetaTrader** to manage MQL4 packages. It provides a small, self‑contained package that provides interfaces such as `IBar` and `ITimeSeries` along with actual implementations to provide access to broker data, together with a tiny test suite. 

The project is intended **only as an educational example** of how to structure, package and compile MQL4 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.  
- **mql4 target** – works with MetaTrader 4.  
- **Compile support** – `kp compile` compiles the test suite.  

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

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

```bash
kp add @douglasrechia/bar
```

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

After adding the dependency, execute `kp install` to download `bar` for prompt use. 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 `bar` and running Unit tests (optional)

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

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

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

cd bar

# Compile the test script
kp compile

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The Unit tests compiled binaries will appear in MetaTrader navigator under the Scripts/bar/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 mql4 @douglasrechia/bar

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The Unit tests compiled binaries will appear in MetaTrader navigator under the Scripts/bar/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.*