Sections marked **(conditional)** are only included when they apply to the repo (e.g. no `Documentation` section if there's no wiki, no `License Warning` if the repo is fully public).
---
## 1. Badges Banner
Centered, top of the file. Language, platform, author, and profile link at minimum. Use `shields.io` flat-square badges.
If the repo has a defined license tag ([NL-NC], [NL-ND], [FPU], [ARR]...), the corresponding badge from [Badges/BADGES.md](../Badges/BADGES.md) can be added here too.
---
## 2. Description / Overview
One short paragraph, centered, directly under the badges. States **what** the repo does and **how** (architecture/approach in one line), not a marketing pitch.
```html
<palign="center">
A high-performance, memory-free JSON parser for MQL5, based on a flat tape architecture.<br/> Single-pass iterative state machine, no recursion, no dynamic memory fragmentation.
</p>
```
---
## 3. Main Features
`## Main Features` heading, bullet list, each feature bolded and explained in one line. This is the only section that is **always required in full**, since it's the core of the README.
```markdown
## Main Features
- **Tape-based zero-alloc model**: the entire JSON is parsed into a single contiguous `long[]` array
- **Single flat loop**: one `switch` over a token enum, strictly O(n)
- **Handle-based navigation**: `CJsonNode` is a lightweight struct, copying is free
```
### Sub-sections (add as needed, always with code)
- **Usage examples** (mandatory): one `###` sub-section per relevant use case, each with a working MQL5/SQL snippet. Never describe usage only in prose.
- **Benchmarks** (conditional): if performance is a selling point, include a results table (parser/lib, language, time), plus a `## Machine` section describing the test rig, and a `## Performance notes` section if runtimes differ (MQL5 build, Python/C++ versions).
- **Article references** (conditional): if the repo is tied to a published MQL5 article, link it here.
---
## 4. Repository Structure
Tree view of the top-level layout, each entry with a short inline comment. Follows [MqlFiles.md](MqlFiles.md) conventions for folder names.
2026-08-01 17:43:44 -05:00
> Personally, I don't recommend being exact with this, meaning listing every single file, but only folders. If you want to add or delete a file later, you're constantly correcting the readme or inflating the number of commits... so my recommendation is to only list folders.
Only if the repo requires a purchase, unlock, or explicit request for access ([NL-ND-P], paid, or unlockable per [TSNReposIndex/README.md](../README.md) legend). State clearly what's required before the code is usable, and link to the product/unlock page.
```markdown
## ⚠️ License Notice
This repository requires a valid unlock/purchase of **FastNL** to compile. See [MQL5 Market](https://www.mql5.com/es/users/nique_372/seller) for details.
```
Skip this section entirely for `🌐 Public` repos.
---
## 6. Requirements
Points to `dependencies.json` as the source of truth, plus any non-dependency requirement (MT5 build, WebRequest whitelist, external service).
```markdown
## Requirements
See [dependencies.json](./dependencies.json) for the full list.
- MetaTrader 5, build 5430+
- WebRequest access enabled for `https://models.dev`
```
---
## 7. Installation
Always via `tsndep`, pointing at the repo's own `.git` URL.
```markdown
## Installation
\`\`\`bash
cd "C:\Users\YOUR_USER\AppData\Roaming\MetaQuotes\Terminal\YOUR_ID\MQL5\Shared Projects"
Requires the \`tsndep\` package, available on [PyPI](https://pypi.org/project/tsndep). It automatically downloads and installs all declared dependencies.
```
---
## 8. Quick Start
Numbered steps (bold step titles), minimal working path from include to first result. 2-4 steps is the target; if it needs more, it probably belongs in `Documentation` instead.
```markdown
## Quick Start
**1. Include the library:**
\`\`\`mql5
#include "..\\RepoName\\Src\\Main.mqh"
\`\`\`
**2. Use it:**
\`\`\`mql5
TSN::CMyClass obj;
obj.Init();
\`\`\`
```
---
## 9. License
Always the same two lines, linking the repo's own `LICENSE` file — never re-explain the license terms inline.
```markdown
## License
**[Read Full License](./LICENSE)**
By downloading or using this repository, you accept the license terms.
```
---
## 10. Documentation (conditional)
Only a link out (wiki, docs site, article series) — never duplicate the wiki content into the README.
```markdown
## Documentation
Full API reference: [Wiki](https://forge.mql5.io/nique_372/RepoName/wiki)
```
Skip if there's no wiki/external doc; in that case the README + inline code comments are the documentation (see [MQL5.md § Comments and Documentation](MQL5.md#comments-and-documentation)).
If it is a trading app/bot utility that may involve risk, place the warning text here (for example, that it is not responsible for financial losses, or disclaimers that it is a bot and not investment advice, that trading is risky, etc., everything you consider necessary).
```markdown
<!-- TSNDep Example -->
## Disclaimer
- TSNDep is a dependency management tool, not trading software
- Always test in development before production deployment
- Ensure you have permissions for all repositories
- Git operations may have security implications. review URLs carefully
- The authors assume no liability for system failures or data loss
