newtypedecl 0.0.1

declarative newtype macro
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

* `fn name(params)`
* `fn name`
* `fn name(&t vs t)`
* `fn name`







The macro generates a lot of code for you. This code generation can be customized by the user
with an abbreviated syntax.

The newtype macro can generate 

`!default fn`
`!default impl`



### Functions and Methods

A `impl` block for the defined struct is generated. This contains automatically generated
functions. The user can override these functions by providing a custom implementation,
suppress the generation of these functions or implement custom functions.


### Traits

A set of traits will be automatically implemented. The user can enable or suppress these
implementations or provide custom implementations. Implementation of other traits is also
possible and using an abbreviated syntax for general cases.

// impl<T: ?Sized> AsRef<T> for Example
// where
//     Inner: AsRef<T>,
// {
//     fn as_ref(&self) -> &T {
//         self.0.as_ref()
//     }
// }

## DWIM

While the macro aims for generating code in a convenient way, it would only do what a
programmer does. The generated newtype struct is easy to extend by conventional `impl` and
`impl Trait` blocks. Some defaults are opinionated but can be overridden by the user.

# Example

The simplest case lets you use it like this:

```rust,ignore
use newtypedecl::newtype;

newtype! {
    pub struct Example(String)
}
```

This will generate the following code for you:

```rust,ignore
#[repr(transparent)]
pub struct Example(String);

impl Example {
    pub fn new(s: String) -> Self {
        Self(s)
    }

    pub fn into_inner(t: Self) -> String {
        t.0
    }
}

<!-- impl AsRef<String> for Example {
 !--     fn as_ref(&self) -> &str {
 !--         self.0.as_ref()
 !--     }
 !-- }
 !-- 
 !-- impl AsMut<str> for Example {
 !--     fn as_mut(&mut self) -> &mut str {
 !--         self.0.as_mut()
 !--     }
 !-- }
 !-- 
 !-- impl Borrow<str> for Example {
 !--     fn borrow(&self) -> &str {
 !--         self.0.borrow()
 !--     }
 !-- }
 !-- 
 !-- impl BorrowMut<str> for Example {
 !--     fn borrow_mut(&mut self) -> &mut str {
 !--         self.0.borrow_mut()
 !--     }
 !-- }
 !-- 
 !-- impl From<String> for Example {
 !--     fn from(s: String) -> Self {
 !--         Self(s)
 !--     }
 !-- } -->
```

A more complex example is:

```rust,ignore
#[macro_use]
use newtypedecl::newtype;

newtype! {
    // Attributes are passed to the generated struct
    /// This includes doc comments
    #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Example(String) {
        // provide a `new` function that overrides the automatic implementation
        // PLANNED: pub const fn new() -> Self {Self(String::new())}

        // suppress the generation of the `take` function
        // PLANNED: !fn take;
        
        // generates a method `push_str` that forwards to `String::push_str()`
        // PLANNED: pub fn push_str(&self, s: &str);
        
        // implement a custom method
        /* PLANNED: pub fn hello(&self) {
            println!("Hello {}!", self.0);
        } */
        
        // suppress the automatic implementation of the `From` trait
        // PLANNED: !impl From;
    }
}
```
The code generator tries to make educated guesses (heuristics) by looking at the newtype
definition. For example depending on if the type is `Clone`, `Copy` or `Default` and if the
`From` trait is implemented the `fn new` with either take no parameter (Default + From
defined), or a parameter by value (no Clone and no Copy) or reference (Clone or Copy).
These heuristics are not perfect, for example the Inner type




A initial implementaiton of the product syntax was done by [Lukas Kalbertodt][lukas] in
[issue #1][issue1] and [PR #2][pr2]. The current implementation is a rewrite of the original
code. The original implementation was not compatible with the newtype completion engine and
had some other issues. The new implementation is more robust and has a better error reporting.