Merge pull request #729 from godot-rust/qol/streamlined-modules

Flatten modules - part I: merge to `godot::global`

Author: Bromeon

godot-codegen/src/generator/central_files.rs

@@ -59,7 +59,7 @@ pub fn make_core_central_code(api: &ExtensionApi, ctx: &mut Context) -> TokenStr
         ..
     } = make_variant_enums(api, ctx);
 
-    let global_enum_defs = make_global_enums(api);
+    let (global_enum_defs, global_reexported_enum_defs) = make_global_enums(api);
     let variant_type_traits = make_variant_type_enum(api, false).0;
 
     // TODO impl Clone, Debug, PartialEq, PartialOrd, Hash for VariantDispatch
@@ -107,16 +107,16 @@ pub fn make_core_central_code(api: &ExtensionApi, ctx: &mut Context) -> TokenStr
             }
         }
 
-        /// Global enums and constants.
-        ///
-        /// A list of global-scope enumerated constants.
-        /// For global built-in functions, check out the [`utilities` module][crate::engine::utilities].
-        ///
-        /// See also [Godot docs for `@GlobalScope`](https://docs.godotengine.org/en/stable/classes/[email protected]#enumerations).
-        pub mod global {
+        /// Global enums and constants, generated by Godot.
+        pub mod global_enums {
             use crate::sys;
             #( #global_enum_defs )*
         }
+
+       pub mod global_reexported_enums {
+            use crate::sys;
+            #( #global_reexported_enum_defs )*
+        }
     }
 }
 
@@ -183,8 +183,9 @@ fn make_variant_enums(api: &ExtensionApi, ctx: &mut Context) -> VariantEnums {
     result
 }
 
-fn make_global_enums(api: &ExtensionApi) -> Vec<TokenStream> {
+fn make_global_enums(api: &ExtensionApi) -> (Vec<TokenStream>, Vec<TokenStream>) {
     let mut global_enum_defs = vec![];
+    let mut global_reexported_enum_defs = vec![];
 
     for enum_ in api.global_enums.iter() {
         // Skip VariantType, which is already defined in godot-ffi.
@@ -193,10 +194,15 @@ fn make_global_enums(api: &ExtensionApi) -> Vec<TokenStream> {
         }
 
         let def = enums::make_enum_definition(enum_);
-        global_enum_defs.push(def);
+
+        if enum_.is_private {
+            global_reexported_enum_defs.push(def);
+        } else {
+            global_enum_defs.push(def);
+        }
     }
 
-    global_enum_defs
+    (global_enum_defs, global_reexported_enum_defs)
 }
 
 fn make_variant_type_enum(api: &ExtensionApi, is_definition: bool) -> (TokenStream, TokenStream) {

godot-codegen/src/generator/enums.rs

@@ -72,7 +72,7 @@ pub fn make_enum_definition_with(
         // Non-exhaustive enums are declared as newtype structs with associated constants.
         else {
             // Workaround because traits are defined in separate crate, but need access to field `ord`.
-            let vis = (!define_traits).then(|| {
+            let ord_vis = (!define_traits).then(|| {
                 quote! { #[doc(hidden)] pub }
             });
 
@@ -82,7 +82,7 @@ pub fn make_enum_definition_with(
                 #[derive( #( #derives ),* )]
                 #( #[doc = #enum_doc] )*
                 pub struct #name {
-                    #vis ord: #ord_type
+                    #ord_vis ord: #ord_type
                 }
 
                 impl #name {

godot-codegen/src/generator/utility_functions.rs

@@ -27,13 +27,6 @@ pub(crate) fn generate_utilities_file(
     let imports = util::make_imports();
 
     let tokens = quote! {
-        //! Global utility functions.
-        //!
-        //! A list of global-scope built-in functions.
-        //! For global enums and constants, check out the [`global` module][crate::engine::global].
-        //!
-        //! See also [Godot docs for `@GlobalScope`](https://docs.godotengine.org/en/stable/classes/[email protected]#methods).
-
         #imports
 
         #(#utility_fn_defs)*

godot-codegen/src/models/domain/enums.rs

@@ -18,6 +18,7 @@ pub struct Enum {
     pub name: Ident,
     pub godot_name: String,
     pub is_bitfield: bool,
+    pub is_private: bool,
     pub is_exhaustive: bool,
     pub enumerators: Vec<Enumerator>,
 }

godot-codegen/src/models/domain_mapping.rs

@@ -486,6 +486,15 @@ impl UtilityFunction {
             return None;
         }
 
+        // Some vararg functions like print() or str() are declared with a single argument "arg1: Variant", but that seems
+        // to be a mistake. We change their parameter list by removing that.
+        let args = option_as_slice(&function.arguments);
+        let parameters = if function.is_vararg && args.len() == 1 && args[0].name == "arg1" {
+            vec![]
+        } else {
+            FnParam::new_range(&function.arguments, ctx)
+        };
+
         let godot_method_name = function.name.clone();
         let rust_method_name = godot_method_name.clone(); // No change for now.
 
@@ -498,7 +507,7 @@ impl UtilityFunction {
             common: FunctionCommon {
                 name: rust_method_name,
                 godot_name: godot_method_name,
-                parameters: FnParam::new_range(&function.arguments, ctx),
+                parameters,
                 return_value: FnReturn::new(&return_value, ctx),
                 is_vararg: function.is_vararg,
                 is_private: false,
@@ -517,6 +526,7 @@ impl Enum {
     pub fn from_json(json_enum: &JsonEnum, surrounding_class: Option<&TyName>) -> Self {
         let godot_name = &json_enum.name;
         let is_bitfield = json_enum.is_bitfield;
+        let is_private = special_cases::is_enum_private(surrounding_class, godot_name);
         let is_exhaustive = special_cases::is_enum_exhaustive(surrounding_class, godot_name);
 
         let rust_enum_name = conv::make_enum_name_str(godot_name);
@@ -551,6 +561,7 @@ impl Enum {
             name: ident(&rust_enum_name),
             godot_name: godot_name.clone(),
             is_bitfield,
+            is_private,
             is_exhaustive,
             enumerators,
         }

godot-codegen/src/special_cases/special_cases.rs

@@ -37,7 +37,7 @@ pub fn is_class_method_deleted(class_name: &TyName, method: &JsonClassMethod, ct
     }
 
     match (class_name.godot_ty.as_str(), method.name.as_str()) {
-        // Already covered by manual APIs
+        // Already covered by manual APIs.
         //| ("Object", "to_string")
         | ("Object", "get_instance_id")
 
@@ -280,8 +280,15 @@ pub fn is_builtin_type_scalar(name: &str) -> bool {
     name.chars().next().unwrap().is_ascii_lowercase()
 }
 
+#[rustfmt::skip]
 pub fn is_utility_function_deleted(function: &JsonUtilityFunction, ctx: &mut Context) -> bool {
-    codegen_special_cases::is_utility_function_excluded(function, ctx)
+    /*let hardcoded = match function.name.as_str() {
+        | "..."
+
+        => true, _ => false
+    };
+
+    hardcoded ||*/ codegen_special_cases::is_utility_function_excluded(function, ctx)
 }
 
 pub fn maybe_rename_class_method<'m>(class_name: &TyName, godot_method_name: &'m str) -> &'m str {
@@ -355,6 +362,21 @@ pub fn is_class_level_server(class_name: &str) -> bool {
     }
 }
 
+/// Whether a generated enum is `pub(crate)`; useful for manual re-exports.
+#[rustfmt::skip]
+pub fn is_enum_private(class_name: Option<&TyName>, enum_name: &str) -> bool {
+    match (class_name, enum_name) {
+        // Re-exported to godot::builtin.
+        | (None, "Corner")
+        | (None, "EulerOrder")
+        | (None, "Side")
+        | (None, "Variant.Operator")
+        | (None, "Variant.Type")
+
+        => true, _ => false
+    }
+}
+
 /// Certain enums that are extremely unlikely to get new identifiers in the future.
 /// 
 /// `class_name` = None for global enums.

godot-core/src/builtin/color.rs

@@ -5,24 +5,21 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use crate::builtin::color_hsv::rgba_to_hsva;
 use crate::builtin::inner::InnerColor;
 use crate::builtin::math::ApproxEq;
-use crate::builtin::GString;
-
+use crate::builtin::meta::impl_godot_as_self;
+use crate::builtin::{ColorHsv, GString};
 use godot_ffi as sys;
-use sys::{ffi_methods, GodotFfi};
-
 use std::ops;
-
-use super::meta::impl_godot_as_self;
-use super::{rgba_to_hsva, ColorHsv};
+use sys::{ffi_methods, GodotFfi};
 
 /// Color built-in type, in floating-point RGBA format.
 ///
 /// Channel values are _typically_ in the range of 0 to 1, but this is not a requirement, and
 /// values outside this range are explicitly allowed for e.g. High Dynamic Range (HDR).
 ///
-/// To access its [**HSVA**](super::ColorHsv) representation, use [`Color::to_hsv`].
+/// To access its [**HSVA**](ColorHsv) representation, use [`Color::to_hsv`].
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -100,8 +97,8 @@ impl Color {
     /// Constructs a `Color` from a string, which can be either:
     ///
     /// - An HTML color code as accepted by [`Color::from_html`].
-    /// - The name of a built-in color constant, such as `BLUE` or `lawn-green`. Matching is case
-    ///   insensitive and hyphens can be used interchangeably with underscores. See the [list of
+    /// - The name of a built-in color constant, such as `BLUE` or `lawn-green`. Matching is case-insensitive
+    ///   and hyphens can be used interchangeably with underscores. See the [list of
     ///   color constants][color_constants] in the Godot API documentation, or the visual [cheat
     ///   sheet][cheat_sheet] for the full list.
     ///
@@ -365,6 +362,7 @@ impl ApproxEq for Color {
     }
 }
 
+/// Defines how individual color channels are laid out in memory.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum ColorChannelOrder {
     /// RGBA channel order. Godot's default.
@@ -566,7 +564,7 @@ impl std::fmt::Display for Color {
     /// # Example
     /// ```
     /// use godot::prelude::*;
-    /// let color = Color::from_rgba(1.0,1.0,1.0,1.0);
+    /// let color = Color::from_rgba(1.0, 1.0, 1.0, 1.0);
     /// assert_eq!(format!("{}", color), "(1, 1, 1, 1)");
     /// ```
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

godot-core/src/builtin/color_constants.rs

@@ -7,7 +7,7 @@
 
 use crate::builtin::Color;
 
-/// Godot's predefined colors
+/// Godot's predefined colors.
 ///
 /// This [visual cheat sheet](https://raw.githubusercontent.com/godotengine/godot-docs/master/img/color_constants.png)
 /// shows how the colors look.

godot-core/src/builtin/meta/godot_convert/mod.rs

@@ -57,16 +57,16 @@ pub trait ToGodot: Sized + GodotConvert {
 
 /// Defines the canonical conversion from Godot for a type.
 ///
-/// It is assumed that all the methods return equal values given equal inputs. Additionally it is assumed
+/// It is assumed that all the methods return equal values given equal inputs. Additionally, it is assumed
 /// that if [`ToGodot`] is implemented, converting to Godot and back again will return a value equal to the
 /// starting value.
 ///
 /// Violating these assumptions is safe but will give unexpected results.
 pub trait FromGodot: Sized + GodotConvert {
-    /// Performs the conversion.
+    /// Converts the Godot representation to this type, returning `Err` on failure.
     fn try_from_godot(via: Self::Via) -> Result<Self, ConvertError>;
 
-    /// ⚠️ Performs the conversion.
+    /// ⚠️ Converts the Godot representation to this type.
     ///
     /// # Panics
     /// If the conversion fails.
@@ -75,7 +75,7 @@ pub trait FromGodot: Sized + GodotConvert {
             .unwrap_or_else(|err| panic!("FromGodot::from_godot() failed: {err}"))
     }
 
-    /// Performs the conversion from a [`Variant`].
+    /// Performs the conversion from a [`Variant`], returning `Err` on failure.
     fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError> {
         let ffi = <Self::Via as GodotType>::Ffi::ffi_from_variant(variant)?;
 

godot-core/src/builtin/meta/mod.rs

@@ -21,7 +21,7 @@ pub use signature::*;
 pub(crate) use godot_convert::convert_error::*;
 
 use crate::builtin::*;
-use crate::engine::global::{self, PropertyHint, PropertyUsageFlags};
+use crate::global::{self, PropertyHint, PropertyUsageFlags};
 use crate::property::Var;
 use crate::property::{Export, PropertyHintInfo};
 use godot_ffi as sys;

godot-core/src/builtin/mod.rs

@@ -36,6 +36,12 @@
 // Re-export macros.
 pub use crate::{array, dict, real, reals, varray};
 
+// Re-export generated enums.
+pub use crate::gen::central::global_reexported_enums::{Corner, EulerOrder, Side, VariantOperator};
+pub use crate::sys::VariantType;
+// Not yet public.
+pub(crate) use crate::gen::central::VariantDispatch;
+
 #[doc(hidden)]
 pub mod __prelude_reexport {
     use super::*;
@@ -62,6 +68,7 @@ pub mod __prelude_reexport {
     pub use variant::*;
     pub use vectors::*;
 
+    pub use super::{EulerOrder, Side, VariantOperator, VariantType};
     pub use crate::{array, dict, real, reals, varray};
 }
 
@@ -148,16 +155,14 @@ pub(crate) fn u8_to_bool(u: u8) -> bool {
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Deprecated enums
+
 /// The side of a [`Rect2`] or [`Rect2i`].
 ///
 /// _Godot equivalent: `@GlobalScope.Side`_
-#[deprecated(note = "Merged with `godot::global::Side`.")]
-pub type RectSide = crate::engine::global::Side;
-use crate::engine::global::Side;
-
-/// The ordering used to interpret a set of euler angles as extrinsic rotations.
-#[deprecated(note = "Merged with `godot::global::EulerOrder`.")]
-pub type EulerOrder = crate::engine::global::EulerOrder;
+#[deprecated = "Merged with `godot::builtin::Side`."]
+pub type RectSide = Side;
 
 #[allow(non_upper_case_globals)]
 impl Side {

godot-core/src/builtin/variant/impls.rs

@@ -10,7 +10,7 @@ use crate::builtin::meta::{
     ArrayElement, FromVariantError, GodotFfiVariant, GodotType, PropertyInfo,
 };
 use crate::builtin::*;
-use crate::engine::global;
+use crate::global;
 use godot_ffi as sys;
 
 // For godot-cpp, see https://github.com/godotengine/godot-cpp/blob/master/include/godot_cpp/core/type_info.hpp.

godot-core/src/builtin/variant/mod.rs

@@ -6,15 +6,11 @@
  */
 
 use crate::builtin::meta::{impl_godot_as_self, ArrayElement, ConvertError, FromGodot, ToGodot};
-use crate::builtin::{GString, StringName};
-use crate::gen::central::VariantDispatch;
+use crate::builtin::{GString, StringName, VariantDispatch, VariantOperator, VariantType};
 use godot_ffi as sys;
 use std::{fmt, ptr};
 use sys::{ffi_methods, interface_fn, GodotFfi};
 
-pub use crate::engine::global::VariantOperator;
-pub use sys::VariantType;
-
 mod impls;
 
 /// Godot variant type, able to store a variety of different types.

godot-core/src/builtin/vectors/mod.rs

@@ -5,6 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+// Must be first.
 mod vector_macros;
 
 mod vector2;
@@ -14,6 +15,7 @@ mod vector3i;
 mod vector4;
 mod vector4i;
 mod vector_axis;
+mod vector_swizzle;
 
 pub use vector2::*;
 pub use vector2i::*;
@@ -22,5 +24,6 @@ pub use vector3i::*;
 pub use vector4::*;
 pub use vector4i::*;
 pub use vector_axis::*;
+pub use vector_swizzle::*;
 
 pub use crate::swizzle;

godot-core/src/builtin/vectors/vector2.rs

@@ -245,7 +245,7 @@ impl_common_vector_fns!(Vector2, real);
 impl_float_vector_glam_fns!(Vector2, real);
 impl_float_vector_component_fns!(Vector2, real, (x, y));
 impl_vector_operators!(Vector2, real, (x, y));
-impl_from_tuple_for_vector2x!(Vector2, real);
+impl_swizzle_trait_for_vector2x!(Vector2, real);
 
 // SAFETY:
 // This type is represented as `Self` in Godot, so `*mut Self` is sound.