주시
1
0
포크
이미 MQLArticles을(를) 포크했습니다
0
원본 프로젝트 nique_372/MQLArticles
MQLArticles/Utils/File/README.md
108 라인
6 KiB
Markdown
Nique_372
2026-10-22 10:28:48 -05:00
[← Utils](../README.md)
# Utils/File
Folder-level file operations. Everything lives in `namespace TSN`.
## Main features
Nique_372
2026-10-22 21:57:02 -05:00
- **Clean a folder**: recursively delete the files of a directory that match the include filter and not the exclude one (`CFolderOpsClean`). A sub-folder whose path matches the include filter is cleaned entirely.
- **Encrypt / decrypt a folder**: every matching file in a directory (recursive), using Fernet (`CFolderOpsEncrypt`).
- **Include / exclude filters**: shared by all of them (`CFolderOpsBase`): set them from a string like `"*.tmp|*.log"`, or load/save them as JSON (`Load`, `Save`).
Nique_372
2026-10-22 10:28:48 -05:00
## Basic usage
### Clean a folder
```mql5
TSN::CFolderOpsClean clean;
Nique_372
2026-10-22 21:57:02 -05:00
clean.SetArrIncluyed("*.tmp|*.log"); // files to delete (patterns, '|' separated)
Nique_372
2026-10-22 10:28:48 -05:00
clean.CleanFolder("MQLArticles\\Temp\\", FILE_COMMON); // directory (with trailing \), common flag
```
### Encrypt and decrypt
```mql5
uchar key[CRYPTOBYLEO_FERNET_KEYBYTES];
// ... fill the key ...
TSN::CFernet fernet;
fernet.Key(key);
TSN::CFolderOpsEncrypt folder_ops;
folder_ops.Fernet(&fernet);
Nique_372
2026-10-22 21:57:02 -05:00
// encrypt: (dir, common flag, delete original, extension of the encrypted file)
folder_ops.SetArrIncluyed("*.txt|*.csv");
folder_ops.SetInitialPass(CRYPTOBYLEO_FERNET_UTCTIME); // timestamp stored in every token
folder_ops.EncryptFolder<TSN::CURandomPRNG<Xoshiro256>>("MQLArticles\\Data\\", true, true, ".enc");
Nique_372
2026-10-22 10:28:48 -05:00
// decrypt: (dir, common flag, delete encrypted file, ttl, extension of the decrypted file)
Nique_372
2026-10-22 21:57:02 -05:00
folder_ops.SetArrIncluyed("*.txt.enc|*.csv.enc");
folder_ops.SetInitialPass(CRYPTOBYLEO_FERNET_UTCTIME); // "now" for the ttl check
Nique_372
2026-10-22 10:28:48 -05:00
folder_ops.DecryptFolder("MQLArticles\\Data\\", true, true, INT_MAX, "-");
```
Nique_372
2026-10-22 21:57:02 -05:00
`SetInitialPass(now)` stores `now` in the object: it is the timestamp written into the tokens when encrypting and the current time used for the TTL check when decrypting. `ttl` is in seconds (`INT_MAX` disables the check). Both operations use the [Fernet](https://forge.mql5.io/nique_372/CryptoByLeo/src/branch/main/Src/Fernet) rules for `ext_encrypt` / `ext_decrypt`, see its README.
> **Warning: `delete_prev_file = true` with an empty extension deletes the result.** Fernet saves the output first and then deletes the source, so if both have the same name (`ext_encrypt` / `ext_decrypt` empty, or `ext_decrypt` without `.` and `-`) the freshly written file is deleted. Use a non-empty extension, or `delete_prev_file = false`.
Nique_372
2026-10-22 10:28:48 -05:00
> `CFernet` and the PRNG come from external TSN libraries (not part of Utils). Full runnable scripts in [`FolderOps/Test/`](./FolderOps/Test).
Nique_372
2026-10-22 21:57:02 -05:00
## How filtering works
For every entry found while walking the tree:
- **Files**: if the file matches the **exclude** filter it is skipped. Otherwise it is processed only if it matches the **include** filter.
- **Folders**: if a folder matches the include filter, *everything* under it is processed, ignoring both filters, until the walk leaves that folder. Otherwise the walk just descends into it.
- **Empty include filter = nothing is processed.** There is no "match all" default; add a pattern that matches everything.
All three operations (`CleanFolder`, `EncryptFolder`, `DecryptFolder`) behave the same way.
### Filter patterns
Multiple patterns are separated by `|` (or any separator you pass to `SetArrIncluyed` / `SetArrExcluyed`).
Pattern syntax is **custom**, not standard glob. See the
[StrMatch module](https://forge.mql5.io/nique_372/TSNStd/src/branch/main/Src/StrMatch)
for the supported patterns.
What is matched against the patterns:
- The **full path relative to the root** (`MQL5\Files` or `Common\Files`), not just the file name. Use `\` as separator.
- Folder paths end with `\`.
## Paths and flags
- `init_dir` is relative to `MQL5\Files` (or `Common\Files` with the common flag) and **must end with `\`**.
- `CleanFolder` takes the flag as an `int` (`FILE_COMMON` or `0`), `EncryptFolder` / `DecryptFolder` and `Load` take a `bool`, and `Save` takes extra `int` file flags.
## Config files (JSON)
`Save` / `Load` use two arrays, `incluyed` and `excluyed`:
```json
{ "incluyed": ["..."], "excluyed": ["..."] }
```
A missing field is treated as an empty list (a warning is recorded). Remember that an empty include list means nothing is processed.
## Error handling
- A failure on one file **never aborts** the run; the remaining files are still processed.
- Problems are recorded as warnings by all three classes. They are reset by `SetInitialPass()` and `Load()`.
- A warning only stores its **kind**, not the file that caused it. At most 16 are kept per run (`FILEFOLDEROPS_MAX_WARNS`); the following ones are dropped silently. Define `MQLARTICLES_FOLDEROPS_ENABLE_LOGS` to see each failure.
- An empty or missing folder is `FILE_FOLDEROPS_WARN_NOT_FILE_FOLDER`, which is normal, not a failure.
### Reading the results
```mql5
folder_ops.SetInitialPass(CRYPTOBYLEO_FERNET_UTCTIME); // CFolderOpsClean::SetInitialPass() takes no argument
folder_ops.DecryptFolder("MQLArticles\\Data\\", true, true, INT_MAX, "-");
for(int i = 0; i < folder_ops.TotalWarns(); i++)
Print(EnumToString(folder_ops.Warn(i)));
```
| Method | Returns |
|---|---|
| `TotalWarns()` | number of warnings recorded in the current run |
| `Warn(i)` | the `i`-th warning (`ENUM_FILE_FOLDEROPS_WARN`) |
| `LastErr()` | last hard error (`ENUM_FILE_FOLDEOPS_ERR`), set by `Load` / `Save` |
## Notes and preconditions
- Call `SetInitialPass()` before each top-level operation to reset internal state. For `CFolderOpsEncrypt` it takes the `now` described above and it is **required**: without it `now` is `0`, so tokens get timestamp `0` and the TTL check never rejects anything.
- `Fernet(...)` must be set before `EncryptFolder` / `DecryptFolder`. A `NULL` encryptor is a precondition violation (a critical runtime error in MQL5).
- When encrypting with `delete_prev_file = false` and an extension set, the output is written in the same folder being walked. Make sure the include filter does not match the encrypted extension, or already-encrypted files may be processed again.
- The operations are **not transactional**: if the run is interrupted or some files fail, the folder is left partially processed.