Document context files and the way they work

Signed-off-by: William Desportes <williamdes@wdes.fr>

Author: williamdes

src/Tools/ContextGenerator.php

@@ -398,10 +398,16 @@ public static function buildAll($input, $output)
 
         foreach ($files as $file) {
             // Skipping current and parent directories.
+            // Skipping _functions* and _common.txt files
             if (($file[0] === '.') || ($file[0] === '_')) {
                 continue;
             }
 
+            // Skipping README.md
+            if ($file === 'README.md') {
+                continue;
+            }
+
             // Building the context.
             echo sprintf("Building context for %s...\n", $file);
             static::build($input . '/' . $file, $output);

tools/contexts/README.md

@@ -0,0 +1,32 @@
+# Context files
+
+This files are used to generate `src/Contexts/*.php` files.
+You need to run `./tools/run_generators.sh` to generate/update them.
+The file `src/Tools/ContextGenerator.php` is responsible for building them.
+And the generated files are loaded and used by `src/Context.php`.
+
+## Default contexts
+
+- For MySQL: MySql50700
+- For MariaDB: MariaDb100300
+
+### In tests
+
+If you name your data files with `_mariadb_` it will automatically load the context for you.
+For example: `tests/data/parser/parseSelectOverAlias_mariadb_100600.in`.
+
+## Files structure
+
+The file `tools/contexts/_common.txt` contains all the data
+that exists in all of the MariaDB and MySQL versions currently supported.
+
+Each `tools/contexts/_functions[MariaDb|MySql]<versionint>.txt` contains the functions supported in this version.
+
+Each `tools/contexts/[MariaDb|MySql]<versionint>.txt` contains the keywords supported in this version.
+
+## Data scheme
+
+- `(R)` -> reserved, can be found on common and version files
+- `(D)` -> data type, can be found on `_common.txt`
+- `(K)` -> keyword, can be found on common and version files
+- `(F)` -> function name, can be found on `_functions[MariaDb|MySql]<versionint>.txt` files