mod.rs

/*
 * 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/.
 */

// Note: some code duplication with godot-codegen crate.

use crate::class::FuncDefinition;
use crate::ParseResult;
use proc_macro2::{Delimiter, Group, Ident, Literal, TokenStream, TokenTree};
use quote::spanned::Spanned;
use quote::{format_ident, quote, ToTokens, TokenStreamExt};
use venial::Attribute;

mod kv_parser;
mod list_parser;

pub(crate) use kv_parser::KvParser;
pub(crate) use list_parser::ListParser;

pub fn ident(s: &str) -> Ident {
    format_ident!("{}", s)
}

pub fn c_str(string: &str) -> Literal {
    let c_string = std::ffi::CString::new(string).expect("CString::new() failed");
    Literal::c_string(&c_string)
}

pub fn class_name_obj(class: &impl ToTokens) -> TokenStream {
    let class = class.to_token_stream();
    quote! { <#class as ::godot::obj::GodotClass>::class_name() }
}

pub fn bail_fn<R, T>(msg: impl AsRef<str>, tokens: T) -> ParseResult<R>
where
    T: Spanned,
{
    // TODO: using T: Spanned often only highlights the first tokens of the symbol, e.g. #[attr] in a function.
    // Could use function.name; possibly our own trait to get a more meaningful span... or change upstream in venial.

    Err(error_fn(msg, tokens))
}

macro_rules! bail {
    ($tokens:expr, $format_string:literal $($rest:tt)*) => {
        $crate::util::bail_fn(format!($format_string $($rest)*), $tokens)
    }
}

macro_rules! require_api_version {
    ($min_version:literal, $span:expr, $attribute:literal) => {
        if !cfg!(since_api = $min_version) {
            bail!(
                $span,
                "{} requires at least Godot API version {}",
                $attribute,
                $min_version
            )
        } else {
            Ok(())
        }
    };
}

pub fn error_fn<T>(msg: impl AsRef<str>, tokens: T) -> venial::Error
where
    T: Spanned,
{
    venial::Error::new_at_span(tokens.__span(), msg.as_ref())
}

macro_rules! error {
    ($tokens:expr, $format_string:literal $($rest:tt)*) => {
        $crate::util::error_fn(format!($format_string $($rest)*), $tokens)
    }
}

pub(crate) use bail;
pub(crate) use error;
pub(crate) use require_api_version;

pub fn reduce_to_signature(function: &venial::Function) -> venial::Function {
    let mut reduced = function.clone();
    reduced.vis_marker = None; // TODO needed?
    reduced.attributes.clear();
    reduced.tk_semicolon = None;
    reduced.body = None;

    reduced
}

pub fn parse_signature(mut signature: TokenStream) -> venial::Function {
    // Signature needs {} body to be parseable by venial
    signature.append(TokenTree::Group(Group::new(
        Delimiter::Brace,
        TokenStream::new(),
    )));

    let function_item = venial::parse_item(signature)
        .unwrap()
        .as_function()
        .unwrap()
        .clone();

    reduce_to_signature(&function_item)
}

/// Returns a type expression that can be used as a `VarcallSignatureTuple`.
pub fn make_signature_tuple_type(
    ret_type: &TokenStream,
    param_types: &[venial::TypeExpr],
) -> TokenStream {
    quote::quote! {
        (#ret_type, #(#param_types),*)
    }
}

fn is_punct(tt: &TokenTree, c: char) -> bool {
    match tt {
        TokenTree::Punct(punct) => punct.as_char() == c,
        _ => false,
    }
}

fn delimiter_opening_char(delimiter: Delimiter) -> char {
    match delimiter {
        Delimiter::Parenthesis => '(',
        Delimiter::Brace => '{',
        Delimiter::Bracket => '[',
        Delimiter::None => 'Ø',
    }
}

// ----------------------------------------------------------------------------------------------------------------------------------------------
// Validation for trait/impl

/// Given an impl block for a trait, returns whether that is an impl for a trait with the given name.
///
/// That is, if `name` is `"MyTrait"`, then this function returns true if and only if `original_impl` is a
/// declaration of the form `impl MyTrait for SomeType`. The type `SomeType` is irrelevant in this example.
pub(crate) fn is_impl_named(original_impl: &venial::Impl, name: &str) -> bool {
    let trait_name = original_impl.trait_ty.as_ref().unwrap(); // unwrap: already checked outside
    extract_typename(trait_name).is_some_and(|seg| seg.ident == name)
}

/// Validates either:
/// a) the declaration is `impl Trait for SomeType`, if `expected_trait` is `Some("Trait")`
/// b) the declaration is `impl SomeType`, if `expected_trait` is `None`
pub(crate) fn validate_impl(
    original_impl: &venial::Impl,
    expected_trait: Option<&str>,
    attr: &str,
) -> ParseResult<Ident> {
    if let Some(expected_trait) = expected_trait {
        // impl Trait for Self -- validate Trait
        if !is_impl_named(original_impl, expected_trait) {
            return bail!(
                original_impl,
                "#[{attr}] for trait impls requires trait to be `{expected_trait}`",
            );
        }
    }

    // impl Trait for Self -- validate Self
    validate_self(original_impl, attr)
}

/// Validates that the declaration is the of the form `impl Trait for SomeType`, where the name of `Trait` begins with `I`.
///
/// Returns `(class_name, trait_path, trait_base_class)`, e.g. `(MyClass, godot::prelude::INode3D, Node3D)`.
pub(crate) fn validate_trait_impl_virtual<'a>(
    original_impl: &'a venial::Impl,
    attr: &str,
) -> ParseResult<(Ident, &'a venial::TypeExpr, Ident)> {
    let trait_name = original_impl.trait_ty.as_ref().unwrap(); // unwrap: already checked outside
    let typename = extract_typename(trait_name);

    // Validate trait
    let Some(base_class) = typename
        .as_ref()
        .and_then(|seg| seg.ident.to_string().strip_prefix('I').map(ident))
    else {
        return bail!(
            original_impl,
            "#[{attr}] for trait impls requires a virtual method trait (trait name should start with 'I')",
        );
    };

    // Validate self
    validate_self(original_impl, attr).map(|class_name| {
        // let trait_name = typename.unwrap(); // unwrap: already checked in 'Validate trait'
        (class_name, trait_name, base_class)
    })
}

fn validate_self(original_impl: &venial::Impl, attr: &str) -> ParseResult<Ident> {
    if let Some(segment) = extract_typename(&original_impl.self_ty) {
        if segment.generic_args.is_none() {
            Ok(segment.ident)
        } else {
            bail!(
                original_impl,
                "#[{attr}] for does currently not support generic arguments",
            )
        }
    } else {
        bail!(
            original_impl,
            "#[{attr}] requires Self type to be a simple path",
        )
    }
}

/// Gets the right-most type name in the path.
pub(crate) fn extract_typename(ty: &venial::TypeExpr) -> Option<venial::PathSegment> {
    match ty.as_path() {
        Some(mut path) => path.segments.pop(),
        _ => None,
    }
}

// ----------------------------------------------------------------------------------------------------------------------------------------------

pub(crate) fn path_is_single(path: &[TokenTree], expected: &str) -> bool {
    path.len() == 1 && path[0].to_string() == expected
}

pub(crate) fn path_ends_with(path: &[TokenTree], expected: &str) -> bool {
    // Could also use TypeExpr::as_path(), or fn below this one.
    path.last().is_some_and(|last| last.to_string() == expected)
}

pub(crate) fn path_ends_with_complex(path: &venial::TypeExpr, expected: &str) -> bool {
    path.as_path().is_some_and(|path| {
        path.segments
            .last()
            .is_some_and(|seg| seg.ident == expected)
    })
}

pub(crate) fn extract_cfg_attrs(
    attrs: &[venial::Attribute],
) -> impl IntoIterator<Item = &venial::Attribute> {
    attrs.iter().filter(|attr| {
        let Some(attr_name) = attr.get_single_path_segment() else {
            return false;
        };
        if attr_name == "cfg" {
            return true;
        }
        if attr_name == "cfg_attr" && attr.value.to_token_stream().to_string().contains("cfg(") {
            return true;
        }
        false
    })
}

#[cfg(before_api = "4.3")]
pub fn make_virtual_tool_check() -> TokenStream {
    quote! {
        if ::godot::private::is_class_inactive(Self::__config().is_tool) {
            return None;
        }
    }
}

#[cfg(since_api = "4.3")]
pub fn make_virtual_tool_check() -> TokenStream {
    TokenStream::new()
}

// This function is duplicated in godot-codegen\src\util.rs
#[rustfmt::skip]
pub fn safe_ident(s: &str) -> Ident {
    // See also: https://doc.rust-lang.org/reference/keywords.html
    match s {
        // Lexer
        | "as" | "break" | "const" | "continue" | "crate" | "else" | "enum" | "extern" | "false" | "fn" | "for" | "if"
        | "impl" | "in" | "let" | "loop" | "match" | "mod" | "move" | "mut" | "pub" | "ref" | "return" | "self" | "Self"
        | "static" | "struct" | "super" | "trait" | "true" | "type" | "unsafe" | "use" | "where" | "while"

        // Lexer 2018+
        | "async" | "await" | "dyn"

        // Reserved
        | "abstract" | "become" | "box" | "do" | "final" | "macro" | "override" | "priv" | "typeof" | "unsized" | "virtual" | "yield"

        // Reserved 2018+
        | "try"
           => format_ident!("{}_", s),

         _ => ident(s)
    }
}

// ----------------------------------------------------------------------------------------------------------------------------------------------

/// Parses a `meta` TokenStream, that is, the tokens in parameter position of a proc-macro (between the braces).
/// Because venial can't actually parse a meta item directly, this is done by reconstructing the full macro attribute on top of some content and then parsing *that*.
pub fn venial_parse_meta(
    meta: &TokenStream,
    self_name: Ident,
    content: &TokenStream,
) -> Result<venial::Item, venial::Error> {
    // Hack because venial doesn't support direct meta parsing yet
    let input = quote! {
        #[#self_name(#meta)]
        #content
    };

    venial::parse_item(input)
}

// ----------------------------------------------------------------------------------------------------------------------------------------------

// util functions for handling #[func]s and #[var(get=f, set=f)]

pub fn make_function_registered_name_constants(
    funcs: &[FuncDefinition],
    class_name: &Ident,
) -> Vec<TokenStream> {
    funcs
        .iter()
        .map(|func| {
            // the constant needs the same #[cfg] attribute(s) as the function, so that it is only active if the function is also active.
            let cfg_attributes = extract_cfg_attrs(&func.external_attributes)
                .into_iter()
                .collect();
            make_function_registered_name_constant(
                class_name,
                &func.signature_info.method_name,
                &func.registered_name,
                &cfg_attributes,
            )
        })
        .collect()
}

/// Funcs can be renamed with `#[func(rename=new_name) fn f();`.
/// To be able to access the renamed function name at a later point, it is saved in a string constant.
/// This would create the following code for `f`:
/// ``pub const __gdext_func_{class_name}_f: &str = "new_name";``
pub fn make_function_registered_name_constant(
    class_name: &Ident,
    func_name: &Ident,
    registered_name: &Option<String>,
    attributes: &Vec<&Attribute>,
) -> TokenStream {
    let const_name = format_function_registered_name_constant_name(class_name, func_name);
    let const_value = match &registered_name {
        Some(renamed) => renamed.to_string(),
        None => func_name.to_string(),
    };

    let doc_comment = format!(
        "The rust function `{}` is registered with godot as `{}`.",
        func_name, const_value
    );

    quote! {
        #(#attributes)*
        #[doc = #doc_comment]
        #[doc(hidden)]
        #[allow(non_upper_case_globals)]
        pub const #const_name: &str  = #const_value;
    }
}

/// Returns the name of the constant that will be autogenerated.
pub fn format_function_registered_name_constant_name(
    class_name: &Ident,
    func_name: &Ident,
) -> Ident {
    format_ident!("__gdext_func_{}_{}", class_name, func_name)
}

/// Returns the name of the dummy struct that's used as container for all function name constants.
pub fn format_function_registered_name_struct_name(class_name: &Ident) -> Ident {
    format_ident!("{class_name}_Functions")
}