Added a page for the qsp typing system

1 files changed, 95 insertions, 0 deletions

diff --git a/documentation/typing.md b/documentation/typing.md
new file mode 100644
index 0000000..57b792d
--- /dev/null
+++ b/documentation/typing.md
@@ -0,0 +1,95 @@
+# QSP Type system
+
+Internally, there is only two types in the engine : String and Integer. This is
+represented with this C struct :
+
+```C
+typedef struct
+{
+    union
+    {
+        QSPString Str;
+        int Num;
+    } Val;
+    QSP_TINYINT Type;
+} QSPVariant;
+```
+
+## Variables and assignation
+
+The type of a variable is determined by the first character in the name:
+
+```C
+#define QSP_STRCHAR QSP_FMT("$")
+
+// …
+
+#define QSP_VARBASETYPE(name) (*(name).Str == QSP_STRCHAR[0]) /* QSP_TYPE_STRING | QSP_TYPE_NUMBER */
+```
+
+But during the assignation, a conversion is automatically done when the types does not match :
+
+```C
+INLINE void qspSetVar(QSPString name, QSPVariant *val, QSP_CHAR op)
+{
+    …
+    if (QSP_VARBASETYPE(name) != QSP_BASETYPE(val->Type))
+    {
+        if (!qspConvertVariantTo(val, QSP_VARBASETYPE(name)))
+        {
+            qspSetError(QSP_ERR_TYPEMISMATCH);
+            return;
+        }
+        qspSetVarValueByReference(var, index, val);
+    
+    }
+```
+
+This can raise uncontrolled error with some functions like `INPUT` if you
+directly the result into a numeric variable.
+
+## Conversion and comparaison between values
+
+Most of the functions provide automatic conversion between them: a string will
+be converted in integer if the other operand is an integer:
+
+- math operation
+
+    That’s why `'1' + 1` will give the result `2` and not `'11'`
+
+- comparaison
+
+
+    For example, the source code for the comparaison is the following one:
+    
+    ```C
+    case qspOpEq:
+        QSP_NUM(tos) = QSP_TOBOOL(qspAutoConvertCompare(args, args + 1) == 0);
+        break;
+    ```
+
+
+When string cannot be converted into a number, the number will be converted in
+string, and the comparaison will compare thoses two strings. In the ASCII
+table, a text will always be greater than a number (`'a' > 9999` will return
+`-1` and `'$' > 0` will return `0`)
+
+
+## Explicit conversion
+
+### From string to num
+
+`isnum(…)` will tell you if a value is an integer or not: 
+
+```
+isnum('123') -> -1
+isnum('abc') -> 0
+```
+
+Using `val(…)` you can convert a string into a integer:
+
+```
+val('123') -> 123
+val('abc') -> 0     ! No error here
+```
+