improve argument and returntype api

brettmc · brettmc · commit 4ed6ecf8fb85 · 2025-03-30T10:12:18.000+11:00
use the Builder pattern to create an Argument or ReturnType, using
methods to change the defaults. A default is to be required, pass-by-val, not-nullable
diff --git a/examples/complex/src/lib.rs b/examples/complex/src/lib.rs
@@ -58,7 +58,7 @@ pub fn get_module() -> Module {
     // register functions
     module
         .add_function("complex_say_hello", say_hello)
-        .argument(Argument::by_val("name"));
+        .argument(Argument::new("name"));
     module.add_function("complex_throw_exception", throw_exception);
     module.add_function("complex_get_all_ini", |_: &mut [ZVal]| {
         let mut arr = ZArray::new();
@@ -91,7 +91,7 @@ pub fn get_module() -> Module {
                 Ok(())
             },
         )
-        .argument(Argument::by_val("foo"));
+        .argument(Argument::new("foo"));
     module.add_class(foo_class);
 
     // register extra info
diff --git a/examples/hello/src/lib.rs b/examples/hello/src/lib.rs
@@ -36,7 +36,7 @@ pub fn get_module() -> Module {
     // Register function `say_hello`, with one argument `name`.
     module
         .add_function("say_hello", say_hello)
-        .argument(Argument::by_val("name"));
+        .argument(Argument::new("name"));
 
     module
 }
diff --git a/examples/http-client/src/client.rs b/examples/http-client/src/client.rs
@@ -39,7 +39,7 @@ pub fn make_client_builder_class(client_class: ClientClass) -> ClassEntity<Clien
             *state = builder.timeout(Duration::from_millis(ms as u64));
             Ok::<_, phper::Error>(this.to_ref_owned())
         })
-        .argument(Argument::by_val("ms"));
+        .argument(Argument::new("ms"));
 
     // Inner call the `ClientBuilder::cookie_store`.
     class
@@ -50,7 +50,7 @@ pub fn make_client_builder_class(client_class: ClientClass) -> ClassEntity<Clien
             *state = builder.cookie_store(enable);
             Ok::<_, phper::Error>(this.to_ref_owned())
         })
-        .argument(Argument::by_val("enable"));
+        .argument(Argument::new("enable"));
 
     // Inner call the `ClientBuilder::build`, and wrap the result `Client` in
     // Object.
@@ -85,7 +85,7 @@ pub fn make_client_class(
             *object.as_mut_state() = Some(request_builder);
             Ok::<_, phper::Error>(object)
         })
-        .argument(Argument::by_val("url"));
+        .argument(Argument::new("url"));
 
     class
         .add_method("post", Visibility::Public, move |this, arguments| {
@@ -96,7 +96,7 @@ pub fn make_client_class(
             *object.as_mut_state() = Some(request_builder);
             Ok::<_, phper::Error>(object)
         })
-        .argument(Argument::by_val("url"));
+        .argument(Argument::new("url"));
 
     class
 }
diff --git a/examples/http-server/src/response.rs b/examples/http-server/src/response.rs
@@ -43,8 +43,8 @@ pub fn make_response_class() -> ClassEntity<Response<Body>> {
 
             Ok::<_, phper::Error>(())
         })
-        .argument(Argument::by_val("name"))
-        .argument(Argument::by_val("value"));
+        .argument(Argument::new("name"))
+        .argument(Argument::new("value"));
 
     // Register the end method with public visibility, accept `data` parameters.
     class
@@ -54,7 +54,7 @@ pub fn make_response_class() -> ClassEntity<Response<Body>> {
             *response.body_mut() = arguments[0].expect_z_str()?.to_bytes().to_vec().into();
             Ok::<_, phper::Error>(())
         })
-        .argument(Argument::by_val("data"));
+        .argument(Argument::new("data"));
 
     class
 }
diff --git a/examples/http-server/src/server.rs b/examples/http-server/src/server.rs
@@ -67,7 +67,7 @@ pub fn make_server_class(
 
             Ok::<_, phper::Error>(())
         })
-        .arguments([Argument::by_val("host"), Argument::by_val("port")]);
+        .arguments([Argument::new("host"), Argument::new("port")]);
 
     // Register the onRequest method, with public visibility, insert the handle into
     // global ON_REQUEST_HANDLERS map.
@@ -80,7 +80,7 @@ pub fn make_server_class(
             });
             Ok::<_, phper::Error>(())
         })
-        .argument(Argument::by_val("handle"));
+        .argument(Argument::new("handle"));
 
     // Register the start method, with public visibility, this method will start and
     // http server, listen on the addr, and block.
diff --git a/examples/logging/src/lib.rs b/examples/logging/src/lib.rs
@@ -32,7 +32,7 @@ pub fn get_module() -> Module {
             echo!("Hello, {}!", message);
             Ok(())
         })
-        .argument(Argument::by_val("message"));
+        .argument(Argument::new("message"));
 
     module
         .add_function("log_notice", |params: &mut [ZVal]| -> phper::Result<()> {
@@ -45,7 +45,7 @@ pub fn get_module() -> Module {
             notice!("Something happened: {}", message);
             Ok(())
         })
-        .argument(Argument::by_val("message"));
+        .argument(Argument::new("message"));
 
     module
         .add_function("log_warning", |params: &mut [ZVal]| -> phper::Result<()> {
@@ -58,7 +58,7 @@ pub fn get_module() -> Module {
             warning!("Something warning: {}", message);
             Ok(())
         })
-        .argument(Argument::by_val("message"));
+        .argument(Argument::new("message"));
 
     module
         .add_function("log_error", |params: &mut [ZVal]| -> phper::Result<()> {
@@ -70,7 +70,7 @@ pub fn get_module() -> Module {
             error!("Something gone failed: {}", message);
             Ok(())
         })
-        .argument(Argument::by_val("message"));
+        .argument(Argument::new("message"));
 
     module
         .add_function(
@@ -85,7 +85,7 @@ pub fn get_module() -> Module {
                 Ok(())
             },
         )
-        .argument(Argument::by_val("message"));
+        .argument(Argument::new("message"));
 
     module
 }
diff --git a/phper-doc/doc/_02_quick_start/_01_write_your_first_extension/index.md b/phper-doc/doc/_02_quick_start/_01_write_your_first_extension/index.md
@@ -79,7 +79,7 @@ Full example is <https://github.com/phper-framework/phper/tree/master/examples/h
        );
    
        // Register function `say_hello`, with one argument `name`.
-       module.add_function("say_hello", say_hello).argument(Argument::by_val("name"));
+       module.add_function("say_hello", say_hello).argument(Argument::new("name"));
    
        module
    }
diff --git a/phper-doc/doc/_02_quick_start/_02_write_a_simple_http_client/index.md b/phper-doc/doc/_02_quick_start/_02_write_a_simple_http_client/index.md
@@ -211,7 +211,7 @@ Now let's begin to finish the logic.
                *state = builder.timeout(Duration::from_millis(ms as u64));
                Ok::<_, phper::Error>(this.to_ref_owned())
            })
-           .argument(Argument::by_val("ms"));
+           .argument(Argument::new("ms"));
    
        // Inner call the `ClientBuilder::cookie_store`.
        class
@@ -222,7 +222,7 @@ Now let's begin to finish the logic.
                *state = builder.cookie_store(enable);
                Ok::<_, phper::Error>(this.to_ref_owned())
            })
-           .argument(Argument::by_val("enable"));
+           .argument(Argument::new("enable"));
    
        // Inner call the `ClientBuilder::build`, and wrap the result `Client` in
        // Object.
diff --git a/phper-doc/doc/_06_module/_02_register_functions/index.md b/phper-doc/doc/_06_module/_02_register_functions/index.md
@@ -18,7 +18,7 @@ pub fn get_module() -> Module {
         let name = arguments[0].expect_z_str()?.to_str()?;
         echo!("Hello, {}!\n", name);
         Ok(())
-    }).argument(Argument::by_val("name"));
+    }).argument(Argument::new("name"));
 
     module
 }
@@ -71,7 +71,7 @@ pub fn get_module() -> Module {
         let count = arguments[0].expect_mut_z_ref()?;
         *count.val_mut().expect_mut_long()? += 100;
         Ok(())
-    }).argument(Argument::by_ref("count"));
+    }).argument(Argument::new("count").by_ref());
 
     module
 }
@@ -101,9 +101,9 @@ pub fn get_module() -> Module {
     module.add_function("my_function", |_| -> phper::Result<()> {
         Ok(())
     })
-    .argument(Argument::by_val("a_class").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))).allow_null())
-    .argument(Argument::by_val("name").with_type_hint(ArgumentTypeHint::String).with_default_value("'my_default'"))
-    .argument(Argument::by_val("optional_bool").with_type_hint(ArgumentTypeHint::Bool).optional());
+    .argument(Argument::new("a_class").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))).allow_null())
+    .argument(Argument::new("name").with_type_hint(ArgumentTypeHint::String).with_default_value("'my_default'"))
+    .argument(Argument::new("optional_bool").with_type_hint(ArgumentTypeHint::Bool).optional());
 
     module
 }
diff --git a/phper-doc/doc/_06_module/_06_register_class/index.md b/phper-doc/doc/_06_module/_06_register_class/index.md
@@ -99,7 +99,7 @@ foo.add_static_method(
         let name = arguments[0].expect_z_str()?.to_str()?;
         Ok::<_, phper::Error>(format!("Hello, {}!\n", name))
     },
-).argument(Argument::by_val("name"));
+).argument(Argument::new("name"));
 ```
 
 ## Argument and return type modifiers
@@ -119,9 +119,9 @@ foo.add_method(
         Ok(())
     },
 )
-.argument(Argument::by_val("a_string").with_type_hint(ArgumentTypeHint::String))
-.argument(Argument::by_val("an_interface").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))))
-.return_type(ReturnType::by_val(ReturnTypeHint::Bool).allow_null());
+.argument(Argument::new("a_string").with_type_hint(ArgumentTypeHint::String))
+.argument(Argument::new("an_interface").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))))
+.return_type(ReturnType::new(ReturnTypeHint::Bool).allow_null());
 ```
 
 ## Add constants
@@ -170,8 +170,8 @@ class.add_method(
         Ok::<_, phper::Error>(())
     },
 )
-.argument(Argument::by_val("key"))
-.argument(Argument::by_val("value"));
+.argument(Argument::new("key"))
+.argument(Argument::new("value"));
 ```
 
 Equivalent to the following PHP code (hides the implementation details):
diff --git a/phper-doc/doc/_06_module/_07_register_interface/index.md b/phper-doc/doc/_06_module/_07_register_interface/index.md
@@ -68,7 +68,7 @@ use phper::objects::StateObj;
 use phper::values::ZVal;
 
 let mut foo = InterfaceEntity::new("Foo");
-foo.add_method("doSomethings").argument(Argument::by_val("name"));
+foo.add_method("doSomethings").argument(Argument::new("name"));
 ```
 
 Note that abstract has no method body, so you don't need to add the handler to the method.
diff --git a/phper/src/functions.rs b/phper/src/functions.rs
@@ -518,8 +518,8 @@ pub struct Argument {
 }
 
 impl Argument {
-    /// Indicate the argument is pass by value.
-    pub fn by_val(name: impl Into<String>) -> Self {
+    /// Create a new argument with default values
+    pub fn new(name: impl Into<String>) -> Self {
         let name = ensure_end_with_zero(name);
         Self {
             name,
@@ -531,43 +531,10 @@ impl Argument {
         }
     }
 
-    /// Indicate the argument is pass by reference.
-    pub fn by_ref(name: impl Into<String>) -> Self {
-        let name = ensure_end_with_zero(name);
-        Self {
-            name,
-            type_hint: None,
-            pass_by_ref: true,
-            required: true,
-            nullable: false,
-            default_value: None,
-        }
-    }
-
-    /// Indicate the argument is pass by value and is optional.
-    pub fn by_val_optional(name: impl Into<String>) -> Self {
-        let name = ensure_end_with_zero(name);
-        Self {
-            name,
-            type_hint: None,
-            pass_by_ref: false,
-            required: false,
-            nullable: false,
-            default_value: None,
-        }
-    }
-
-    /// Indicate the argument is pass by reference nad is optional.
-    pub fn by_ref_optional(name: impl Into<String>) -> Self {
-        let name = ensure_end_with_zero(name);
-        Self {
-            name,
-            type_hint: None,
-            pass_by_ref: true,
-            required: false,
-            nullable: false,
-            default_value: None,
-        }
+    /// Indicate the argument is passed by reference
+    pub fn by_ref(mut self) -> Self {
+        self.pass_by_ref = true;
+        self
     }
 
     /// Add a type-hint to the argument
@@ -582,13 +549,7 @@ impl Argument {
         self
     }
 
-    /// Argument is required (also see by_*<ref|val>)
-    pub fn required(mut self) -> Self {
-        self.required = true;
-        self
-    }
-
-    /// Argument is optional (also see by_<ref|val>_optional)
+    /// Argument is optional
     pub fn optional(mut self) -> Self {
         self.required = false;
         self
@@ -614,7 +575,7 @@ pub struct ReturnType {
 impl ReturnType {
     /// Indicate the return type is return by value.
     #[inline]
-    pub fn by_val(type_hint: ReturnTypeHint) -> Self {
+    pub fn new(type_hint: ReturnTypeHint) -> Self {
         Self {
             type_hint,
             ret_by_ref: false,
@@ -624,12 +585,9 @@ impl ReturnType {
 
     /// Indicate the return type is return by reference.
     #[inline]
-    pub fn by_ref(type_hint: ReturnTypeHint) -> Self {
-        Self {
-            type_hint,
-            ret_by_ref: true,
-            allow_null: false,
-        }
+    pub fn by_ref(mut self) -> Self {
+        self.ret_by_ref = true;
+        self
     }
 
     /// Indicate the return type can be null.
@@ -640,6 +598,7 @@ impl ReturnType {
     }
 
     /// Add a type-hint to the return type
+    #[inline]
     pub fn with_type_hint(mut self, type_hint: ReturnTypeHint) -> Self {
         self.type_hint = type_hint;
         self
diff --git a/tests/integration/src/arguments.rs b/tests/integration/src/arguments.rs
diff --git a/tests/integration/src/classes.rs b/tests/integration/src/classes.rs
diff --git a/tests/integration/src/functions.rs b/tests/integration/src/functions.rs
diff --git a/tests/integration/src/objects.rs b/tests/integration/src/objects.rs
diff --git a/tests/integration/src/references.rs b/tests/integration/src/references.rs
diff --git a/tests/integration/src/typehints.rs b/tests/integration/src/typehints.rs

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ pub fn get_module() -> Module {`
`36`	`36`	// Register function `say_hello`, with one argument `name`.
`37`	`37`	`module`
`38`	`38`	`.add_function("say_hello", say_hello)`
`39`		`- .argument(Argument::by_val("name"));`
	`39`	`+ .argument(Argument::new("name"));`
`40`	`40`
`41`	`41`	`module`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -79,7 +79,7 @@ Full example is <https://github.com/phper-framework/phper/tree/master/examples/h`
`79`	`79`	`);`
`80`	`80`
`81`	`81`	// Register function `say_hello`, with one argument `name`.
`82`		`- module.add_function("say_hello", say_hello).argument(Argument::by_val("name"));`
	`82`	`+ module.add_function("say_hello", say_hello).argument(Argument::new("name"));`
`83`	`83`
`84`	`84`	`module`
`85`	`85`	`}`