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/class_@globalscope.html#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/class_@globalscope.html#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;