Merge pull request #535 from StatisMike/feature/save_trysave

`save` and `try_save` functions and IO-utilites refactor in godot_core::engine refactor

Author: Bromeon

godot-codegen/src/codegen_special_cases.rs

@@ -162,6 +162,7 @@ const SELECTED_CLASSES: &[&str] = &[
     "Resource",
     "ResourceFormatLoader",
     "ResourceLoader",
+    "ResourceSaver",
     "RigidBody2D",
     "SceneTree",
     "SceneTreeTimer",

godot-core/src/engine/gfile.rs renamed to godot-core/src/engine/io/gfile.rs

@@ -0,0 +1,178 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use std::error::Error;
+
+use crate::engine::global::Error as GodotError;
+use crate::gen::classes::FileAccess;
+use crate::obj::{Gd, NotUniqueError};
+
+/// Error that can occur while using `gdext` IO utilities.
+#[derive(Debug)]
+pub struct IoError {
+    data: ErrorData,
+}
+
+impl std::fmt::Display for IoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match &self.data {
+            ErrorData::Load(err) => err.fmt(f),
+            ErrorData::Save(err) => err.fmt(f),
+            ErrorData::GFile(err) => err.fmt(f),
+        }
+    }
+}
+
+impl Error for IoError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        if let ErrorData::GFile(GFileError {
+            kind: GFileErrorKind::NotUniqueRef(err),
+            ..
+        }) = &self.data
+        {
+            return Some(err);
+        }
+        None
+    }
+}
+
+impl IoError {
+    pub(crate) fn saving(error: GodotError, class: String, path: String) -> Self {
+        Self {
+            data: ErrorData::Save(SaverError {
+                class,
+                path,
+                godot_error: error,
+            }),
+        }
+    }
+
+    pub(crate) fn loading(class: String, path: String) -> Self {
+        Self {
+            data: ErrorData::Load(LoaderError {
+                kind: LoaderErrorKind::Load,
+                class,
+                path,
+            }),
+        }
+    }
+
+    pub(crate) fn loading_cast(class: String, path: String) -> Self {
+        Self {
+            data: ErrorData::Load(LoaderError {
+                kind: LoaderErrorKind::Cast,
+                class,
+                path,
+            }),
+        }
+    }
+
+    pub(crate) fn check_unique_open_file_access(
+        file_access: Gd<FileAccess>,
+    ) -> Result<Gd<FileAccess>, Self> {
+        let path = file_access.get_path();
+
+        if !file_access.is_open() {
+            return Err(Self {
+                data: ErrorData::GFile(GFileError {
+                    kind: GFileErrorKind::NotOpen,
+                    path: path.to_string(),
+                }),
+            });
+        }
+
+        match NotUniqueError::check(file_access) {
+            Ok(gd) => Ok(gd),
+            Err(err) => Err(Self {
+                data: ErrorData::GFile(GFileError {
+                    kind: GFileErrorKind::NotUniqueRef(err),
+                    path: path.to_string(),
+                }),
+            }),
+        }
+    }
+}
+
+#[derive(Debug)]
+enum ErrorData {
+    Load(LoaderError),
+    Save(SaverError),
+    GFile(GFileError),
+}
+
+#[derive(Debug)]
+struct LoaderError {
+    kind: LoaderErrorKind,
+    class: String,
+    path: String,
+}
+
+#[derive(Debug)]
+enum LoaderErrorKind {
+    Load,
+    Cast,
+}
+
+impl std::fmt::Display for LoaderError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let class = &self.class;
+        let path = &self.path;
+
+        match &self.kind {
+            LoaderErrorKind::Load => write!(
+                f,
+                "can't load resource of class: '{class}' from path: '{path}'"
+            ),
+            LoaderErrorKind::Cast => write!(
+                f,
+                "can't cast loaded resource to class: '{class}' from path: '{path}'"
+            ),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct SaverError {
+    class: String,
+    path: String,
+    godot_error: GodotError,
+}
+
+impl std::fmt::Display for SaverError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let class = &self.class;
+        let path = &self.path;
+        let godot_error = &self.godot_error;
+
+        write!(f, "can't save resource of class: '{class}' to path: '{path}'; Godot error: {godot_error:?}")
+    }
+}
+
+#[derive(Debug)]
+struct GFileError {
+    kind: GFileErrorKind,
+    path: String,
+}
+
+#[derive(Debug)]
+enum GFileErrorKind {
+    NotUniqueRef(NotUniqueError),
+    NotOpen,
+}
+
+impl std::fmt::Display for GFileError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let path = &self.path;
+
+        match &self.kind {
+            GFileErrorKind::NotUniqueRef(err) => {
+                write!(f, "access to file '{path}' is not unique: '{err}'")
+            }
+            GFileErrorKind::NotOpen => write!(f, "access to file '{path}' is not open"),
+        }
+    }
+}

godot-core/src/engine/io/io_error.rs

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+mod gfile;
+mod io_error;
+mod resources;
+
+pub use gfile::GFile;
+pub use io_error::*;
+pub use resources::{load, save, try_load, try_save};

godot-core/src/engine/io/mod.rs

@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use crate::builtin::GString;
+use crate::engine::global::Error as GodotError;
+use crate::gen::classes::{Resource, ResourceLoader, ResourceSaver};
+use crate::obj::{Gd, GodotClass, Inherits};
+
+use super::IoError;
+
+/// Loads a resource from the filesystem located at `path`, panicking on error.
+///
+/// See [`try_load`] for more information.
+///
+/// # Example
+///
+/// ```no_run
+/// use godot::prelude::*;
+///
+/// let scene = load::<PackedScene>("res://path/to/Main.tscn");
+/// ```
+///
+/// # Panics
+/// If the resource cannot be loaded, or is not of type `T` or inherited.
+#[inline]
+pub fn load<T>(path: impl Into<GString>) -> Gd<T>
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    let path = path.into();
+    load_impl(&path).unwrap_or_else(|err| panic!("failed: {err}"))
+}
+
+/// Loads a resource from the filesystem located at `path`.
+///
+/// The resource is loaded on the method call (unless it's referenced already elsewhere, e.g. in another script or in the scene),
+/// which might cause slight delay, especially when loading scenes.
+///
+/// This function can fail if resource can't be loaded by [`ResourceLoader`] or if the subsequent cast into `T` fails.
+///
+/// This method is a simplified version of [`ResourceLoader::load()`][crate::engine::ResourceLoader::load],
+/// which can be used for more advanced scenarios.
+///
+/// # Note:
+/// Resource paths can be obtained by right-clicking on a resource in the Godot editor (_FileSystem_ dock) and choosing "Copy Path",
+/// or by dragging the file from the _FileSystem_ dock into the script.
+///
+/// The path must be absolute (typically starting with `res://`), a local path will fail.
+///
+/// # Example
+/// Loads a scene called `Main` located in the `path/to` subdirectory of the Godot project and caches it in a variable.
+/// The resource is directly stored with type `PackedScene`.
+///
+/// ```no_run
+/// use godot::prelude::*;
+///
+/// if let Ok(scene) = try_load::<PackedScene>("res://path/to/Main.tscn") {
+///     // all good
+/// } else {
+///     // handle error
+/// }
+/// ```
+#[inline]
+pub fn try_load<T>(path: impl Into<GString>) -> Result<Gd<T>, IoError>
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    load_impl(&path.into())
+}
+
+/// Saves a [`Resource`]-inheriting [`GodotClass`] `obj` into file located at `path`.
+///
+/// See [`try_save`] for more information.
+///
+/// # Panics
+/// If the resouce cannot be saved.
+///
+/// # Example
+/// ```no_run
+/// use godot::prelude::*;
+/// use godot::engine::save;
+///
+/// save(Resource::new(), "res://base_resource.tres")
+/// ```
+/// use godot::
+#[inline]
+pub fn save<T>(obj: Gd<T>, path: impl Into<GString>)
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    let path = path.into();
+    save_impl(obj, &path)
+        .unwrap_or_else(|err| panic!("failed to save resource at path '{}': {}", &path, err));
+}
+
+/// Saves a [Resource]-inheriting [GodotClass] `obj` into file located at `path`.
+///
+/// This function can fail if [`ResourceSaver`] can't save the resource to file, as it is a simplified version of
+/// [`ResourceSaver::save()`][crate::engine::ResourceSaver::save]. The underlying method can be used for more advances scenarios.
+///
+/// # Note
+/// Target path must be presented in Godot-recognized format, mainly the ones beginning with `res://` and `user://`. Saving
+/// to `res://` is possible only when working with unexported project - after its export only `user://` is viable.
+///
+/// # Example
+/// ```no_run
+/// use godot::prelude::*;
+/// use godot::engine::try_save;
+///
+/// #[derive(GodotClass)]
+/// #[class(base=Resource, init)]
+/// struct SavedGame {
+///   // Exported properties are saved in `.tres` files.
+///   #[export]
+///   level: u32
+/// };
+///
+/// let save_state = SavedGame::new_gd();
+/// let res = try_save(save_state, "user://save.tres");
+///
+/// assert!(res.is_ok());
+/// ```
+#[inline]
+pub fn try_save<T>(obj: Gd<T>, path: impl Into<GString>) -> Result<(), IoError>
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    save_impl(obj, &path.into())
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Implementation of this file
+
+// Separate function, to avoid constructing string twice
+// Note that more optimizations than that likely make no sense, as loading is quite expensive
+fn load_impl<T>(path: &GString) -> Result<Gd<T>, IoError>
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    // TODO unclone GString
+    match ResourceLoader::singleton()
+        .load_ex(path.clone())
+        .type_hint(T::class_name().to_gstring())
+        .done()
+    {
+        Some(res) => match res.try_cast::<T>() {
+            Ok(obj) => Ok(obj),
+            Err(_) => Err(IoError::loading_cast(
+                T::class_name().to_string(),
+                path.to_string(),
+            )),
+        },
+        None => Err(IoError::loading(
+            T::class_name().to_string(),
+            path.to_string(),
+        )),
+    }
+}
+
+fn save_impl<T>(obj: Gd<T>, path: &GString) -> Result<(), IoError>
+where
+    T: GodotClass + Inherits<Resource>,
+{
+    // TODO unclone GString
+    let res = ResourceSaver::singleton()
+        .save_ex(obj.upcast())
+        .path(path.clone())
+        .done();
+
+    if res == GodotError::OK {
+        return Ok(());
+    }
+    Err(IoError::saving(
+        res,
+        T::class_name().to_string(),
+        path.to_string(),
+    ))
+}