Merge pull request #60408 from KoBeWi/statically_typed_directories

Introduce more static methods to directory API

2 files changed, 82 insertions, 12 deletions

diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml
index de2e32b17b..cb7bf56f11 100644
--- a/doc/classes/DirAccess.xml
+++ b/doc/classes/DirAccess.xml
@@ -6,6 +6,15 @@
 	<description>
 		Directory type. It is used to manage directories and their content (not restricted to the project folder).
 		[DirAccess] can't be instantiated directly. Instead it is created with a static method that takes a path for which it will be opened.
+		Most of the methods have a static alternative that can be used without creating a [DirAccess]. Static methods only support absolute paths (including [code]res://[/code] and [code]user://[/code]).
+		[codeblock]
+		# Standard
+		var dir = Directory.new()
+		dir.open("user://levels")
+		dir.make_dir("world1")
+		# Static
+		Directory.make_dir_absolute("user://levels/world1")
+		[/codeblock]
 		[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use [ResourceLoader] to access imported resources.
 		Here is an example on how to iterate through the files of a directory:
 		[codeblocks]
@@ -59,7 +68,7 @@
 	<methods>
 		<method name="change_dir">
 			<return type="int" enum="Error" />
-			<param index="0" name="todir" type="String" />
+			<param index="0" name="to_dir" type="String" />
 			<description>
 				Changes the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. [code]newdir[/code] or [code]../newdir[/code]), or an absolute path (e.g. [code]/tmp/newdir[/code] or [code]res://somedir/newdir[/code]).
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
@@ -76,6 +85,15 @@
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
 			</description>
 		</method>
+		<method name="copy_absolute" qualifiers="static">
+			<return type="int" enum="Error" />
+			<param index="0" name="from" type="String" />
+			<param index="1" name="to" type="String" />
+			<param index="2" name="chmod_flags" type="int" default="-1" />
+			<description>
+				Static version of [method copy]. Supports only absolute paths.
+			</description>
+		</method>
 		<method name="current_is_dir" qualifiers="const">
 			<return type="bool" />
 			<description>
@@ -87,7 +105,13 @@
 			<param index="0" name="path" type="String" />
 			<description>
 				Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path.
-				If the [DirAccess] is not open, the path is relative to [code]res://[/code].
+			</description>
+		</method>
+		<method name="dir_exists_absolute" qualifiers="static">
+			<return type="bool" />
+			<param index="0" name="path" type="String" />
+			<description>
+				Static version of [method dir_exists]. Supports only absolute paths.
 			</description>
 		</method>
 		<method name="file_exists">
@@ -95,7 +119,7 @@
 			<param index="0" name="path" type="String" />
 			<description>
 				Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path.
-				If the [DirAccess] is not open, the path is relative to [code]res://[/code].
+				For a static equivalent, use [method FileAccess.file_exists].
 			</description>
 		</method>
 		<method name="get_current_dir" qualifiers="const">
@@ -108,7 +132,7 @@
 		<method name="get_current_drive">
 			<return type="int" />
 			<description>
-				Returns the currently opened directory's drive index. See [method get_drive] to convert returned index to the name of the drive.
+				Returns the currently opened directory's drive index. See [method get_drive_name] to convert returned index to the name of the drive.
 			</description>
 		</method>
 		<method name="get_directories">
@@ -118,17 +142,15 @@
 				Affected by [member include_hidden] and [member include_navigational].
 			</description>
 		</method>
-		<method name="get_drive">
-			<return type="String" />
-			<param index="0" name="idx" type="int" />
+		<method name="get_directories_at" qualifiers="static">
+			<return type="PackedStringArray" />
+			<param index="0" name="path" type="String" />
 			<description>
-				On Windows, returns the name of the drive (partition) passed as an argument (e.g. [code]C:[/code]).
-				On macOS, returns the path to the mounted volume passed as an argument.
-				On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument.
-				On other platforms, or if the requested drive does not exist, the method returns an empty String.
+				Returns a [PackedStringArray] containing filenames of the directory contents, excluding files, at the given [param path]. The array is sorted alphabetically.
+				Use [method get_directories] if you want more control of what gets included.
 			</description>
 		</method>
-		<method name="get_drive_count">
+		<method name="get_drive_count" qualifiers="static">
 			<return type="int" />
 			<description>
 				On Windows, returns the number of drives (partitions) mounted on the current filesystem.
@@ -137,6 +159,16 @@
 				On other platforms, the method returns 0.
 			</description>
 		</method>
+		<method name="get_drive_name" qualifiers="static">
+			<return type="String" />
+			<param index="0" name="idx" type="int" />
+			<description>
+				On Windows, returns the name of the drive (partition) passed as an argument (e.g. [code]C:[/code]).
+				On macOS, returns the path to the mounted volume passed as an argument.
+				On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument.
+				On other platforms, or if the requested drive does not exist, the method returns an empty String.
+			</description>
+		</method>
 		<method name="get_files">
 			<return type="PackedStringArray" />
 			<description>
@@ -144,6 +176,14 @@
 				Affected by [member include_hidden].
 			</description>
 		</method>
+		<method name="get_files_at" qualifiers="static">
+			<return type="PackedStringArray" />
+			<param index="0" name="path" type="String" />
+			<description>
+				Returns a [PackedStringArray] containing filenames of the directory contents, excluding directories, at the given [param path]. The array is sorted alphabetically.
+				Use [method get_files] if you want more control of what gets included.
+			</description>
+		</method>
 		<method name="get_next">
 			<return type="String" />
 			<description>
@@ -185,6 +225,13 @@
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
 			</description>
 		</method>
+		<method name="make_dir_absolute" qualifiers="static">
+			<return type="int" enum="Error" />
+			<param index="0" name="path" type="String" />
+			<description>
+				Static version of [method make_dir]. Supports only absolute paths.
+			</description>
+		</method>
 		<method name="make_dir_recursive">
 			<return type="int" enum="Error" />
 			<param index="0" name="path" type="String" />
@@ -193,6 +240,13 @@
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
 			</description>
 		</method>
+		<method name="make_dir_recursive_absolute" qualifiers="static">
+			<return type="int" enum="Error" />
+			<param index="0" name="path" type="String" />
+			<description>
+				Static version of [method make_dir_recursive]. Supports only absolute paths.
+			</description>
+		</method>
 		<method name="open" qualifiers="static">
 			<return type="DirAccess" />
 			<param index="0" name="path" type="String" />
@@ -210,6 +264,13 @@
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
 			</description>
 		</method>
+		<method name="remove_absolute" qualifiers="static">
+			<return type="int" enum="Error" />
+			<param index="0" name="path" type="String" />
+			<description>
+				Static version of [method remove]. Supports only absolute paths.
+			</description>
+		</method>
 		<method name="rename">
 			<return type="int" enum="Error" />
 			<param index="0" name="from" type="String" />
@@ -219,6 +280,14 @@
 				Returns one of the [enum Error] code constants ([code]OK[/code] on success).
 			</description>
 		</method>
+		<method name="rename_absolute" qualifiers="static">
+			<return type="int" enum="Error" />
+			<param index="0" name="from" type="String" />
+			<param index="1" name="to" type="String" />
+			<description>
+				Static version of [method rename]. Supports only absolute paths.
+			</description>
+		</method>
 	</methods>
 	<members>
 		<member name="include_hidden" type="bool" setter="set_include_hidden" getter="get_include_hidden">
diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml
index 32f6a1dd3e..adc0f4c3dd 100644
--- a/doc/classes/FileAccess.xml
+++ b/doc/classes/FileAccess.xml
@@ -77,6 +77,7 @@
 			<description>
 				Returns [code]true[/code] if the file exists in the given path.
 				[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See [method ResourceLoader.exists] for an alternative approach that takes resource remapping into account.
+				For a non-static, relative equivalent, use [method DirAccess.file_exists].
 			</description>
 		</method>
 		<method name="flush">