From 2a98f19c223d06a4365dd6e825e4717d1617bc6a Mon Sep 17 00:00:00 2001 From: Eggsrael Date: Fri, 10 Oct 2025 16:16:19 -0700 Subject: [PATCH 1/6] Docs(preamble): Added rust examples --- docs/writing-reactors/preambles.mdx | 74 +++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index c2111eaf3..91c493c90 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -440,6 +440,80 @@ The important takeaway here is with the package.json file and the compiled JavaS +For example, the follow reactor brings the constant `PI` into scope allowing us to call `f64::const::PI` as `PI` + +```lf-c +target Rust; + +main reactor { + preamble {= + use std::f64::const::PI; + =} + + reaction(startup) {= + println!("{}", PI); + =} +} +``` + +This will print: + +``` +3.141592653589793 +``` +for this example, we add the crate [hello](https://docs.rs/hello/latest/hello/) through the rust [cargo-dependencies](<../reference/target-declaration#cargo-dependencies>) target option. +```lf-C +target Rust { + cargo-dependencies: { + hello: "1.0.4", + }, +}; + +preamble {= + use hello; +=} + +main reactor { + reaction(startup) { + hello::world(); + } +} + +``` +This will print: +``` +Hello, world! +``` + +In this example we create a function `add_42` and a rust macro `add!` +```lf-c +target Rust; + +main reactor { + preamble {= + macro_rules! add { + ($a:expr, $b:expr) => { + $a+$b + } + } + fn add_42 (a: i32) -> i32 { + return a + 42; + } + =} + + reaction(startup) { + println!("add macro example: {}", add!(1,1)); + println!("add 42 example: {}", add_42(10)); + } +} + +``` +This will print: +``` +add macro example: 2 +add 42 example: 52 +``` + :::danger FIXME: Add `preamble` example. ::: From 5960df009859604f6bf2cf0449433d26d4195ce8 Mon Sep 17 00:00:00 2001 From: Eggsrael Date: Mon, 13 Oct 2025 14:21:44 -0700 Subject: [PATCH 2/6] Docs(preamble): Fixed examples and added explanations --- docs/writing-reactors/preambles.mdx | 95 +++++++++++++++-------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index 91c493c90..f2f61e219 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -440,78 +440,81 @@ The important takeaway here is with the package.json file and the compiled JavaS -For example, the follow reactor brings the constant `PI` into scope allowing us to call `f64::const::PI` as `PI` + You can use the `preamble` to define macros and functions that are shared within the given reactor: ```lf-c target Rust; -main reactor { +main reactor { preamble {= - use std::f64::const::PI; + macro_rules! add { + ($a:expr, $b:expr) => { + $a+$b + } + } + fn add_42 (a: i32) -> i32 { + return a + 42; + } =} - reaction(startup) {= - println!("{}", PI); - =} + reaction(startup) { + println!("add macro example: {}", add!(1,1)); + println!("add 42 example: {}", add_42(10)); + } } ``` - -This will print: - +This will print: ``` -3.141592653589793 +add macro example: 2 +add 42 example: 52 ``` -for this example, we add the crate [hello](https://docs.rs/hello/latest/hello/) through the rust [cargo-dependencies](<../reference/target-declaration#cargo-dependencies>) target option. -```lf-C -target Rust { - cargo-dependencies: { - hello: "1.0.4", - }, -}; -preamble {= - use hello; -=} +By having the `preamble` inside the reactor, you can define any functions or macros that are shared within the given reactor. This will allow you to reuse code across different reactions easily within the same reactor. This also can extend to `use` to shorten declaration of module items. For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: -main reactor { - reaction(startup) { - hello::world(); - } -} +```lf-c +target Rust; + +main reactor { + preamble {= + use std::f64::const::PI; + =} + reaction(startup) {= + println!("{}", PI); + =} +} ``` This will print: ``` -Hello, world! +3.141592653589793 ``` +By putting `use` in the `preamble`, you can change the scope of `PI` for the for the reactor, in this case the main reactor. Its important to note that besides the crates specified in the target declarations _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. This means that crate level attributes like `#![no_std]` will not work if added to the preamble. -In this example we create a function `add_42` and a rust macro `add!` -```lf-c -target Rust; +This would be an example of accessing a user created module named `foo` that is in the same directory as the lingua france program: -main reactor { +File: example.lf +```lf-c +target Rust { + rust-include: ["foo.rs"] +} +main reactor { preamble {= - macro_rules! add { - ($a:expr, $b:expr) => { - $a+$b - } - } - fn add_42 (a: i32) -> i32 { - return a + 42; - } + use crate::foo::world; =} - - reaction(startup) { - println!("add macro example: {}", add!(1,1)); - println!("add 42 example: {}", add_42(10)); + reaction(startup) { + world(); } } - ``` -This will print: +File: foo.rs +```rust +pub fn world() { + println!("Hello, world!"); +} ``` -add macro example: 2 -add 42 example: 52 +This will print: +``` +Hello, world! ``` :::danger From b4a05aaa9dff32a48b6c9c6b68f9348b73e3bd5d Mon Sep 17 00:00:00 2001 From: Eggsrael Date: Tue, 14 Oct 2025 12:12:51 -0700 Subject: [PATCH 3/6] Docs(preamble): Small changes --- docs/writing-reactors/preambles.mdx | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index f2f61e219..ac526fbd0 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -464,12 +464,16 @@ main reactor { } ``` This will print: + ``` add macro example: 2 add 42 example: 52 ``` -By having the `preamble` inside the reactor, you can define any functions or macros that are shared within the given reactor. This will allow you to reuse code across different reactions easily within the same reactor. This also can extend to `use` to shorten declaration of module items. For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: +By having the `preamble` inside the reactor, you can define any functions or macros to be shared within the given reactor. +This will allow you to reuse code across different reactions easily within the same reactor. +This also can allow us to change the scope of items using the 'use' statement. +For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: ```lf-c target Rust; @@ -484,15 +488,19 @@ main reactor { =} } ``` + This will print: + ``` 3.141592653589793 ``` -By putting `use` in the `preamble`, you can change the scope of `PI` for the for the reactor, in this case the main reactor. Its important to note that besides the crates specified in the target declarations _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. This means that crate level attributes like `#![no_std]` will not work if added to the preamble. +By putting `use` in the `preamble`, the scope of `PI` is changed for the entire reactor, in this case the main reactor. +This works with all items that are brought into scope using the `use` statement and not just constants and functions. -This would be an example of accessing a user created module named `foo` that is in the same directory as the lingua france program: +This would be an example of accessing a user created module named `foo` that is included using the `rust-include` target parameter: File: example.lf + ```lf-c target Rust { rust-include: ["foo.rs"] @@ -506,17 +514,24 @@ main reactor { } } ``` + File: foo.rs + ```rust pub fn world() { println!("Hello, world!"); } ``` + This will print: + ``` Hello, world! ``` +Its important to note that besides the crates specified in the target declarations _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. +This means that crate level attributes like `#![no_std]` will not work if added to the preamble. + :::danger FIXME: Add `preamble` example. ::: From f31dc55a625d1c1eea1f2fdccbdff958e2d209f3 Mon Sep 17 00:00:00 2001 From: Eggsrael Date: Tue, 14 Oct 2025 12:39:33 -0700 Subject: [PATCH 4/6] Docs(Preamble): more small fixes --- docs/writing-reactors/preambles.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index ac526fbd0..4bf39dc5d 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -440,7 +440,7 @@ The important takeaway here is with the package.json file and the compiled JavaS - You can use the `preamble` to define macros and functions that are shared within the given reactor: +For example, you can use the `preamble` to define macros and functions that are shared within the given reactor: ```lf-c target Rust; @@ -472,7 +472,8 @@ add 42 example: 52 By having the `preamble` inside the reactor, you can define any functions or macros to be shared within the given reactor. This will allow you to reuse code across different reactions easily within the same reactor. -This also can allow us to change the scope of items using the 'use' statement. +This also can allow us to change the scope of items using the `use` statement. + For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: ```lf-c @@ -529,7 +530,7 @@ This will print: Hello, world! ``` -Its important to note that besides the crates specified in the target declarations _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. +It is important to note that besides Crates specified in the rust target declaration's _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. This means that crate level attributes like `#![no_std]` will not work if added to the preamble. :::danger From ef360351528282cfad33acdde9873b7ab5c09546 Mon Sep 17 00:00:00 2001 From: Eggsrael Date: Thu, 16 Oct 2025 13:25:02 -0700 Subject: [PATCH 5/6] Docs(Preamble): added link to help readers understand crate --- docs/writing-reactors/preambles.mdx | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index 4bf39dc5d..94e5a9572 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -442,7 +442,7 @@ The important takeaway here is with the package.json file and the compiled JavaS For example, you can use the `preamble` to define macros and functions that are shared within the given reactor: -```lf-c +```lf-rs target Rust; main reactor { @@ -476,7 +476,7 @@ This also can allow us to change the scope of items using the `use` statement. For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: -```lf-c +```lf-rs target Rust; main reactor { @@ -502,7 +502,7 @@ This would be an example of accessing a user created module named `foo` that is File: example.lf -```lf-c +```lf-rs target Rust { rust-include: ["foo.rs"] } @@ -530,12 +530,8 @@ This will print: Hello, world! ``` -It is important to note that besides Crates specified in the rust target declaration's _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. +It is important to note that besides [crates](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html) specified in the rust target declaration's _cargo-dependencies_ and user modules in _rust-include_, all user code is added to a module called `reactors` during compilation time. This means that crate level attributes like `#![no_std]` will not work if added to the preamble. -:::danger -FIXME: Add `preamble` example. -::: - From 7e772cdef152997ea3106fa39c3aab52341b4c36 Mon Sep 17 00:00:00 2001 From: "Edward A. Lee" Date: Tue, 21 Oct 2025 04:44:03 -0700 Subject: [PATCH 6/6] Update preambles.mdx --- docs/writing-reactors/preambles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-reactors/preambles.mdx b/docs/writing-reactors/preambles.mdx index 94e5a9572..341337b2d 100644 --- a/docs/writing-reactors/preambles.mdx +++ b/docs/writing-reactors/preambles.mdx @@ -474,7 +474,7 @@ By having the `preamble` inside the reactor, you can define any functions or mac This will allow you to reuse code across different reactions easily within the same reactor. This also can allow us to change the scope of items using the `use` statement. -For example, the follow reactor brings the constant `PI` into scope and print out the first 15 digits of pi: +For example, the follow reactor brings the constant `PI` into scope and prints out the first 15 digits of pi: ```lf-rs target Rust;