refactor(macro): add stubs for new builder pattern

Resolves: #183

Author: Xenira

Cargo.toml

@@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0"
 keywords = ["php", "ffi", "zend"]
 version = "0.13.1"
 authors = ["David Cole <[email protected]>"]
-edition = "2018"
+edition = "2021"
 categories = ["api-bindings"]
 exclude = ["/.github", "/.crates", "/guide"]
 

crates/macros/Cargo.toml

@@ -19,6 +19,7 @@ quote = "1.0.9"
 proc-macro2 = "1.0.26"
 lazy_static = "1.4.0"
 anyhow = "1.0"
+lsp_doc_stable = "0.1.0"
 
 [lints.rust]
 missing_docs = "warn"

crates/macros/src/class.rs

@@ -4,6 +4,7 @@ use quote::quote;
 use syn::parse::ParseStream;
 use syn::{Attribute, AttributeArgs, Expr, Fields, ItemStruct, LitStr, Token};
 
+use crate::helpers::get_docs;
 use crate::prelude::*;
 
 #[derive(Debug, Default, FromMeta)]
@@ -25,7 +26,7 @@ pub struct StructArgs {
 struct ClassAttrs {
     extends: Option<syn::Expr>,
     implements: Vec<syn::Expr>,
-    comments: Vec<String>,
+    docs: Vec<String>,
 }
 
 impl ClassAttrs {
@@ -48,16 +49,11 @@ impl ClassAttrs {
                     Err(_) => bail!(attr => "Invalid arguments passed to implements attribute."),
                 };
                 self.implements.push(implements);
-            } else if attr.path.is_ident("doc") {
-                let comment: LitStr = match attr.parse_args() {
-                    Ok(comment) => comment,
-                    Err(_) => bail!(attr => "Invalid arguments passed to doc attribute."),
-                };
-                self.comments.push(comment.value());
             } else {
                 attrs.push(attr);
             }
         }
+        self.docs = get_docs(attrs);
         Ok(())
     }
 }
@@ -85,6 +81,7 @@ pub fn parser(args: AttributeArgs, mut input: ItemStruct) -> Result<TokenStream>
         &class_attrs.implements,
         &fields,
         args.flags.as_ref(),
+        &class_attrs.docs,
     );
 
     Ok(quote! {
@@ -225,6 +222,7 @@ pub fn parse_attribute(attr: &Attribute) -> Result<Option<ParsedAttribute>> {
 }
 
 /// Generates an implementation of `RegisteredClass` for struct `ident`.
+#[allow(clippy::too_many_arguments)]
 fn generate_registered_class_impl(
     ident: &syn::Ident,
     class_name: Option<&str>,
@@ -233,6 +231,7 @@ fn generate_registered_class_impl(
     implements: &[syn::Expr],
     fields: &[Property],
     flags: Option<&syn::Expr>,
+    docs: &[String],
 ) -> TokenStream {
     let ident_str = ident.to_string();
     let class_name = match class_name {
@@ -241,17 +240,36 @@ fn generate_registered_class_impl(
     };
     let modifier = modifier.option_tokens();
     let extends = extends.option_tokens();
+
     let fields = fields.iter().map(|prop| {
         let name = prop.name();
         let ident = prop.ident;
+        let flags = prop
+            .attr
+            .flags
+            .as_ref()
+            .map(|flags| flags.to_token_stream())
+            .unwrap_or(quote! { ::ext_php_rs::flags::PropertyFlags::Public });
+        let docs = &prop.docs;
+
         quote! {
-            (#name, ::ext_php_rs::props::Property::field(|this: &mut Self| &mut this.#ident))
+            (#name, ::ext_php_rs::internal::property::PropertyInfo {
+                prop: ::ext_php_rs::props::Property::field(|this: &mut Self| &mut this.#ident),
+                flags: #flags,
+                docs: &[#(#docs,)*]
+            })
         }
     });
+
     let flags = match flags {
         Some(flags) => flags.to_token_stream(),
         None => quote! { ::ext_php_rs::flags::ClassFlags::empty() }.to_token_stream(),
     };
+
+    let docs = quote! {
+        #(#docs)*
+    };
+
     quote! {
         impl ::ext_php_rs::class::RegisteredClass for #ident {
             const CLASS_NAME: &'static str = #class_name;
@@ -265,6 +283,9 @@ fn generate_registered_class_impl(
                 #(#implements,)*
             ];
             const FLAGS: ::ext_php_rs::flags::ClassFlags = #flags;
+            const DOC_COMMENTS: &'static [&'static str] = &[
+                #docs
+            ];
 
             #[inline]
             fn get_metadata() -> &'static ::ext_php_rs::class::ClassMetadata<Self> {
@@ -274,7 +295,7 @@ fn generate_registered_class_impl(
             }
 
             fn get_properties<'a>() -> ::std::collections::HashMap<
-                &'static str, ::ext_php_rs::props::Property<'a, Self>
+                &'static str, ::ext_php_rs::internal::property::PropertyInfo<'a, Self>
             > {
                 use ::std::iter::FromIterator;
                 ::std::collections::HashMap::from_iter([
@@ -297,7 +318,7 @@ fn generate_registered_class_impl(
             }
 
             #[inline]
-            fn constants() -> &'static [(&'static str, &'static dyn ::ext_php_rs::convert::IntoZvalDyn)] {
+            fn constants() -> &'static [(&'static str, &'static dyn ::ext_php_rs::convert::IntoZvalDyn, &'static [&'static str])] {
                 use ::ext_php_rs::internal::class::PhpClassImpl;
                 ::ext_php_rs::internal::class::PhpClassImplCollector::<Self>::default().get_constants()
             }

crates/macros/src/constant.rs

@@ -0,0 +1,31 @@
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::ItemConst;
+
+use crate::helpers::get_docs;
+use crate::prelude::*;
+
+const INTERNAL_CONST_DOC_PREFIX: &str = "_internal_const_docs_";
+
+pub fn parser(item: ItemConst) -> TokenStream {
+    let docs = get_docs(&item.attrs);
+    let docs_ident = format_ident!("{INTERNAL_CONST_DOC_PREFIX}{}", item.ident);
+
+    quote! {
+        #item
+        #[allow(non_upper_case_globals)]
+        const #docs_ident: &[&str] = &[#(#docs),*];
+    }
+}
+
+pub fn wrap(input: syn::Path) -> Result<TokenStream> {
+    let Some(const_name) = input.get_ident().map(|i| i.to_string()) else {
+        bail!(input => "Pass a PHP const into `wrap_constant!()`.");
+    };
+    let doc_const = format_ident!("{INTERNAL_CONST_DOC_PREFIX}{const_name}");
+
+    Ok(quote! {
+        (#const_name, #input, #doc_const)
+
+    })
+}

crates/macros/src/function.rs

@@ -16,11 +16,9 @@ pub fn wrap(input: syn::Path) -> Result<TokenStream> {
         bail!(input => "Pass a PHP function name into `wrap_function!()`.");
     };
     let builder_func = format_ident!("_internal_{func_name}");
-    let err = format!("Failed to build function `{}`.", func_name);
 
     Ok(quote! {{
         (<#builder_func as ::ext_php_rs::internal::function::PhpFunction>::FUNCTION_ENTRY)()
-            .expect(#err)
     }})
 }
 
@@ -165,7 +163,7 @@ impl<'a> Function<'a> {
                 .variadic()
             }
         });
-        let output = self.output.as_ref().map(|output| {
+        let returns = self.output.as_ref().map(|output| {
             quote! {
                 .returns(
                     <#output as ::ext_php_rs::convert::IntoZval>::TYPE,
@@ -232,6 +230,15 @@ impl<'a> Function<'a> {
             }
         };
 
+        let docs = if !self.docs.is_empty() {
+            let docs = &self.docs;
+            quote! {
+                .docs(&[#(#docs),*])
+            }
+        } else {
+            quote! {}
+        };
+
         Ok(quote! {
             ::ext_php_rs::builders::FunctionBuilder::new(#name, {
                 ::ext_php_rs::zend_fastcall! {
@@ -258,7 +265,8 @@ impl<'a> Function<'a> {
             .not_required()
             #(.arg(#not_required_args))*
             #variadic
-            #output
+            #returns
+            #docs
         })
     }
 
@@ -273,13 +281,10 @@ impl<'a> Function<'a> {
             struct #internal_ident;
 
             impl ::ext_php_rs::internal::function::PhpFunction for #internal_ident {
-                const FUNCTION_ENTRY: fn() -> ::ext_php_rs::error::Result<
-                    ::ext_php_rs::zend::FunctionEntry
-                > = {
-                    fn entry() -> ::ext_php_rs::error::Result<
-                        ::ext_php_rs::zend::FunctionEntry
-                    > {
-                        #builder.build()
+                const FUNCTION_ENTRY: fn() -> ::ext_php_rs::builders::FunctionBuilder<'static> = {
+                    fn entry() -> ::ext_php_rs::builders::FunctionBuilder<'static>
+                    {
+                        #builder
                     }
                     entry
                 };
@@ -355,14 +360,14 @@ impl<'a> Function<'a> {
 
 #[derive(Debug)]
 pub struct ReceiverArg {
-    pub mutable: bool,
+    pub _mutable: bool,
     pub span: Span,
 }
 
 #[derive(Debug)]
 pub struct TypedArg<'a> {
     pub name: &'a Ident,
-    pub ty: Box<Type>,
+    pub ty: Type,
     pub nullable: bool,
     pub default: Option<Lit>,
     pub as_ref: bool,
@@ -393,7 +398,7 @@ impl<'a> Args<'a> {
                         bail!(receiver => "Too many receivers specified.")
                     }
                     result.receiver.replace(ReceiverArg {
-                        mutable: receiver.mutability.is_some(),
+                        _mutable: receiver.mutability.is_some(),
                         span: receiver.span(),
                     });
                 }
@@ -421,8 +426,8 @@ impl<'a> Args<'a> {
         Ok(result)
     }
 
-    fn parse_typed(ty: &Box<Type>) -> (bool, bool, Box<Type>) {
-        match ty.as_ref() {
+    fn parse_typed(ty: &Type) -> (bool, bool, Type) {
+        match ty {
             Type::Reference(ref_) => {
                 let as_ref = ref_.mutability.is_some();
                 match ref_.elem.as_ref() {
@@ -448,7 +453,7 @@ impl<'a> Args<'a> {
                             args.args
                                 .iter()
                                 .find(|arg| matches!(arg, GenericArgument::Type(_)))
-                                .map(|ga| match ga {
+                                .and_then(|ga| match ga {
                                     GenericArgument::Type(ty) => Some(match ty {
                                         Type::Reference(r) => {
                                             let mut new_ref = r.clone();
@@ -460,11 +465,9 @@ impl<'a> Args<'a> {
                                     }),
                                     _ => None,
                                 })
-                                .flatten()
                         } else {
                             None
                         }
-                        .map(|ty| Box::new(ty))
                     })
                     .unwrap_or_else(|| ty.clone());
                 (false, as_ref, ty.clone())
@@ -503,10 +506,10 @@ impl<'a> Args<'a> {
     }
 }
 
-impl<'a> TypedArg<'a> {
+impl TypedArg<'_> {
     /// Returns a 'clean type' with the lifetimes removed. This allows the type
     /// to be used outside of the original function context.
-    fn clean_ty(&self) -> Box<Type> {
+    fn clean_ty(&self) -> Type {
         let mut ty = self.ty.clone();
         ty.drop_lifetimes();
         ty
@@ -532,17 +535,18 @@ impl<'a> TypedArg<'a> {
         } else {
             None
         };
-        let default = self.default.as_ref().map(|_| {
+        let default = self.default.as_ref().map(|val| {
+            let val = val.to_token_stream().to_string();
             quote! {
-                .default()
+                .default(#val)
             }
         });
         let as_ref = if self.as_ref {
             Some(quote! { .as_ref() })
         } else {
             None
         };
-        let variadic = self.variadic.then(|| quote! { .ir_variadic() });
+        let variadic = self.variadic.then(|| quote! { .is_variadic() });
         Ok(quote! {
             ::ext_php_rs::args::Arg::new(#name, <#ty as ::ext_php_rs::convert::FromZvalMut>::TYPE)
                 #null
@@ -595,7 +599,7 @@ pub fn type_is_nullable(ty: &Type, has_default: bool) -> Result<bool> {
                     .path
                     .segments
                     .iter()
-                    .last()
+                    .next_back()
                     .map(|seg| seg.ident == "Option")
                     .unwrap_or(false)
         }

crates/macros/src/impl_.rs

@@ -342,8 +342,9 @@ impl<'a> ParsedImpl<'a> {
         let constants = self.constants.iter().map(|c| {
             let name = &c.name;
             let ident = c.ident;
+            let docs = &c.docs;
             quote! {
-                (#name, &#path::#ident)
+                (#name, &#path::#ident, &[#(#docs),*])
             }
         });
 
@@ -365,7 +366,7 @@ impl<'a> ParsedImpl<'a> {
                     #constructor
                 }
 
-                fn get_constants(self) -> &'static [(&'static str, &'static dyn ::ext_php_rs::convert::IntoZvalDyn)] {
+                fn get_constants(self) -> &'static [(&'static str, &'static dyn ::ext_php_rs::convert::IntoZvalDyn, &'static [&'static str])] {
                     &[#(#constants),*]
                 }
             }