Add rmdir rule

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

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()
 }

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.")
+                }
+            }
+        }
+    }
 }
 
 /**

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

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