From b0442e56854f5a04d03b1a30fd273ded98296d93 Mon Sep 17 00:00:00 2001
From: sofia <sofia@teascade.net>
Date: Tue, 29 Jul 2025 16:02:54 +0300
Subject: [PATCH] Add documentation for include_bytes!

---
 documentation/README.md     | 7 ++++++-
 documentation/intrinsics.md | 8 ++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/documentation/README.md b/documentation/README.md
index a7a7e34..6db37e1 100644
--- a/documentation/README.md
+++ b/documentation/README.md
@@ -261,6 +261,9 @@ calls, literals, or if-expressions. Types of supported expressions include:
   *associated type* with given parameters.
   - **Accessing function calls**, a shorthand to call associated function calls
     which have `&self` or `&mut self` as their first parameter.
+  - **Macro invocations** for invoking **macros** which are evaluated at
+    compile-time rather than runtime. Currently it is not possible to define
+    your own macros, but there are some pre-defined in the intrinsics.
 - **Block-expressions**, which can return a value to the higher-level expression
   if they have a statement with a soft-return. Otherwise they return void.
 - **If-expressions**, which can execute one of two expressions depending on the
@@ -278,7 +281,7 @@ In formal grammar:
     <indexing> | <accessing> |
     <binary-exp> | <unary-exp> |
     <function-call> | <accessing-function-call> | <assoc-function-call>
-    <block> | <if-expr> | <cast> |
+    <macro-invocation> | <block> | <if-expr> | <cast> |
     ( "(" <expression> ")" )
 
 <variable> :: <ident>
@@ -294,6 +297,7 @@ In formal grammar:
 <function-call> :: <expression> "(" [ <expression> ( "," <expression> )* ] ")"
 <accessing-function-call> :: <accessing> "(" [ <expression> ( "," <expression> )* ] ")"
 <assoc-function-call> :: <type> "::" <function-call>
+<macro-invocation> :: <expression> "!(" [ <expression> ( "," <expression> )* ] ")"
 <if-expr> :: "if" <expression> <expression> [ "else" <expression> ]
 <cast> :: <expression> "as" <type>
 ```
@@ -312,6 +316,7 @@ test.first // Accessing
 func(value, 14) // Function call
 Test::get_field(&test); // Associated function call
 test.get_field(); // Same, but using a the dot-form shorthand
+include_bytes!("./test"); // Macro invocation
 if varname {} else {} // If-expression
 value as u32 // cast
 (value + 2) // Binop within parenthesis
diff --git a/documentation/intrinsics.md b/documentation/intrinsics.md
index 8d663fe..90996a4 100644
--- a/documentation/intrinsics.md
+++ b/documentation/intrinsics.md
@@ -17,6 +17,14 @@ Allocates `size` bytes and returns a pointer of `u8` of length `size`.
 i32::malloc(40); // Reserves 40 bytes
 ```
 
+### Macro Intrinsics
+
+#### `include_bytes!(path: *char) -> &[u8; _]`
+
+Attempts to load file from `path` (relative to module) into memory and includes
+it into the compiled binary directly. Returns a borrow to an array containing
+bytes from the file. Array length varies depending on the file contents.
+
 ### Associated Intrinsics
 
 #### `<T>::sizeof() -> u64`