added doc on ===, instanceof and typeof.

doc/jsweet-language-specifications.md

@@ -15,6 +15,7 @@ Content
 -   [Basic concepts](#basic-concepts)
     -   [Core types and objects](#core-types-and-objects)
     -   [Classes](#classes)
+    -   [Testing the type of an object](#testing-the-type-of-an-object)
     -   [Interfaces](#interfaces)
     -   [Untyped objects (maps)](#untyped-objects-maps)
     -   [Enums](#enums)
@@ -80,6 +81,17 @@ boolean b = false;
 assert !b;
 ```
 
+Note that in JSweet the `==` operator behaves like in JavaScript on primitive types, so that when comparing a string and an integer, it will try to match the two without taking the types in consideration. For instance, `2 == 2` evaluates to `true`. In JavaScript, one can use the `===` operator to strictly compare the objects, so that `2 === 2` evaluates to `false`. To use the `===` operator in JSweet, use the `jsweet.util.Globals.equalsStrict` utility method as follows.
+
+``` java
+import static jsweet.util.Globals.equalsStrict;
+[...]
+int i = 2;
+assert i == 2;
+assert "2" == i;
+assert !(equalsStrict("2", i);
+```
+
 #### Allowed Java objects
 
 Here follows the list of allowed Java classes in JSweet:
@@ -285,6 +297,37 @@ public class ContainerClass {
 
 Exceptions: inner classes annotated with `@ObjectType` or `@Erased` are allowed (see the part on Auxiliary Types).
 
+### Testing the type of an object
+
+To test the type of a given object at runtime, one can use the `instanceof` Java operator. It is the advised and preferred way to test types at runtime. JSweet will transpile to a regular `instanceof` or to a `typeof` operator depending on the tested type (it will fallback in `typeof` for `number`, `string`, and `boolean` core types).
+
+It is also possible to directly use the `typeof` operator from JSweet with the `jsweet.util.Globals.typeof` utility method. In general, it is not necessary to use it and the `instanceof` operator is preferred and more general.
+
+Here are some examples of valid type tests:
+
+``` java
+import static jsweet.util.Globals.typeof;
+import static jsweet.util.Globals.equalsStrict;
+[...]
+Number n1 = 2;
+Object n2 = 2;
+int n3 = 2;
+Object s = "test";
+MyClass c = new MyClass();
+
+assert n1 instanceof Number; // transpiles to a typeof
+assert n2 instanceof Number; // transpiles to a typeof
+assert n2 instanceof Integer; // transpiles to a typeof
+assert !(n2 instanceof String); // transpiles to a typeof
+assert s instanceof String; // transpiles to a typeof
+assert !(s instanceof Integer); // transpiles to a typeof
+assert c instanceof MyClass;
+assert typeof(n3) == "number";
+assert equalsStrict(typeof(n3), "number");
+```
+
+Note: the `instanceof` operator is not allowed in interfaces, for reasons that will be explained in the following sections.
+
 ### Interfaces
 
 In JSweet, an interface (a.k.a. object type) can be seen as object signature, that is to say the accessible functions and properties of an object (without specifying any implementation). An interface is defined for typing only and has no runtime representation (no instances), however, they can be used to type objects.

doc/jsweet-language-specifications.tex

@@ -108,6 +108,17 @@ boolean b = false;
 assert !b;
 \end{lstlisting}
 
+Note that in JSweet the \texttt{==} operator behaves like in JavaScript on primitive types, so that when comparing a string and an integer, it will try to match the two without taking the types in consideration. For instance, \texttt{"2" == 2} evaluates to \texttt{true}. In JavaScript, one can use the \texttt{===} operator to strictly compare the objects, so that \texttt{"2" === 2} evaluates to \texttt{false}. To use the \texttt{===} operator in JSweet, use the \texttt{jsweet.util.Globals.equalsStrict} utility method as follows. 
+
+\begin{lstlisting}[language=Java]
+import static jsweet.util.Globals.equalsStrict;
+[...]
+int i = 2;
+assert i == 2;
+assert "2" == i;
+assert !(equalsStrict("2", i);
+\end{lstlisting}
+
 \subsection{Allowed Java objects}
 
 Here follows the list of allowed Java classes in JSweet:
@@ -301,6 +312,37 @@ public class ContainerClass {
 
 Exceptions: inner classes annotated with \texttt{@ObjectType} or \texttt{@Erased} are allowed (see the part on Auxiliary Types).
 
+\section{Testing the type of an object}
+
+To test the type of a given object at runtime, one can use the \texttt{instanceof} Java operator. It is the advised and preferred way to test types at runtime. JSweet will transpile to a regular \texttt{instanceof} or to a \texttt{typeof} operator depending on the tested type (it will fallback in \texttt{typeof} for \texttt{number}, \texttt{string}, and \texttt{boolean} core types).
+
+It is also possible to directly use the \texttt{typeof} operator from JSweet with the \texttt{jsweet.\-util.\-Globals.\-typeof} utility method. In general, it is not necessary to use it and the \texttt{instanceof} operator is preferred and more general.
+
+Here are some examples of valid type tests:
+
+\begin{lstlisting}[language=Java]
+import static jsweet.util.Globals.typeof;
+import static jsweet.util.Globals.equalsStrict;
+[...]
+Number n1 = 2;
+Object n2 = 2;
+int n3 = 2;
+Object s = "test";
+MyClass c = new MyClass();
+
+assert n1 instanceof Number; // transpiles to a typeof
+assert n2 instanceof Number; // transpiles to a typeof
+assert n2 instanceof Integer; // transpiles to a typeof
+assert !(n2 instanceof String); // transpiles to a typeof
+assert s instanceof String; // transpiles to a typeof
+assert !(s instanceof Integer); // transpiles to a typeof
+assert c instanceof MyClass;
+assert typeof(n3) == "number";
+assert equalsStrict(typeof(n3), "number");
+\end{lstlisting}
+
+Note: the \texttt{instanceof} operator is not allowed in interfaces, for reasons that will be explained in the following sections.
+
 \section{Interfaces}
 
 In JSweet, an interface (a.k.a. object type) can be seen as object signature, that is to say the accessible functions and properties of an object (without specifying any implementation). An interface is defined for typing only and has no runtime representation (no instances), however, they can be used to type objects.