Skip to content

Commit 86a21cf

Browse files
denisandroiddenisandroid
committed
feat: improve documentation, rework examples, add more descriptions
1 parent 0ae3fab commit 86a21cf

File tree

9 files changed

+136
-142
lines changed

9 files changed

+136
-142
lines changed

‎Cargo.toml‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,23 @@ repository = "https://github.com/clucompany/include_tt.git"
77
license = "MIT OR Apache-2.0"
88
readme = "README.md"
99

10-
description = "Macro for embedding (trees, strings, arrays) into macro trees directly from files."
11-
keywords = ["procedural-macros", "macro", "code-generation", "code-transformation", "clucompany"]
12-
categories = ["development-tools", "development-tools::build-utils"]
10+
description = "Macros for ultra-flexible injection of compiler trees, literals, or binary data into Rust syntax trees from external sources."
11+
keywords = [
12+
"procedural-macros",
13+
"macro",
14+
"codegen",
15+
"syntax-injection",
16+
"tt-injection",
17+
"clucompany"
18+
]
19+
20+
categories = [
21+
"development-tools",
22+
"development-tools::build-utils",
23+
"development-tools::procedural-macro",
24+
"code-generation",
25+
"parsing"
26+
]
1327

1428
[features]
1529
default = [ ]

‎README.md‎

Lines changed: 10 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<b>[include_tt]</b>
44

5-
(Macro for embedding (trees, strings, arrays) into macro trees directly from files.)
5+
(Macros for ultra-flexible injection of compiler trees, literals, or binary data into Rust syntax trees from external sources.)
66
</br></br>
77

88
<div id="badges">
@@ -51,46 +51,19 @@ use include_tt::inject;
5151
```rust
5252
use include_tt::inject;
5353
use std::fmt::Write;
54+
fn main() {
55+
let mut buf = String::new();
5456

55-
// Example demonstrating the usage of inject! macro for embedding content from files.
56-
{
57-
// Embedding trees from a file in an arbitrary place of other macros.
58-
let a = 10;
59-
let b = 20;
60-
let mut end_str = String::new();
61-
62-
// Using inject! to embed content into a macro.
6357
inject! {
64-
let _e = write!(
65-
&mut end_str,
66-
67-
"arg1: {}, arg2: {}",
68-
#include!("./for_examples/full.tt") // this file contains `a, b`.
69-
);
58+
write!(
59+
&mut buf,
60+
"Welcome, {}. Your score is {}.",
61+
#tt("examples/name.tt"), // `"Ferris"`
62+
#tt("examples/" "score" ".tt") // `100500`
63+
).unwrap();
7064
}
71-
72-
// Asserting the result matches the expected output.
73-
assert_eq!(end_str, "arg1: 10, arg2: 20");
74-
}
7565

76-
{
77-
// Loading a string from "full.tt" using inject! macro.
78-
let str = inject!(
79-
#str("./for_examples/full.tt") // this file contains `a, b`.
80-
);
81-
82-
// Asserting the result matches the expected output.
83-
assert_eq!(str, "a, b");
84-
}
85-
86-
{
87-
// Loading a array from "full.tt" using inject! macro.
88-
let array: &'static [u8; 4] = inject!(
89-
#arr("./for_examples/full.tt") // this file contains `a, b`.
90-
);
91-
92-
// Asserting the result matches the expected output.
93-
assert_eq!(array, b"a, b");
66+
assert_eq!(buf, "Welcome, Ferris. Your score is 100500.");
9467
}
9568
```
9669

‎examples/basic_codegen.rs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
macro_rules! new_module {
2+
[ @($const_t: ident) : [ $($path:tt)* ]; ] => {
3+
include_tt::inject! {
4+
#[allow(dead_code)]
5+
#[allow(non_upper_case_globals)]
6+
pub mod my_module {
7+
pub const a: usize = 0;
8+
pub const b: usize = 10;
9+
10+
// The `#POINT_TRACKER_FILES:` marker allows the macro to add additional
11+
// instructions that tell the compiler which files to track so that it can
12+
// recompile the macro if they change. This is completely optional, but without
13+
// it tracking will not work.
14+
#POINT_TRACKER_FILES:
15+
16+
pub const $const_t: (usize, usize) = (#tt($($path)*));
17+
}
18+
}
19+
};
20+
}
21+
22+
fn main() {
23+
// we created a module "my_module" and a constant "T" containing (a, b).
24+
//
25+
// if you need to change, for example, to (b,a) or substitute constant values,
26+
// we will only change the contents of the file "for_examples/full.tt"!
27+
new_module! {
28+
@(T): [examples / "full" . t 't']; // this file contains "a, b", see "for_examples/full.tt"
29+
}
30+
assert_eq!(my_module::T, (0, 10));
31+
}

examples/full.rs renamed to examples/basic_data.rs

File renamed without changes.

‎examples/constmodule.rs‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎examples/name.tt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"Ferris"

‎examples/score.tt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
100500

‎examples/template_macro.rs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
use include_tt::inject;
2+
use std::fmt::Write;
3+
fn main() {
4+
let mut buf = String::new();
5+
6+
inject! {
7+
write!(
8+
&mut buf,
9+
"Welcome, {}. Your score is {}!",
10+
#tt("examples/name.tt"), // `"Ferris"`
11+
#tt("examples/" "score" ".tt") // `100500`
12+
).unwrap();
13+
}
14+
15+
assert_eq!(buf, "Welcome, Ferris. Your score is 100500!");
16+
}

‎src/lib.rs‎

Lines changed: 60 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -35,53 +35,23 @@
3535
//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
3636
//SOFTWARE.
3737

38-
/*! Macro for embedding (trees, strings, arrays) into macro trees directly from files.
38+
/*! Macros for ultra-flexible injection of compiler trees, literals, or binary data into Rust syntax trees from external sources.
39+
3940
```rust
4041
use include_tt::inject;
4142
use std::fmt::Write;
42-
43-
// Example demonstrating the usage of inject! macro for embedding content from files.
44-
{
45-
// Embedding trees from a file in an arbitrary place of other macros.
46-
let a = 10;
47-
let b = 20;
48-
let mut end_str = String::new();
49-
50-
// Using inject! to embed content into a macro.
51-
inject! {
52-
let _e = write!(
53-
&mut end_str,
54-
55-
"arg1: {}, arg2: {}",
56-
57-
// This file contains `a, b`.
58-
#tt("./examples/full.tt") // this file contains `a, b`.
59-
);
60-
}
61-
62-
// Asserting the result matches the expected output.
63-
assert_eq!(end_str, "arg1: 10, arg2: 20");
64-
}
65-
66-
{
67-
// Loading a string from "full.tt" using inject! macro.
68-
let str = inject!(
69-
#str("./examples/full.tt") // this file contains `a, b`.
70-
);
71-
72-
// Asserting the result matches the expected output.
73-
assert_eq!(str, "a, b");
43+
let mut buf = String::new();
44+
45+
inject! {
46+
write!(
47+
&mut buf,
48+
"Welcome, {}. Your score is {}!",
49+
#tt("examples/name.tt"), // `"Ferris"`
50+
#tt("examples/" "score" ".tt") // `100500`
51+
).unwrap();
7452
}
7553
76-
{
77-
// Loading a array from "full.tt" using inject! macro.
78-
let array: &'static [u8; 4] = inject!(
79-
#arr("./examples/full.tt") // this file contains `a, b`.
80-
);
81-
82-
// Asserting the result matches the expected output.
83-
assert_eq!(array, b"a, b");
84-
}
54+
assert_eq!(buf, "Welcome, Ferris. Your score is 100500!");
8555
```
8656
*/
8757

@@ -432,43 +402,58 @@ fn autoinject_tt_in_group<'tk, 'gpsn>(
432402
SearchGroup::Break
433403
}
434404

435-
/// Macro for including trees, strings, arrays from files.
436-
///
437-
/// Multiple occurrences of groups are supported.
438-
///
405+
/// Macro for injecting trees, strings, arrays from files.
406+
///
407+
/// ## template_macro
439408
/// ```rust
440409
/// use include_tt::inject;
441410
/// use std::fmt::Write;
411+
/// let mut buf = String::new();
412+
///
413+
/// inject! {
414+
/// write!(
415+
/// &mut buf,
416+
/// "Welcome, {}. Your score is {}!",
417+
/// #tt("examples/name.tt"), // `"Ferris"`
418+
/// #tt("examples/" "score" ".tt") // `100500`
419+
/// ).unwrap();
420+
/// }
442421
///
443-
/// { // Embedding compiler trees from a file in an arbitrary place of other macros.
444-
/// let a = 10;
445-
/// let b = 20;
446-
///
447-
/// let mut end_str = String::new();
448-
/// inject! {
449-
/// let _e = write!(
450-
/// &mut end_str,
451-
///
452-
/// "arg1: {}, arg2: {}",
453-
/// #tt("./examples/full.tt") // this file contains `a, b`.
454-
/// );
455-
/// }
456-
/// assert_eq!(end_str, "arg1: 10, arg2: 20");
457-
/// }
458-
///
459-
/// {
460-
/// let str = inject!(
461-
/// #str("./examples/full.tt") // this file contains `a, b`.
462-
/// );
463-
/// assert_eq!(str, "a, b");
464-
/// }
465-
///
466-
/// {
467-
/// let array: &'static [u8; 4] = inject!(
468-
/// #arr("./examples/full.tt") // this file contains `a, b`.
469-
/// );
470-
/// assert_eq!(array, b"a, b");
471-
/// }
422+
/// assert_eq!(buf, "Welcome, Ferris. Your score is 100500!");
423+
/// ```
424+
///
425+
/// ## basic_codegen
426+
///
427+
/// ```rust
428+
/// macro_rules! new_module {
429+
/// [ @($const_t: ident) : [ $($path:tt)* ]; ] => {
430+
/// include_tt::inject! {
431+
/// #[allow(dead_code)]
432+
/// #[allow(non_upper_case_globals)]
433+
/// pub mod my_module {
434+
/// pub const a: usize = 0;
435+
/// pub const b: usize = 10;
436+
///
437+
/// // The `#POINT_TRACKER_FILES:` marker allows the macro to add additional
438+
/// // instructions that tell the compiler which files to track so that it can
439+
/// // recompile the macro if they change. This is completely optional, but without
440+
/// // it tracking will not work.
441+
/// #POINT_TRACKER_FILES:
442+
///
443+
/// pub const $const_t: (usize, usize) = (#tt($($path)*));
444+
/// }
445+
/// }
446+
/// };
447+
/// }
448+
///
449+
/// // we created a module "my_module" and a constant "T" containing (a, b).
450+
/// //
451+
/// // if you need to change, for example, to (b,a) or substitute constant values,
452+
/// // we will only change the contents of the file "for_examples/full.tt"!
453+
/// new_module! {
454+
/// @(T): [examples / "full" . t 't']; // this file contains "a, b", see "for_examples/full.tt"
455+
/// }
456+
/// assert_eq!(my_module::T, (0, 10));
472457
/// ```
473458
#[proc_macro]
474459
pub fn inject(input: TokenStream) -> TokenStream {

0 commit comments

Comments
 (0)