docs: test improviments

Author: Heitor Danilo

.vscode/settings.json

@@ -28,6 +28,12 @@
  "def.h": "c",
  "chardef.h": "c",
  "langdef.h": "c",
- "token_test.h": "c"
+ "token_test.h": "c",
+ "vector": "c",
+ "array": "c",
+ "string_view": "c",
+ "initializer_list": "c",
+ "utility": "c",
+ "TEST.C": "cpp"
  }
 }

README.md

@@ -1,62 +1,99 @@
 <h1 align="center">Overview</h1>
 
-**Mariana** is a simple interpreted language created using standard C. It came about from my desire to design something with "perfect" syntax (in my opinion). It's developed purely for learning purposes.
+**Mariana** is a simple interpreted language created using C. It came about from my desire to design something with "perfect" syntax (in my opinion). It's developed purely for learning purposes.
 
 Being aware that this language will never be used in production, and is merely a small personal project, this README will be used as a discussion platform during the development process, such as, for instance, architectural decisions concerning syntax.
 
 <h1 align="center">Getting Started</h1>
 
-I plan to develop an installation script. For now, you can clone the source code and compile it directly:
+"I am in the process of developing an installation script. However, for now, you can clone the source code and compile it manually. Follow these steps:
 
 1. Clone the repository:
+
  ```bash
  git clone https://github.com/heiytor/mari-programming-language && cd mari-programming-language
  ```
 
 2. Compile the source code:
 
  ```bash
- make dev
- ```
-
- During the project development, I personally chose to build my own testing "framework" to stick to the idea of using only standard C. You can run all the tests with:
- ```bash
- make test
+ make
  ```
- 
- If all tests pass, the output will look something like:
 
- ![image](https://github.com/heiytor/mari-programming-language/assets/107213601/62583e37-9fde-4c85-988b-bd43f3290aa8)
+ This command will first run all [tests](). If all tests pass, the source code will then be compiled. If you want to only compile the source code without running the tests, you can use `make dev`.
 
- 
- On the other hand, if any test fails, the program will exit, and the output will look something like:
+Once you've done that, navigate to the project folder and execute the following command:
 
- ![image](https://github.com/heiytor/mari-programming-language/assets/107213601/b742dfb6-84ba-4cfd-a1cf-44d012ad43b4)
-
-With that done, within the project folder you can run the following command:
-
-```
+```bash
 ./program
 ```
 
-This will start a small REPL.
+This will launch a simple Read-Eval-Print Loop (REPL)."
 
 <h1 align="center">Syntax</h1>
 
 ```mariana
 // Function definition
-def func add(def x, def y) {
+var add_numbers = fn(def x, def y) {
  return x + y;
 }
 
-def x = 5; // Variable definition. All variables are constants by default.
-def mut y = 10; // Mutable variable definition
+var x = 5; // Variable definition. All variables are constants by default.
+var mut y = 10; // Mutable variable definition
 
-def result = add(x, y);
+var result = add(x, y);
 x = 0; // This will throw an error.
 y = 0; // This will pass.
 
-println("{x} + {y} = {result}");
+println("${x} + ${y} = ${result}");
+```
+
+<h1 align="center">Tests</h1>
+
+During the course of this project's development, I considered several testing frameworks, such as Check. However, my evaluation led me to the conclusion that introducing such a framework could potentially overcomplicate things.
+
+As a result, I decided to implement my own testing "framework". Running these tests is simple, just execute the following command:
+
+```
+make test
+```
+
+If all tests pass successfully, the console will display a message similar to the following:
+
+![]()
+
+However, if a test fails, the program will halt execution at the point of failure, allowing for easier debugging.
+
+You can find the definitions for all tests in the files that end with the "_test.h" suffix, while the `_test.c` files contain the implementations of these tests. The `./src/main_test.c` file serves as the test runner, executing all test implementations.
+
+Tests are named following the pattern "**test_should_pass_if_\[condition]**". For example:
+1. **test_should_pass_if**_var_statement_to_string_is_equal_to_expected (`src/ast/ast_test.h`)
+2. **test_should_pass_if**_bool_assignments_are_equal_to_expected (`src/token/token_test.h`)**
+
+Each `_test.c` file contains local helper functions that assist in performing specific tasks within the file, but are not accessible for other tests. For this reason, I would categorize this as a library, rather than a framework. For instance, in ***src/ast/ast_test.c***, you'll find the `create_program` function:
+
+```C
+struct Program* create_program(char* input) {
+ struct Lexer* lexer = new_lexer(input);
+ struct Parser* parser = new_parser(lexer);
+ struct Program* program = parser->parse_program(parser);
+
+ return program;
+}
+```
+
+This function assists us in creating new programs within tests:
+
+```C
+void test_should_pass_if_program_to_string_is_equal_to_expected() {
+ char* input = "var x = ;\n" // var statement
+  "var mut y = ;\n" // mutable var statement
+  "return ;"; // return statement
+
+ struct Program* prg = create_program(input);
+
+ // [...]
+}
 ```
 
 <h1 align="center">Developer Notes</h1>
@@ -82,11 +119,16 @@ One of my primary goals in this project is readability and comprehensibility (ma
  * 
  * If the lexer sees any of these characters after a letter, the lexer must create a single token:
  * my_!var: "my_!var"
-*/
-bool is_allowed_as_first_char(byte ch) {
- return ch != '.' && ch != '?' &&
-
- ch != '!';
+ * 
+ * @param ch The current character being evaluated.
+ * 
+ * @return 1 if is number, 0 otherwise.
+ */
+int is_allowed_as_first_char(byte ch) {
+ return ch != '.' &&
+ // ch != '-' && // uncomment to allow kebab-case
+ ch != '?' &&
+ ch != '!';
 }
 ```