From 346ad17e264bd512d7bc2d6c34cc5653b6adbdbc Mon Sep 17 00:00:00 2001
From: "Gu://em_" <guillem.george@epita.fr>
Date: Sat, 17 Jan 2026 16:40:53 +0100
Subject: [PATCH] docs: reworked parser header to fully comply with the given
 grammar and added a language representation for each parse_* function

---
 src/parser/parsing_utils.c |  7 ++-
 src/parser/parsing_utils.h | 88 +++++++++++++++++++++++++++++---------
 2 files changed, 73 insertions(+), 22 deletions(-)

diff --git a/src/parser/parsing_utils.c b/src/parser/parsing_utils.c
index c07653e..0d0f43a 100644
--- a/src/parser/parsing_utils.c
+++ b/src/parser/parsing_utils.c
@@ -47,6 +47,11 @@ static bool is_end_of_list(struct token *token)
 
 // === Functions
 
+struct ast *parse_input(void)
+{
+    return parse_list();
+}
+
 /* Parses a simple list of words (command and arguments)
  * and returns the resulting ast
  */
@@ -55,7 +60,7 @@ struct ast *parse_simple_command(void)
     struct list *command_elements = NULL;
     struct token *token = PEEK_TOKEN();
 
-    while (!isterminator(token))
+    while (token->type == TOKEN_WORD)
     {
         token = POP_TOKEN();
         command_elements = list_append(command_elements, token->data);
diff --git a/src/parser/parsing_utils.h b/src/parser/parsing_utils.h
index a380a85..3c9101c 100644
--- a/src/parser/parsing_utils.h
+++ b/src/parser/parsing_utils.h
@@ -19,33 +19,79 @@
         return NULL;                                                           \
     }
 
-/* @brief: parses a list of [and_or] rules, separated by semicolons.
+/* @brief Acts as the entry point of the parser, calls parse_list
+ */
+struct ast* parse_input(void);
+
+/* @brief: parses a list of [and_or] rules separated by semicolons and that
+ *         ends by a newline
+ *
+ * @code input = list '\n'
+ *             | list EOF
+ *             | '\n'
+ *             | EOF
+ *             ;
  */
 struct ast *parse_list(void);
 
-/* @brief Parses a simple list of words (command and arguments)
- * and returns the resulting ast
- */
-struct ast *parse_simple_command(void);
-
-/* 
- */
-struct ast *parse_if_rule(void);
-
-/*
- */
-struct ast *parse_shell_command(void);
-
-/* @brief parses commands inside if/else clauses and returns the corresponding
- * AST list
- */
-struct ast* parse_compound_list(void);
-
-/*
+/* @brief Only parses a pipeline rule for the moment
+ *
+ * @code and_or = pipeline ;
  */
 struct ast* parse_and_or(void);
 
-/*
+/* @brief Only parses a command rule for the moment
+ *
+ * @code pipeline = command ;
+ */
+struct ast* parse_pipeline(void);
+
+/* @brief Parses a simple command rule or a shell command rule depending on
+ *        the first token.
+ * @note
+ *        TOKEN_WORD => simple_command
+ *        TOKEN_IF => shell_command
+ *
+ * @code command = simple_command
+ *               | shell_command
+ *               ;
+ */
+struct ast* parse_command(void);
+
+/* @brief Parses a simple list of words (command and arguments)
+ *        ending by a separator
+ *
+ * @code simple_command = WORD { element } ;
+ */
+struct ast *parse_simple_command(void);
+
+
+/* @brief Only parses if rules for the moment
+ *
+ * @code shell_command = if_rule ;
+ */
+struct ast *parse_shell_command(void);
+
+
+/* @brief Parses a if rule (condition, then-clause, elif-clause, else-clause)
+ *
+ * @code if_rule = 'if' compound_list 'then' compound_list [else_clause] 'fi' ;
+ */
+struct ast *parse_if_rule(void);
+
+
+/* @brief parses commands inside if/else clauses and returns the corresponding
+ * AST list
+ *
+ * @code compound_list = {'\n'} and_or { ( ';' | '\n' ) {'\n'} and_or } [';'] {'\n'} ;
+ */
+struct ast* parse_compound_list(void);
+
+/* @brief
+ *
+ * @code else_clause = 'else' compound_list
+ *                   | 'elif' compound_list 'then' compound_list [else_clause]
+ *                   ;
  */
 struct ast* parse_else_clause(void);