synca 0.5.0

Write asynchronous code, and synca will create a synchronous version.
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

# About

SyncA is a framework for creating crates with both synchronous and asynchronous versions.

# Docs

[SyncA Book](https://synca.sgr-team.dev)

# Motivation

When we write a library, we cannot control the environment in which our code will be used.

Often this leads to the fact that there is only a synchronous version, or two different crates.
If the problems of the first solution are obvious, then the second leads to a violation of the 
[DRY principle](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).

SyncA solves this problem by hiding the asynchronous implementation behind a feature.

# Concept

One macro for everything.

The macro synca::synca generates 2 versions of code: async with attribute #[cfg(feature)] and 
sync with attribute #[cfg(not(feature))].

# Full example

```rust
/// # synca
/// 
/// The macro will create 2 versions of the my_mod
/// With the asynchrony feature enabled - asynchronous version, 
/// without it - synchronous.
#[synca::synca(feature = "async")]
mod my_mod { }

/// # Functions
/// 
/// The macro turns asynchronous functions into synchronous 
/// implementations - removing all the .await calls
#[synca::synca(feature = "async")]
impl MyStruct {
  pub async fn first_name(&mut self) -> String {
    let row = self.client.query_one("SQL", &[]).await.unwrap();

    row.get("name")
  }
}

/// # Types
/// 
/// synca supports type substitution 
/// The synchronous version will use type postgres::Client
#[synca::synca(
  feature = "async",
  tokio_postgres::Client => postgres::Client
)]
struct MyStruct {
  client: tokio_postgres::Client
} 

/// # Tests
/// 
/// synca support attributes substitution too.
/// This allows you to test not only the asynchronous version, but also the synchronous one
#[synca::synca(
  feature = "async",
  tokio_postgres::Client => postgres::Client,
  #[tokio::test] => #[test]
)]
mod tests {
  #[tokio::test]
  pub async fn my_test() {

  }
}

/// # Traits
///
/// synca also knows how to work with traits
#[synca::synca(
  feature = "async",
  tokio_postgres::Client => postgres::Client,
)]
pub trait MyTrait { 
  async fn get_name(client: &mut tokio_postgres::Client);
}

/// # Docs
/// 
/// synca also contains a documentation processor that allows to generate 
/// different documentation for the synchronous and asynchronous versions
/// 
/// [synca::sync]
/// It's sync doc
/// [/synca::sync]
/// [synca::async]
/// It's async doc
/// [/synca::async]
/// 
/// # Match
/// 
/// You can also use "synca::match" to replace part of a string.
/// 
/// Arguments 
/// - [synca::match]tokio_postgres|postgres[/synca::match]::Client - postgres client
#[synca::synca(
  feature = "async",
  tokio_postgres::Client => postgres::Client,
)]
pub async fn my_fn(client: &mut tokio_postgres::Client) { }

/// # Virtual attributes
/// 
/// - synca::ignore - ignore in code fold
/// - synca::sync_only - the code will only be available in the synchronous version
/// - synca::async_only - the code will only be available in the asynchronous version
#[synca::synca(
  feature = "async",
  tokio_postgres::Client => postgres::Client,
  #[tokio::test] => #[test],
)]
mod my_mod {
  #[tokio::test]
  async fn my_test() { 
    #[synca::ignore]
    assert_eq!(format!(".aw{}", "ait"), ".await");
  }

  #[test]
  #[synca::sync_only]
  fn sync_test() { 
  }

  #[test]
  #[synca::async_only]
  fn async_test() { 
  }
}
```