Merge pull request #60408 from KoBeWi/statically_typed_directories

Introduce more static methods to directory API

4 files changed, 161 insertions, 15 deletions

diff --git a/core/io/dir_access.cpp b/core/io/dir_access.cpp
index 4454f2a100..f86dfe8057 100644
--- a/core/io/dir_access.cpp
+++ b/core/io/dir_access.cpp
@@ -261,6 +261,51 @@ Ref<DirAccess> DirAccess::_open(const String &p_path) {
 	return da;
 }
 
+int DirAccess::_get_drive_count() {
+	Ref<DirAccess> d = DirAccess::create(DirAccess::ACCESS_FILESYSTEM);
+	return d->get_drive_count();
+}
+
+String DirAccess::get_drive_name(int p_idx) {
+	Ref<DirAccess> d = DirAccess::create(DirAccess::ACCESS_FILESYSTEM);
+	return d->get_drive(p_idx);
+}
+
+Error DirAccess::make_dir_absolute(const String &p_dir) {
+	Ref<DirAccess> d = DirAccess::create_for_path(p_dir);
+	return d->make_dir(p_dir);
+}
+
+Error DirAccess::make_dir_recursive_absolute(const String &p_dir) {
+	Ref<DirAccess> d = DirAccess::create_for_path(p_dir);
+	return d->make_dir_recursive(p_dir);
+}
+
+bool DirAccess::dir_exists_absolute(const String &p_dir) {
+	Ref<DirAccess> d = DirAccess::create_for_path(p_dir);
+	return d->dir_exists(p_dir);
+}
+
+Error DirAccess::copy_absolute(const String &p_from, const String &p_to, int p_chmod_flags) {
+	Ref<DirAccess> d = DirAccess::create(DirAccess::ACCESS_FILESYSTEM);
+	// Support copying from res:// to user:// etc.
+	String from = ProjectSettings::get_singleton()->globalize_path(p_from);
+	String to = ProjectSettings::get_singleton()->globalize_path(p_to);
+	return d->copy(from, to, p_chmod_flags);
+}
+
+Error DirAccess::rename_absolute(const String &p_from, const String &p_to) {
+	Ref<DirAccess> d = DirAccess::create(DirAccess::ACCESS_FILESYSTEM);
+	String from = ProjectSettings::get_singleton()->globalize_path(p_from);
+	String to = ProjectSettings::get_singleton()->globalize_path(p_to);
+	return d->rename(from, to);
+}
+
+Error DirAccess::remove_absolute(const String &p_path) {
+	Ref<DirAccess> d = DirAccess::create_for_path(p_path);
+	return d->remove(p_path);
+}
+
 Ref<DirAccess> DirAccess::create(AccessType p_access) {
 	Ref<DirAccess> da = create_func[p_access] ? create_func[p_access]() : nullptr;
 	if (da.is_valid()) {
@@ -445,10 +490,20 @@ PackedStringArray DirAccess::get_files() {
 	return _get_contents(false);
 }
 
+PackedStringArray DirAccess::get_files_at(const String &p_path) {
+	Ref<DirAccess> da = DirAccess::open(p_path);
+	return da->get_files();
+}
+
 PackedStringArray DirAccess::get_directories() {
 	return _get_contents(true);
 }
 
+PackedStringArray DirAccess::get_directories_at(const String &p_path) {
+	Ref<DirAccess> da = DirAccess::open(p_path);
+	return da->get_directories();
+}
+
 PackedStringArray DirAccess::_get_contents(bool p_directories) {
 	PackedStringArray ret;
 
@@ -498,20 +553,28 @@ void DirAccess::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("current_is_dir"), &DirAccess::current_is_dir);
 	ClassDB::bind_method(D_METHOD("list_dir_end"), &DirAccess::list_dir_end);
 	ClassDB::bind_method(D_METHOD("get_files"), &DirAccess::get_files);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("get_files_at", "path"), &DirAccess::get_files_at);
 	ClassDB::bind_method(D_METHOD("get_directories"), &DirAccess::get_directories);
-	ClassDB::bind_method(D_METHOD("get_drive_count"), &DirAccess::get_drive_count);
-	ClassDB::bind_method(D_METHOD("get_drive", "idx"), &DirAccess::get_drive);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("get_directories_at", "path"), &DirAccess::get_directories_at);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("get_drive_count"), &DirAccess::_get_drive_count);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("get_drive_name", "idx"), &DirAccess::get_drive_name);
 	ClassDB::bind_method(D_METHOD("get_current_drive"), &DirAccess::get_current_drive);
-	ClassDB::bind_method(D_METHOD("change_dir", "todir"), &DirAccess::change_dir);
+	ClassDB::bind_method(D_METHOD("change_dir", "to_dir"), &DirAccess::change_dir);
 	ClassDB::bind_method(D_METHOD("get_current_dir", "include_drive"), &DirAccess::get_current_dir, DEFVAL(true));
 	ClassDB::bind_method(D_METHOD("make_dir", "path"), &DirAccess::make_dir);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("make_dir_absolute", "path"), &DirAccess::make_dir_absolute);
 	ClassDB::bind_method(D_METHOD("make_dir_recursive", "path"), &DirAccess::make_dir_recursive);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("make_dir_recursive_absolute", "path"), &DirAccess::make_dir_recursive_absolute);
 	ClassDB::bind_method(D_METHOD("file_exists", "path"), &DirAccess::file_exists);
 	ClassDB::bind_method(D_METHOD("dir_exists", "path"), &DirAccess::dir_exists);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("dir_exists_absolute", "path"), &DirAccess::dir_exists_absolute);
 	ClassDB::bind_method(D_METHOD("get_space_left"), &DirAccess::get_space_left);
 	ClassDB::bind_method(D_METHOD("copy", "from", "to", "chmod_flags"), &DirAccess::copy, DEFVAL(-1));
+	ClassDB::bind_static_method("DirAccess", D_METHOD("copy_absolute", "from", "to", "chmod_flags"), &DirAccess::copy_absolute, DEFVAL(-1));
 	ClassDB::bind_method(D_METHOD("rename", "from", "to"), &DirAccess::rename);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("rename_absolute", "from", "to"), &DirAccess::rename_absolute);
 	ClassDB::bind_method(D_METHOD("remove", "path"), &DirAccess::remove);
+	ClassDB::bind_static_method("DirAccess", D_METHOD("remove_absolute", "path"), &DirAccess::remove_absolute);
 
 	ClassDB::bind_method(D_METHOD("set_include_navigational", "enable"), &DirAccess::set_include_navigational);
 	ClassDB::bind_method(D_METHOD("get_include_navigational"), &DirAccess::get_include_navigational);
diff --git a/core/io/dir_access.h b/core/io/dir_access.h
index a694f6388f..ee675f1c89 100644
--- a/core/io/dir_access.h
+++ b/core/io/dir_access.h
@@ -136,8 +136,21 @@ public:
 	static Ref<DirAccess> open(const String &p_path, Error *r_error = nullptr);
 	static Ref<DirAccess> _open(const String &p_path);
 
+	static int _get_drive_count();
+	static String get_drive_name(int p_idx);
+
+	static Error make_dir_absolute(const String &p_dir);
+	static Error make_dir_recursive_absolute(const String &p_dir);
+	static bool dir_exists_absolute(const String &p_dir);
+
+	static Error copy_absolute(const String &p_from, const String &p_to, int p_chmod_flags = -1);
+	static Error rename_absolute(const String &p_from, const String &p_to);
+	static Error remove_absolute(const String &p_path);
+
 	PackedStringArray get_files();
+	static PackedStringArray get_files_at(const String &p_path);
 	PackedStringArray get_directories();
+	static PackedStringArray get_directories_at(const String &p_path);
 	PackedStringArray _get_contents(bool p_directories);
 	String _get_next();
 
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">