From 2a817c96a4435e2e6542e354835b54780b27de1c Mon Sep 17 00:00:00 2001
From: Paul Koe <hackbaellchen21@gmx.de>
Date: Thu, 1 Feb 2024 11:44:33 +0000
Subject: [PATCH] Add rmdir rule

---
 CHANGELOG.md                                  |  5 +++
 .../islandoftex/arara/api/files/MPPPath.kt    | 11 ++++++
 .../islandoftex/arara/api/files/MPPPath.kt    | 34 +++++++++++++++++++
 rules/arara-rule-rmdir.yaml                   | 25 ++++++++++++++
 website/content/manual/Rules.md               | 14 +++++++-
 5 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 rules/arara-rule-rmdir.yaml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 12cdb8ae..4d79c231 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,11 @@ on.
 
 ## [Unreleased]
 
+### Added
+
+* A new `rmdir` rule to remove directories (thanks to @hackbaellchen).
+  (see !53)
+
 ## [7.1.2] - 2023-10-01
 
 ### Fixed
diff --git a/api/src/commonMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt b/api/src/commonMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
index fd6a347d..cf9c1136 100644
--- a/api/src/commonMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
+++ b/api/src/commonMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
@@ -132,4 +132,15 @@ public expect class MPPPath {
      */
     @Throws(AraraIOException::class)
     public fun createDirectories()
+
+    /**
+     * Treat this path as a directory identifier and remove it at
+     * this location including its contents.
+     * Does nothing if this directory does not exist at the current location.
+     *
+     * Fails with an [AraraIOException] if the directory could not be removed
+     * or a regular file exists at the location.
+     */
+    @Throws(AraraIOException::class)
+    public fun removeDirectory()
 }
diff --git a/api/src/jvmMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt b/api/src/jvmMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
index 00886e5d..bac3df86 100644
--- a/api/src/jvmMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
+++ b/api/src/jvmMain/kotlin/org/islandoftex/arara/api/files/MPPPath.kt
@@ -251,6 +251,40 @@ public actual class MPPPath {
             throw AraraIOException("Directory already exists as a file.")
         }
     }
+
+    /**
+     * Treat this path as a directory identifier and remove it at
+     * this location including its contents.
+     * Does nothing if this directory does not exist at the current location.
+     * As VfsFile::delete can only remove empty directories, a recursive
+     * function call is made to clear the directory first.
+     *
+     * Fails with an [AraraIOException] if the directory could not be removed
+     * or a regular file exists at the location.
+     */
+    public actual fun removeDirectory() {
+        fun removePotentiallyNonEmptyDir(file: VfsFile) {
+            runBlockingNoJs {
+                if (file.exists()) {
+                    if (file.isDirectory()) {
+                        for (child in file.listSimple()) {
+                            removePotentiallyNonEmptyDir(child)
+                        }
+                    }
+                    file.delete()
+                }
+            }
+        }
+        runBlockingNoJs {
+            if (vfsFile.exists()) {
+                if (vfsFile.isDirectory()) {
+                    removePotentiallyNonEmptyDir(vfsFile)
+                } else {
+                    throw AraraIOException("Target directory is a file.")
+                }
+            }
+        }
+    }
 }
 
 /**
diff --git a/rules/arara-rule-rmdir.yaml b/rules/arara-rule-rmdir.yaml
new file mode 100644
index 00000000..04da08fe
--- /dev/null
+++ b/rules/arara-rule-rmdir.yaml
@@ -0,0 +1,25 @@
+!config
+# Arara, the cool TeX automation tool
+# Copyright (c) 2024, Island of TeX
+# All rights reserved.
+#
+# This rule is part of arara.
+identifier: rmdir
+name: Remove subdirectory
+authors:
+- hackbaellchen
+- Island of TeX
+commands:
+- name: Remove subdirectory
+  command: >
+    @{
+        toFile(target[0]).removeDirectory();
+        return true;
+    }
+arguments:
+- identifier: target
+  flag: >
+    @{
+        return parameters.target;
+    }
+  required: true
diff --git a/website/content/manual/Rules.md b/website/content/manual/Rules.md
index 608ee287..2f719f21 100644
--- a/website/content/manual/Rules.md
+++ b/website/content/manual/Rules.md
@@ -2226,12 +2226,24 @@ providing capabilities to developers.
 % arara: --> 'output.pdf' ] }
 ```
 
+# `rmdir`
+
+This rule removes a directory including its contents at the current location.
+It does nothing if the directory does not exist.
+
+- **[R]** `target`: This option, as the name implies, specifies the name of the
+  target directory to be removed. Keep in mind that this option is required.
+
+```tex
+% arara: rmdir: { target: 'dir_to_remove' }
+```
+
 # `sage`
 
 This rule runs `sage`, a free open source mathematics software system, on the
 corresponding base name of the `❖ currentFile` reference (i.e, the
 name without the associated extension) as a string concatenated with the `sage`
-extension (which can be overriden).
+extension (which can be overridden).
 
 - `program` (default: `sage`): This option, as the name indicates, sets the
   program name. If the tool is not directly available in your system path, make