Merge pull request #3 from clucompany/1.1.0

1.1.0

Author: denisandroid

Cargo.toml

@@ -1,15 +1,33 @@
 [package]
 name = "include_tt"
-version = "1.0.7"
+version = "1.1.0"
 edition = "2024"
 authors = ["Denis Kotlyarov (Денис Котляров) <denis2005991@gmail.com>"]
 repository = "https://github.com/clucompany/include_tt.git"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 
-description = "Macro for embedding (trees, strings, arrays) into macro trees directly from files."
-keywords = ["procedural-macros", "macro", "code-generation", "code-transformation", "clucompany"]
-categories = ["development-tools", "development-tools::build-utils"]
+description = "Macros for ultra-flexible injection of compiler trees, literals, or binary data into Rust syntax trees from external sources."
+keywords = [
+	"procedural-macros", 
+	"macro", 
+	"codegen", 
+	"syntax-injection", 
+	"tt-injection", 
+	"clucompany"
+]
+
+categories = [
+	"development-tools", 
+	"development-tools::build-utils", 
+	"development-tools::procedural-macro",
+	"code-generation", 
+	"parsing"
+]
+
+[features]
+default = [ ]
+escape_symbol = []
 
 [lib]
 proc-macro = true

README.md

@@ -2,7 +2,7 @@
 
   <b>[include_tt]</b>
 
-  (Macro for embedding (trees, strings, arrays) into macro trees directly from files.)
+  (Macros for ultra-flexible injection of compiler trees, literals, or binary data into Rust syntax trees from external sources.)
   </br></br>
 
 <div id="badges">
@@ -37,60 +37,33 @@ Add this to your Cargo.toml:
 
 ```toml
 [dependencies]
-include_tt = "1.0.7"
+include_tt = "1.1.0"
 ```
 
 and this to your source code:
 
 ```rust
-use include_tt::include_tt;
+use include_tt::inject;
 ```
 
 ## Example
 
 ```rust
-use include_tt::include_tt;
+use include_tt::inject;
 use std::fmt::Write;
-
-// Example demonstrating the usage of include_tt! macro for embedding content from files.
-{ 
-	// Embedding trees from a file in an arbitrary place of other macros.
-	let a = 10;
-	let b = 20;
-	let mut end_str = String::new();
-	
-	// Using include_tt! to embed content into a macro.
-	include_tt! {
-		let _e = write!(
-			&mut end_str,
-			
-			"arg1: {}, arg2: {}",
-			#include!("./for_examples/full.tt") // this file contains `a, b`.
-		);
+fn main() {
+	let mut buf = String::new();
+
+	inject! {
+		write!(
+			&mut buf,
+			"Welcome, {}. Your score is {}.",
+			#tt("examples/name.tt"),			// `"Ferris"`
+			#tt("examples/" "score" ".tt")	// `100500`
+		).unwrap();
 	}
-	
-	// Asserting the result matches the expected output.
-	assert_eq!(end_str, "arg1: 10, arg2: 20");
-}
 
-{ 
-	// Loading a string from "full.tt" using include_tt! macro.
-	let str = include_tt!(
-		#include_str!("./for_examples/full.tt") // this file contains `a, b`.
-	);
-	
-	// Asserting the result matches the expected output.
-	assert_eq!(str, "a, b");
-}
-
-{
-	// Loading a array from "full.tt" using include_tt! macro.
-	let array: &'static [u8; 4] = include_tt!(
-		#include_arr!("./for_examples/full.tt") // this file contains `a, b`.
-	);
-	
-	// Asserting the result matches the expected output.
-	assert_eq!(array, b"a, b");
+	assert_eq!(buf, "Welcome, Ferris. Your score is 100500.");
 }
 ```
 

examples/basic_codegen.rs

@@ -0,0 +1,31 @@
+macro_rules! new_module {
+	[ @($const_t: ident) : [ $($path:tt)* ]; ] => {
+		include_tt::inject! {
+			#[allow(dead_code)]
+			#[allow(non_upper_case_globals)]
+			pub mod my_module {
+				pub const a: usize = 0;
+				pub const b: usize = 10;
+				
+				// The `#POINT_TRACKER_FILES:` marker allows the macro to add additional 
+				// instructions that tell the compiler which files to track so that it can 
+				// recompile the macro if they change. This is completely optional, but without 
+				// it tracking will not work.
+				#POINT_TRACKER_FILES: 
+				
+				pub const $const_t: (usize, usize) = (#tt($($path)*));
+			}
+		}
+	};
+}
+
+fn main() {
+	// we created a module "my_module" and a constant "T" containing (a, b).
+	//
+	// if you need to change, for example, to (b,a) or substitute constant values,
+	// we will only change the contents of the file "for_examples/full.tt"!
+	new_module! {
+		@(T): [examples / "full" . t 't']; // this file contains "a, b", see "for_examples/full.tt"
+	}
+	assert_eq!(my_module::T, (0, 10));
+}

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

@@ -1,4 +1,4 @@
-use include_tt::include_tt;
+use include_tt::inject;
 use std::fmt::Write;
 
 macro_rules! test2_rules {
@@ -44,35 +44,35 @@ macro_rules! test2_rules {
 
 fn main() {
 	// Loading trees from a file and substituting them into a custom macro.
-	include_tt! {
-		#POINT_TRACKER_FILES;
+	inject! {
+		#POINT_TRACKER_FILES:
 		test2_rules! {
-			[ #include!("./examples/full.tt") ] // this file contains `a, b`.
-			[ #include! { "./examples/full.tt" } ] // this file contains `a, b`.
+			[ #tt("./examples/full.tt") ] // this file contains `a, b`.
+			[ #tt { "./examples/full.tt" } ] // this file contains `a, b`.
 		}
 		test2_rules! {
-			#include!("./examples/full.tt") // this file contains `a, b`.
+			#tt ("./examples/full.tt") // this file contains `a, b`.
 		}
 
 		println!(
 			concat!(
 				"#",
-				#include_str!("./examples/full.tt"), // this file contains `a, b`.
+				#str("./examples/full.tt"), // this file contains `a, b`.
 				"#"
 			)
 		);
 	}
 
 	{
 		// Loading a string from a file.
-		let str = include_tt!(#include_str!("./examples/full.tt")); // this file contains `a, b`.
+		let str = inject!(#str("./examples/full.tt")); // this file contains `a, b`.
 		assert_eq!(str, "a, b");
 	}
 
 	{
 		// Loading an array from a file.
-		let array: &'static [u8; 4] = include_tt!(
-			#include_arr!("./examples/full.tt") // this file contains `a, b`.
+		let array: &'static [u8; 4] = inject!(
+			#array("./examples/full.tt") // this file contains `a, b`.
 		);
 		assert_eq!(array, b"a, b");
 	}
@@ -83,12 +83,12 @@ fn main() {
 		let b = 20;
 
 		let mut end_str = String::new();
-		include_tt! {
+		inject! {
 			let _e = write!(
 				&mut end_str,
 
 				"arg1: {}, arg2: {}",
-				#include!("./examples/full.tt") // this file contains `a, b`.
+				#tt("./examples/full.tt") // this file contains `a, b`.
 			);
 		}
 		assert_eq!(end_str, "arg1: 10, arg2: 20");

examples/constmodule.rs

@@ -1,4 +1,4 @@
-use include_tt::include_tt;
+use include_tt::inject;
 
 macro_rules! test_rules {
 	[
@@ -35,14 +35,14 @@ fn main() {
 	let a = 10;
 	let b = 20;
 
-	include_tt! {
+	inject! {
 		// this macro only supports:
 		// a + b = n
 		// or
 		// a - b = n
-		#POINT_TRACKER_FILES;
+		#POINT_TRACKER_FILES:
 		test_rules! {
-			#include!("./examples/mrules.tt") // this file contains "a + b = n", see "./for_examples/mrules.tt"
+			#tt("./examples/mrules.tt") // this file contains "a + b = n", see "./for_examples/mrules.tt"
 		}
 	}
 	assert_eq!(n, a + b);

examples/mrules.rs

@@ -0,0 +1 @@
+"Ferris"

examples/name.tt

@@ -0,0 +1 @@
+100500

examples/score.tt

@@ -0,0 +1,16 @@
+use include_tt::inject;
+use std::fmt::Write;
+fn main() {
+	let mut buf = String::new();
+
+	inject! {
+		write!(
+			&mut buf,
+			"Welcome, {}. Your score is {}!",
+			#tt("examples/name.tt"),			// `"Ferris"`
+			#tt("examples/" "score" ".tt")	// `100500`
+		).unwrap();
+	}
+
+	assert_eq!(buf, "Welcome, Ferris. Your score is 100500!");
+}