From 91d8d283760e5da4c777fad5ffbd29b9bf3ca71d Mon Sep 17 00:00:00 2001
From: Chimrod <>
Date: Fri, 22 Sep 2023 15:06:51 +0200
Subject: Updated the readme

---
 readme.md | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index ae37826..4396f21 100644
--- a/readme.md
+++ b/readme.md
@@ -1,4 +1,48 @@
 
 # QSP Syntax Parser
 
-This tool is a syntax analyzer for the QSP Language.
+This tool is a syntax analyzer for the QSP Language. It contains a syntaxic
+parser able to read the QSP language, and allow some analysis over it.
+
+The application does not use regexes, but translates the source qsp file using
+a grammar to represent each instruction.
+
+In this way, the application is able to :
+
+1. Point out an error in the source code, indicating the line that could not be
+   translated.
+2. Perform operations on the file representation.
+
+## Reading QSP
+
+The QSP language was not designed to be processed in this way. There are
+ambivalent cases that cannot be represented cleanly via a grammar.
+
+An example is the `!` character, which can indicate the start of a comment, or
+an inequality operator.
+
+Another example is the `*` character, which can be the first character of an
+instruction, or a multiplication operation. For example:
+
+- `*clr()` is a valid instruction, but `5 *clr()` is not.
+- `*rnd()` is an invalid instruction, but `5 *rnd()` is valid.
+(As a bonus `rnd* rnd()` is also valid…)
+
+What's more, the language is very permissive, allowing for structures that are
+actually incorrect.
+
+For example:
+
+```
+if $PARGS[0] = 'Day1':
+end
+
+elseif $ARGS[0] = 'Week1':
+end
+```
+
+As a result, the application may pick up errors on particular cases that are
+nonetheless valid. I've tried to respect the syntax of the QSP language as much
+as possible, but on borderline cases, I consider that being stricter is
+positive.
+
-- 
cgit v1.2.3