From 234ce9447f15f02daf1f8f08d7beb80bdc65c323 Mon Sep 17 00:00:00 2001
From: Chimrod <>
Date: Wed, 18 Oct 2023 09:37:11 +0200
Subject: Update documentation

---
 documentation/parsing.md |  34 ++++++++++++++++
 readme.md                | 100 +++++++++++++++++++++++++++++------------------
 2 files changed, 96 insertions(+), 38 deletions(-)
 create mode 100644 documentation/parsing.md

diff --git a/documentation/parsing.md b/documentation/parsing.md
new file mode 100644
index 0000000..43d5028
--- /dev/null
+++ b/documentation/parsing.md
@@ -0,0 +1,34 @@
+# 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.
+
+
diff --git a/readme.md b/readme.md
index 4396f21..bc27ddb 100644
--- a/readme.md
+++ b/readme.md
@@ -7,42 +7,66 @@ 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.
+## Command line 
+
+    qsp_parser.exe input_file             
+      --version  Display the version of the application and exit
+      --level    Message level [debug, warn, error]
+      --global   Each line is refered from the begining of the file and not the
+                 location
+      -help      Display this list of options
+      --help     Display this list of options
+    
+
+You can run the application by giving in argument the file to analyze: the
+results will be printed in the standard output: 
+
+     qsp_parser.exe test.qsrc 
+     Location test                         
+     [{ level = Warn; loc = Line 3 19:27;
+        message = "The type Integer is expected but got String" };
+       { level = Debug; loc = Line 4 26:30;
+         message = "The type Integer is expected but got String" };
+       { level = Debug; loc = Line 5 8:45;
+         message = "Possible dead end (no else fallback)" };
+       { level = Warn; loc = Lines 13-15;
+         message = "Possible dead end (unmatched path)" }
+       ]
+    Found 0 error(s), 3 warning(s)
+     
+
+## Checks provided
+
+I will take this small code as example. The output of the analysis is given
+just above:
+
+
+    # test
+                                                    ! Warning here, $ARGS expect a string
+    if $ARGS[1] = 0 or $ARGS[1] = 1:
+    		act 'action':  value = '123'            &! value is a numeric variable
+            if value = 2: act 'other': gt 'other'   &! Dead end here if value ≠ 2
+    else
+    		act 'Action2': gt 'arg', 'arg1'
+    end
+    
+    act 'Go':
+    	if 0:
+    		act 'Leave': gt 'begin'
+    	else
+    		act 'Label': 'Action'                   &! Dead end here
+    	end
+    end
+    
+    --- test ---------------------------------
+
+### Type checking
+
+The QSP language uses explicit variable name for string or numeric values and you
+can easily spot when a string value is used instead of a numeric.
+
+### Dead end
+
+By analysing the branchs, the application can spot the block where no `gt`
+instructions are given, which can lead to dead end in the code.
 
-- 
cgit v1.2.3