stub-macro 0.3.0

stub!() is a better version of todo!() that can be assigned to a variable
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

<!-- DO NOT EDIT -->
<!-- This file is automatically generated by README.ts. -->
<!-- Edit README.ts if you want to make changes. -->

# stub!() - a better todo!()

[![Build](https://github.com/DenisGorbachev/stub-macro/actions/workflows/ci.yml/badge.svg)](https://github.com/DenisGorbachev/stub-macro)
[![Documentation](https://docs.rs/stub-macro/badge.svg)](https://docs.rs/stub-macro)

<!-- crate documentation start -->
`stub!()` can be assigned to a variable:

```rust
let username = stub!(String);
```

This allows you to specify just type of the variable and continue working on other code, then come back later and specify its value.

## Examples

```rust
fn assign() {
    // you can assign stub!() to a variable
    let username = stub!(String);
    println!("Hello {username}")
}

fn return_position() -> String {
    // you can use stub!() like todo!() in return position
    stub!()
}

fn infer_type() {
    // you can let the compiler automatically infer the type
    let status = stub!();
    if status { println!("Success") }
}

fn explicit_type() {
    // you can specify the type explicitly
    let status: bool = stub!();
    if status { println!("Success") }
}

fn custom_message() {
    // you can add a custom message
    let status: bool = stub!("Send a request to GitHub");
    if status { println!("Success") }
}

fn impl_example() -> impl core::fmt::Display {
    // you can use stub!() in return position even with `impl Trait` return type
    // note: `impl Trait` must be written as `impl dyn Trait` due to `macro_rules!` limitation
    stub!(impl dyn core::fmt::Display)
}

fn iter_example() -> impl Iterator<Item = u32> {
    // use stub_iter!() when the return type is an iterator
    stub_iter!()
}

#[cfg(feature = "futures")]
fn stream_example() -> impl futures_core::stream::Stream<Item = u32> {
    // use stub_stream!() when the return type is a stream
    stub_stream!()
}

fn explicit_type_with_message_example() -> u32 {
    // you can add
    stub!(u32, "Assigned to: {}", "John")
}

fn explicit_type_example() -> u32 {
    stub!(u32)
}

fn implicit_type_with_message_example() -> u32 {
    stub!("Assigned to: {}", "John")
}

fn implicit_type_example() -> u32 {
    stub!()
}
```

## Behavior

When a stub is invoked, it will panic like a `todo!()` macro.
However, unlike a `todo!()` macro, it will not make the subsequent parts of your code unreachable.

If a custom message is provided, it will be included in the panic message.

## Notes

- `stub!()` macro is intended for use during development and should be replaced with actual implementations before production use.
- When using `impl Trait` in return position, you must use `impl dyn Trait` in the macro invocation due to a limitation in `macro_rules!`
- `stub!(impl dyn Trait)` requires the `alloc` feature.
- `stub_stream!()` requires the `futures` feature.

<!-- crate documentation end -->

## Installation

```shell
cargo add stub-macro
```

## Gratitude

Like the project? [⭐ Star this repo](https://github.com/DenisGorbachev/stub-macro) on GitHub!

## License

[Apache-2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, shall be licensed as above, without any additional terms or conditions.