Implement adding new field with custom expression as value (#10)

* Implement adding new field with custom expression as value

* code refactoring

* update readme and code refactoring

* update doc version reference for crate.io

Author: douggynix

Cargo.lock

@@ -1,12 +1,12 @@
 [package]
 name = "dto_mapper"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["James Douglass Lefruit"]
 description = "A library to create dynamic DTOs (Data Transfer Object) from a structure"
 repository = "https://github.com/douggynix/dto_mapper"
 homepage = "https://github.com/douggynix/dto_mapper"
-documentation = "https://github.com/douggynix/dto_mapper/tree/0.1.3"
+documentation = "https://github.com/douggynix/dto_mapper/tree/0.2.0"
 readme = "README.md"
 license = "Apache-2.0"
 categories = ["data-structures", "web-programming", "rust-patterns"]
@@ -20,10 +20,12 @@ exclude = [
 proc-macro = true
 
 [dependencies]
-proc-macro2 = "1.0.69"
-quote = "1.0.33"
-syn = { version = "2.0.39", features = ["full"] }
+derive_builder = "0.20.0"
+proc-macro2 = "1.0.81"
+quote = "1.0.36"
+syn = { version = "2.0.60", features = ["full"] }
+unstringify = "0.1.4"
 
 [dev-dependencies]
-derive_builder = "0.12.0"
+derive_builder = "0.20.0"
 

Cargo.toml

@@ -28,12 +28,13 @@ If we have to load a 'user' record from a database, we wouldn't want to send all
 This is where DTO Mapper Library comes handy.
 
 # Installation
-**_dto_mapper_** library depends on **_derive_builder_** to implement builder pattern for dto objects resulted from the dto mappers.
+**_dto_mapper_** library depends on **_unstringify_** and **_derive_builder_** which implements builder pattern for dto objects resulted from the dto mappers.
 By default, it generate builder for the dtos. 
 You can use this instruction to install the latest version of **dto_mapper** library to your project
 ```shell
 cargo add derive_builder
 cargo add dto_mapper
+cargo add unstringify
 ```
 And import it to the rust source file you need to use it:
 ```rust
@@ -58,11 +59,23 @@ It takes only those lines below to get this work done. And the conversion are be
     ***/
     #[macro_use]
     extern crate derive_builder;
+    #[allow(unused)]
+    use std::str::FromStr;
+    #[allow(unused)]
+    use unstringify::unstringify;
+
+    fn concat_str(s1: &str, s2: &str) -> String {
+        s1.to_owned() + " " + s2
+    }
 
     #[derive(DtoMapper,Default,Clone)]
     #[mapper( dto="LoginDto"  , map=[ ("username:login",true) , ("password",true)] , derive=(Debug, Clone, PartialEq) )]
     #[mapper( dto="ProfileDto" , ignore=["password"]  , derive=(Debug, Clone, PartialEq) )]
-    #[mapper( dto="PersonDto" , no_builder=true,  map=[ ("firstname",true), ("lastname",true), ("email",false) ]  )] //no_builder=true will not create default builder for that dto
+    //no_builder=true will not create default builder for that dto
+    #[mapper( dto="PersonDto" , no_builder=true,  map=[ ("firstname",true), ("lastname",true), ("email",false) ]  )] 
+    #[mapper( dto="CustomDto" , no_builder=true , map=[ ("email",false) ] , derive=(Debug, Clone) ,
+        new_fields=[( "name: String", "concat_str( self.firstname.as_str(), self.lastname.as_str() )" )]
+    )]
     struct User{
         username: String,
         password: String,
@@ -141,6 +154,43 @@ pub struct PersonDto {
     pub lastname: String,
 } // size = 72 (0x48), align = 0x8
 ```
+
+
+Let's consider building CustomDto by adding a new field called `name` which will be initialized with concatenation of firstname and lastname fields from `User` struct with the help of **dto_mapper**:
+```rust
+        let user = User {
+            firstname: "Dessalines".into(),
+            lastname: "Jean Jacques".into(),
+            ..User::default()
+        };
+
+        println!("{:?}", user);
+        let custom_dto: CustomDto = user.into();
+        println!("{:?}", custom_dto);
+```
+
+Here is how **vscode** prints the code generated by DTO mapper for  **CustomDTO** and the Into Trait implemented by **User** for it
+```Rust
+pub struct CustomDto {
+    pub email: Option<String>,
+    pub name: String,
+}
+
+impl Into<CustomDto> for User {
+    fn into(self) -> CustomDto {
+        CustomDto {
+            email: Some(self.email),
+            name: concat_str(self.firstname.as_str(), self.lastname.as_str()),
+        }
+    }
+}
+```
+
+You can install 'expand' binary crate and use ***cargo expand*** command in order to print out the DTO structures generated as shown above:
+```shell
+cargo install expand
+cargo expand
+```
 # Description of macro derive and attributes for Dto Mapper
 First, DTO Mapper library requires that the source struct implements Default traits as the library relies on it to implement Into Traits for conversion between DTO and Source struct.
 If not it will result in error in your IDE. It is a must to to derive or implement Default for your source struct.
@@ -163,4 +213,9 @@ struct SourceStruct{ }
       if **ignore** is present , then **map** field becomes optional. Except if needed rename destination fields for the dto
     - **derive** : a list of of macro to derive from. `derive=(Debug,Clone)`
     - **no_builder**: a boolean flag to turn on or off builders for the dto. Default value is **_false_**. If the Dto name is "MyDto" , the builder will create a struct named "MyDtoBuilder" that can be used to build "MyDto" struct.
+    - **new_fields** : an array of declaration of new field names to include to the resulted dto structure. `new_fields=[("fieldname:type"), ("initialize_expression") )]`.
+      `fieldname:type` will create a new field with the `fieldname` specified and the `type`. It is not mandatory to rename. you can have `map=[("fieldname",true)]`
+      `initialize_expression` is used an initialize value or expression to use when converting the original structure to the dto. 
+      For instance `new_fields=[("name:String"), ("concat_str(self.firstname,self.lastname)") )]` will create a new field in the dto called `name` which will be initialized with the concatenation of the original struct `firstname` and `lastname` fields. See the example above.
+      **I would strongly suggest to use function  as `initialize_expression` for more complex scenarios in case parsing is failing when writing complex inline expression directly. This will reduce code complexity!!**
 

README.md

@@ -0,0 +1,39 @@
+use derive_builder::Builder;
+use dto_mapper::DtoMapper;
+#[allow(unused)]
+use std::str::FromStr;
+#[allow(unused)]
+use unstringify::unstringify;
+
+fn concat_str(s1: &str, s2: &str) -> String {
+    s1.to_owned() + " " + s2
+}
+
+#[derive(DtoMapper, Debug, Default, Clone)]
+#[mapper( dto="LoginDto"  , map=[ ("username:login",true) , ("password",true)] , derive=(Debug, Clone, PartialEq) )]
+#[mapper( dto="ProfileDto" , ignore=["password"]  , derive=(Debug, Clone, PartialEq) )]
+#[mapper( dto="PersonDto" , no_builder=true , map=[ ("firstname",true), ("lastname",true), ("email",false) ]  )]
+#[mapper( dto="CustomDto" , no_builder=true , map=[ ("email",false) ] , derive=(Debug, Clone) ,
+new_fields=[( "name: String", "concat_str( self.firstname.as_str(), self.lastname.as_str() )" )]
+)]
+struct User {
+    username: String,
+    password: String,
+    email: String,
+    firstname: String,
+    middle_name: Option<String>,
+    lastname: String,
+    age: u8,
+}
+
+fn main() {
+    let user = User {
+        firstname: "Dessalines".into(),
+        lastname: "Jean Jacques".into(),
+        ..User::default()
+    };
+
+    println!("{:?}", user);
+    let custom_dto: CustomDto = user.into();
+    println!("{:?}", custom_dto);
+}