[← Utils](../README.md) # Utils/File Folder-level file operations. Everything lives in `namespace TSN`. ## Main features - **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`). ## Basic usage ### Clean a folder ```mql5 TSN::CFolderOpsClean clean; clean.SetArrIncluyed("*.tmp|*.log"); // files to delete (patterns, '|' separated) 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); // 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>("MQLArticles\\Data\\", true, true, ".enc"); // decrypt: (dir, common flag, delete encrypted file, ttl, extension of the decrypted file) folder_ops.SetArrIncluyed("*.txt.enc|*.csv.enc"); folder_ops.SetInitialPass(CRYPTOBYLEO_FERNET_UTCTIME); // "now" for the ttl check folder_ops.DecryptFolder("MQLArticles\\Data\\", true, true, INT_MAX, "-"); ``` `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`. > `CFernet` and the PRNG come from external TSN libraries (not part of Utils). Full runnable scripts in [`FolderOps/Test/`](./FolderOps/Test). ## 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.