From 47997f15394e42c83b54e3804b64a59cb5c85748 Mon Sep 17 00:00:00 2001 From: Ashkenov Timur Date: Sat, 10 Oct 2026 12:07:24 +0300 Subject: [PATCH] [OMEGA-493] Docs: Document delete-file I/O skill --- docs/reference-skills-io.md | 49 ++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/reference-skills-io.md b/docs/reference-skills-io.md index 8c3e71798..dace4a06a 100644 --- a/docs/reference-skills-io.md +++ b/docs/reference-skills-io.md @@ -1,6 +1,6 @@ # Reference — I/O Skills -Defined in `src/skills.metta`; the `shell` primitive is backed by `src/skills.pl`, the write skills by `src/fileio.py`. +Defined in `src/skills.metta`; the `shell` primitive is backed by `src/skills.pl`, the write and delete skills by `src/fileio.py`. --- @@ -152,6 +152,53 @@ read back from disk — or `APPEND-FAILED file=: ` (e.g. when the f --- +## `delete-file` + +### Signature +```metta +(delete-file "path") +``` + +### Purpose +Delete a file and check afterward whether the path still exists. Implemented by +`fileio.delete_file` in `src/fileio.py`. + +### Parameters +- `path` — absolute or relative filesystem path to delete. Relative paths are resolved against the Omega process's current working directory. + +### Returns +`DELETE-VERIFIED file=` after removal if the existence check reports that +the path is absent, or `DELETE-FAILED file=: ` on failure. +The returned path matches the input as given. + +Failure reasons include: + +- `file does not exist` — the path does not exist, including as a symbolic link. +- `path is a directory` — the path is a directory or a symbolic link to a directory. +- The exception message from the removal operation, such as a permission error. +- `file still exists after removal` — the post-removal check finds the path still present, for example if another process recreated it. + +### Examples +```metta +(write-file "/tmp/delete-file-example.txt" "temporary contents") +(delete-file "/tmp/delete-file-example.txt") +``` + +After a successful write and deletion, the deletion result is: +```text +DELETE-VERIFIED file=/tmp/delete-file-example.txt +``` + +### Notes / Limits +- Deletes immediately without confirmation or moving the file to a trash folder. There is no built-in undo. +- Does not delete directories or recursively remove their contents. +- Removes symbolic links to files and dangling symbolic links themselves, leaving their targets untouched. Symbolic links to directories are rejected. +- Deleting an already missing path returns `DELETE-FAILED`, not a success result. +- Use `get-io-policy` before deleting when the path is not known to be allowed; the target must be covered by a `read_write` path. Filesystem permissions and active security restrictions still apply. +- Relay the returned verification result; do not claim success without `DELETE-VERIFIED`. Verification is a point-in-time check using `os.path.exists`, which follows symbolic links and does not detect dangling links recreated at the path. + +--- + ## `get-io-policy` ### Signature