SimPHash/README.md

<p align="center">
  <img src="https://img.shields.io/badge/Language-MQL5%20%7C%20YAML-1B6CA8?style=flat-square"/>
  <img src="https://img.shields.io/badge/Platform-MetaTrader%205-0D1B2A?style=flat-square"/>
  <img src="https://img.shields.io/badge/Author-nique__372-C9D6DF?style=flat-square&logoColor=white"/>
  <img src="https://img.shields.io/badge/MQL5.com-nique__372-1B6CA8?style=flat-square"/>
    <a href="./LICENSE">
  <img src="https://img.shields.io/badge/License-Nique%26Leo%20NL--NC-yellow.svg"/>
</a>
</p>

<p align="center">
Simple perfect hash generator, driven by a YAML config file.<br/> Runs as an EA: reads your key/value map from 
YAML, builds a perfect hash with <a href="https://forge.mql5.io/nique_372/PerfectHashByLeo">PerfectHashByLeo</a>, 
and emits a ready-to-include <code>.mqh</code> with the tables and lookup function already written.
</p>

<p align="center">
<i>A perfect hash function maps a fixed, known set of keys to distinct slots with no collisions 
so lookups are just a couple of arithmetic ops and an array index, no chaining or probing needed.
SimPHash builds that table for you at design time from a YAML key list.</i>
</p>

---

## Main Features

- **YAML-driven, no code required**: you don't write the perfect hash tables by hand you list your keys (and optionally values) in a YAML file, run the EA once, and it generates the `.mqh` for you.
- **Two swappable hash stages**, matching how [PerfectHashByLeo](https://forge.mql5.io/nique_372/PerfectHashByLeo) works internally: a bucket hash (FNV-1a 64 or xxHash64) followed by a final displacement hash (MurMur-style, SplitMix64, fmix64 or Fibonacci hashing).
- **Two output modes**: either a table of **final values** (the generated function returns your mapped value directly) or a table of **indices** (the function returns a position into your own array useful when the value is too complex to inline).
- **Optional binary export**: alongside the `.mqh`, you can dump the seeds/hashes/values/meta as raw `.bin` files (useful if you want to load the table at runtime instead of compiling it in).
- **Generates a complete, working lookup function** both a `string`-keyed overload and a pre-hashed `ulong`-keyed overload, so callers who already computed the hash elsewhere can skip re-hashing.

Every parameter accepted by the YAML config is documented, with a ready-to-copy template, in **[Src/Template/README.md](./Src/Template/README.md)**.

---

## Usage: the process

**1. Write your YAML config** list your keys, pick your hash stages, point `file_name_out` at the `.mqh` you want generated. Full parameter reference: [Src/Template/README.md](./Src/Template/README.md).

<p align="center"><img src="./Market/simphahs1.png" width="640" alt="Editing config.yaml"/></p>

**2. Run `SimpHash.mq5`** pointing `InpYamlFileName` at that config. It generates the `.mqh` with the seed/hash/value tables plus a ready `HashCustom(const string& key)` / `HashCustom(const ulong key_hash)` function:

<p align="center">
  <img src="./Market/simphash4.png" width="400" alt="Generated .mqh tables"/>
  <img src="./Market/simphash5.png" width="400" alt="Generated .mqh lookup function"/>
</p>

**3. Include the generated file** in your own project and call the generated function:

<p align="center"><img src="./Market/simphash2.png" width="640" alt="Using the generated function"/></p>

**4. Done** valid keys resolve to their value, unknown keys return `invalid_value`:

<p align="center"><img src="./Market/simphash3.png" width="640" alt="Output in the MT5 log"/></p>

---

## Repository Structure

```
SimPHash/
├── SimpHash.mq5          # Main EA reads the YAML config and generates the .mqh
├── dependencies.json     # tsndep manifest (private repos required to compile)
├── Src/
│   ├── PerfectHash.mqh   # Core generator logic
│   ├── Def.mqh
│   ├── Hash/             # Hash strategies (bucket hash + final displacement hash)
│   ├── EnumReg/          # YAML enum registry
│   ├── Template/         # config.yaml template + full parameter reference (README.md)
│   └── Test/             # Sample config.yaml, generated Out.mqh and Test.mq5
└── Market/               # Screenshots used in this README and MQL5 Market version (free DLL)
```

---

## Installation

MetaTrader 5 build `5430` or later is required either way. Pick the path that matches what you want to do:

### For developers

Check [dependencies.json](./dependencies.json), and:

- **Install them with `tsndep`** (available on [PyPI](https://pypi.org/project/tsndep)) from your `Shared Projects` folder it reads [dependencies.json](./dependencies.json) and downloads everything declared there:

   ```bash
   cd "C:\Users\YOUR_USER\AppData\Roaming\MetaQuotes\Terminal\YOUR_ID\MQL5\Shared Projects"
   tsndep install "https://forge.mql5.io/nique_372/SimPHash.git"
   ```

### For users

You don't need the source or its private dependencies to use SimPHash pick one of these two options:

**Option A Manual (from the repo's releases)**

1. Download the latest compiled EA from [Releases](https://forge.mql5.io/nique_372/SimPHash/releases) and move it into your terminal's `MQL5/Experts` folder.
2. Clone the [`TsnTables`](https://forge.mql5.io/nique_372/TsnTables.git) repository into your `Include` folder the generated `.mqh` includes it (e.g. `#include <TSN/Tables/AllHashes.mqh>`) to resolve the shared hash tables. See the [MqlIncludes convention](https://forge.mql5.io/nique_372/TSNReposIndex/src/branch/main/Conventions/MqlIncludes.md) for how these proxy includes work.

**Option B MQL5 Market (recommended, no manual steps)**

1. Get **SimPHash** from the [MQL5 Market](https://www.mql5.com/en/market/product/194416) it installs directly into your terminal, no moving files around.
2. Clone the [`TsnTables`](https://forge.mql5.io/nique_372/TsnTables.git) repository into your `Include` folder, same as in Option A.

> The Market build does not support the DLL-enabled code path it ships DLL-free.

Either way, once the EA is in place and `TsnTables` is available, jump to [Usage: the process](#usage-the-process) above.

---

## License

**[Read Full License](./LICENSE)**

By downloading, cloning, forking, or otherwise using this repository, you accept the license terms.

---

## Contact

- **Platform:** [MQL5 Community](https://www.mql5.com/es/users/nique_372)
- **Profile:** https://www.mql5.com/es/users/nique_372
- **Articles:** https://www.mql5.com/es/users/nique_372/publications