124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# Package bar
|
|
|
|
**Simple, fast and reliable bar access with time series and new bar detection**
|
|
*MIT License*
|
|
|
|
---
|
|
|
|
## What is this?
|
|
|
|
`bar` is a **demonstration helper package** that showcases how to build a KnitPkg package.
|
|
|
|
It provides:
|
|
|
|
- `IBar` interface and implementations for bar data access
|
|
- `ITimeSeries<T>` interface for type-safe series access
|
|
- `BarWatcher` for new bar detection
|
|
|
|
This 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.
|
|
|
|
## Prerequisites
|
|
|
|
To use 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).
|
|
3. **KnitPkg homepage**: See [https://knitpkg.dev](https://knitpkg.dev) for an overview and [https://docs.knitpkg.dev](https://docs.knitpkg.dev) for documentation.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Package type** (`type: package`) — header-only library consumable by other KnitPkg projects
|
|
- **MQL4 target** — designed for MetaTrader 4
|
|
- **Compile support** — `kp compile` compiles the unit test script(s)
|
|
- **Bar access abstractions** — read bar data through a clean interface (`IBar`)
|
|
- **Typed time series** — `ITimeSeries<T>` for safer access patterns
|
|
- **New bar detection** — `BarWatcher` to detect new bars reliably
|
|
|
|
---
|
|
|
|
## Installing as a dependency (recommended)
|
|
|
|
To add `bar` to your KnitPkg project:
|
|
|
|
```bash
|
|
kp add @douglasrechia/bar
|
|
```
|
|
|
|
---
|
|
|
|
## Basic usage (example)
|
|
|
|
In the case your MQL4 project uses `include_mode: include`, include headers from the KnitPkg include directory:
|
|
|
|
```mql4
|
|
#include "../knitpkg/include/douglasrechia/bar/<Header>.mqh"
|
|
```
|
|
|
|
> Note: The exact header names and function signatures depend on the package headers. Use MetaEditor IntelliSense to browse the available APIs.
|
|
|
|
---
|
|
|
|
## Exploring the project locally (optional)
|
|
|
|
If you want to explore how a KnitPkg package is structured, clone the repository and run the standard workflow.
|
|
|
|
### 1) Clone into MetaTrader `Scripts` folder (example)
|
|
|
|
```bash
|
|
# Go to your MetaTrader 'Scripts' directory.
|
|
# Tip: in MetaEditor, right-click the `Scripts` folder and choose "Open Folder".
|
|
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>\MQL4\Scripts"
|
|
|
|
git clone https://forge.mql5.io/DouglasRechia/mql4-bar.git
|
|
cd bar
|
|
```
|
|
|
|
### 2) Compile
|
|
|
|
```bash
|
|
kp compile
|
|
```
|
|
|
|
---
|
|
|
|
## Running unit tests
|
|
|
|
Unit tests are implemented as a MetaTrader **Script**.
|
|
|
|
1. Compile the project.
|
|
2. Restart MetaTrader (so the Navigator refreshes).
|
|
3. Run the generated unit test script from the Navigator on any chart.
|
|
4. Check results in the MetaTrader console (Experts/Scripts tab, depending on your setup).
|
|
|
|
The compiled binary is placed under the project `bin/` directory (and appears in the Navigator under the corresponding compiled location after refresh).
|
|
|
|
---
|
|
|
|
## One-command download/build via the registry (optional)
|
|
|
|
You can also use `kp get` to query the registry for metadata and automatically download/build the latest stable version.
|
|
|
|
Example (run from your MetaTrader *Data Folder* root):
|
|
|
|
```bash
|
|
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"
|
|
|
|
kp get mql5 @douglasrechia/bar
|
|
```
|
|
|
|
Restart MetaTrader afterward to refresh the Navigator, then run the unit test script as described above.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This project is released under the **MIT License**. See `LICENSE` for details.
|
|
|
|
---
|
|
|
|
## Disclaimer
|
|
|
|
This code is provided **as-is**, for **educational purposes only**.
|
|
No warranty (express or implied) is provided. Use at your own risk.
|