SimPHash/Src/Template/README.md

# SimPHash — Config Reference

This document describes every parameter accepted by the YAML config consumed by SimPHash.
For the general overview, install steps and end-to-end usage flow, see the [main README](../../README.md).

`config.yaml` in this same folder is a fully commented, ready-to-copy template — start from it.

---

## Parameters

| Parameter | Description |
|---|---|
| `max_attepms` | Maximum displacement attempts (seed values `0, 1, 2, ...`) tried per bucket before giving up. |
| `namespace` | Namespace the generated tables/function are wrapped in (leave empty/`null` to skip). |
| `file_name_out` | Path of the `.mqh` file to generate. |
| `table_prefix` | Prefix used for all generated table names (`<prefix>_seeds`, `<prefix>_hashes`, `<prefix>_values`/`<prefix>_tindex`). |
| `copyright` | Text written into the generated file's `#property copyright`. |
| `link` | Text written into the generated file's `#property link`. |
| `func_name` | Name of the generated lookup function. |
| `def_name_table_size` | Name of the `#define` for the final table size. |
| `def_bucket_size_name` | Name of the `#define` for the bucket count. |
| `invalid_value` | Value returned by the generated function when a key isn't found (also used to fill unused slots). |
| `comment_funct` | If `true`, the generated function body is wrapped in `/* */` (useful when you only want the tables and will write the function yourself). |
| `guard_name` | Optional `#ifndef`/`#define` include guard name for the generated file. |
| `bin` | Optional object with `seeds`, `values`, `hash` and `meta` file paths — if present, the raw tables are also written as binary files. |
| `hash.type` | Bucket hash algorithm: `TSN_PHASH_TYPE_FNV1A_64` or `TSN_PHASH_TYPE_XXHASH_64`. |
| `hash.config.basis` / `hash.config.prime` | FNV-1a offset basis / prime (use `def` for the standard FNV-1a-64 constants). |
| `hash.config.seed` | xxHash64 seed (only used when `hash.type` is `TSN_PHASH_TYPE_XXHASH_64`). |
| `final_hash` | Final displacement hash: `HASH_UL1_MUR_MUR`, `HASH_UL1_SPLITMIX`, `HASH_UL1_FMIX` or `HASH_UL1_FIBBO`. |
| `perfect_hash.elements_por_bucket` | Target average number of keys per bucket (lower = more buckets, generally faster to find a working seed). |
| `perfect_hash.load_factor` | Final table load factor (keys / final table size) — lower leaves more free slots, easing displacement at the cost of memory. |
| `map_use_value` | `true` = generate a values table (function returns the value directly); `false` = generate an indices table (function returns a position for you to index your own array with). |
| `map` | The key set itself: a YAML object (`KEY: value`) when `map_use_value: true`, or an array of keys otherwise. |

### Files 
In any parameter that mentions a path or route to a file, keep in mind that if you are using the market version, you must specify the relative path 
(if common_flag=true then relative to the Common\ folder, otherwise to the Files\ folder of your terminal), otherwise the full path C:\

### The two hash stages

SimPHash mirrors how [PerfectHashByLeo](https://forge.mql5.io/nique_372/PerfectHashByLeo) works internally — a bucket hash followed by a final displacement hash:

- **Bucket hash (`hash.type`)** — converts each string key into a `ulong` before bucketing.
  - `TSN_PHASH_TYPE_FNV1A_64`: FNV-1a 64-bit, with configurable `basis`/`prime`.
  - `TSN_PHASH_TYPE_XXHASH_64`: xxHash64, with a configurable `seed`.
- **Final hash (`final_hash`)** — the per-bucket displacement hash, applied to the already-bucketed `ulong` key plus a seed.
  - `HASH_UL1_MUR_MUR`: MurMur-style finalizer.
  - `HASH_UL1_SPLITMIX`: SplitMix64.
  - `HASH_UL1_FMIX`: MurmurHash3 fmix64 finalizer.
  - `HASH_UL1_FIBBO`:  Fibonacci hashing.

### Output modes

- `map_use_value: true` -> a **values table**: the generated function returns your mapped value directly.
- `map_use_value: false` -> an **indices table**: the function returns a position into your own array — useful when the value is too complex to inline (structs, objects, etc.).

Either mode can additionally be exported as raw `.bin` files via the `bin` block, if you'd rather load the table at runtime than compile it in.

---

## Editing by hand? Use the JSON Schema

[`Schema.json`](./Schema.json) in this same folder describes the exact shape above every field, its type, and which values are valid 
so if you're editing `config.yaml` directly in an editor instead of copying an existing one, you get autocomplete and inline validation instead of guessing.

Most editors pick it up with a single line at the top of your YAML file:

```yaml
# yaml-language-server: $schema=./Schema.json
```

(VS Code with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) reads this comment automatically; 
adjust the relative path if your `config.yaml` lives elsewhere.)