Proposed spec for DEP for assert with messages.

docs/language/dartLangSpec.tex

Index: docs/language/dartLangSpec.tex
diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex
index 3850f200dfcfc00dea26f2a7b80fdf71a2c7f3a8..6b88e59ecaf43c012dfedb3627fb732d9c4ef1b5 100644
--- a/docs/language/dartLangSpec.tex
+++ b/docs/language/dartLangSpec.tex
@@ -3874,7 +3874,7 @@ Let $T$ be the  static type of $o$. It is a static type warning if $T$ does not
 \item
 $T$ or a superinterface of $T$ is annotated with an annotation denoting a constant identical to the constant \code{@proxy} defined in \code{dart:core}.  Or
 \item  $T$ is \code{Type}, $e$ is a constant type literal and the class corresponding to $e$ has a static getter named $m$.
-\item $T$ is \code{Function} and $m$ is \CALL. \rationale {The type \code{Function} is treated as if it has a \code{call} method for any possible signature of \CALL. The expectation is that any concrete subclass of \code{Function} will implement \CALL. Note that a warning will be issue if this is not the case. Furthermore, any use of \CALL{} on a subclass of \code{Function} that fails to implement \CALL{} will also provoke a a warning, as this exemption is limited to type \code{Function}, and does not apply to its subtypes. 
+\item $T$ is \code{Function} and $m$ is \CALL. \rationale {The type \code{Function} is treated as if it has a \code{call} method for any possible signature of \CALL. The expectation is that any concrete subclass of \code{Function} will implement \CALL. Note that a warning will be issue if this is not the case. Furthermore, any use of \CALL{} on a subclass of \code{Function} that fails to implement \CALL{} will also provoke a warning, as this exemption is limited to type \code{Function}, and does not apply to its subtypes. 
 }
 \end{itemize}
 
@@ -6457,24 +6457,38 @@ An {\em assert statement} is used to disrupt normal execution if a given boolean
 
 \begin{grammar}
 {\bf assertStatement:}
-   assert `(' conditionalExpression `)' `{\escapegrammar ;}'
+   assert `(' conditionalExpression (`,' expression)?  `)' `{\escapegrammar ;}'
       .
 \end{grammar}
       
 \LMHash{}
-The assert statement has no effect in production mode. In checked mode, execution of an assert statement \code{\ASSERT{}($e$);} proceeds as follows:
+The assert statement has no effect in production mode. In checked mode, execution of an assert statement \code{\ASSERT{}($e$);} or \code{\ASSERT{}($e$, $s$);} proceeds as follows:
 
 \LMHash{}
 The conditional expression $e$ is evaluated to an object $o$. If the class of $o$ is a subtype of \code{Function} then let $r$ be the result of invoking $o$ with no arguments. Otherwise, let $r$ be $o$. 
-It is a dynamic type error if $o$ is not of type \code{bool} or of type \code{Function}, or if $r$ is not of type \code{bool}.  If $r$ is \FALSE{}, we say that the assertion failed. If $r$ is \TRUE{}, we say that the assertion succeeded. If the assertion succeeded, execution of the assert statement is complete. If the assertion failed, an \code{AssertionError} is thrown.
+It is a dynamic type error if $o$ is not of type \code{bool} or of type \code{Function}, or if $r$ is not of type \code{bool}.  If $r$ is \FALSE{}, we say that the assertion failed. If $r$ is \TRUE{}, we say that the assertion succeeded. If the assertion succeeded, execution of the assert statement is complete. 
+
+\LMHash{}
+If the assertion failed, and the assertion is of the form \code{\ASSERT{}($e$);} an \cd{AssertionError()} is thrown.

[Lasse Reichstein Nielsen, 2015/11/04 11:58:46]

I don't think it needs the "()" after AssertionError. Ditto below.

[gbracha, 2015/11/04 21:27:29]

Done.

+
+If the assertion failed and the assertion is of the form \code{\ASSERT{}($e$, $s$);} then the expression $s$ is evaluated to a value $o_s$. If evaluation of $s$ fails, an \cd{AssertionError()} is thrown. Otherwise, the \cd{toString()} method is invoked on $o_s$ resulting in a string object $m$. If the invocation of \cd{toString()} throws an exception, an \cd{AssertionError()} is thrown. Otherwise, 

[Lasse Reichstein Nielsen, 2015/11/04 11:58:46]

We could remove the toString call completely, and just use the object o_s as
message.
That avoids the entire problem of handling it if toString throws, and allows the
AssertionError to use Error.safeToString on the object if it wants to.

[Paul Berry, 2015/11/04 16:48:17]

I'm not convinced that would be an improvement, for two reasons.

1. It's not uncommon for a complex object to have a toString method which
renders its content in an easily human-readable form.  It seems likely that
users are going to want that custom toString method to be used when generating
assertion failure messages.

2. Most of the time people are probably going to construct assertion messages
using string interpolation, e.g. `assert(x == y, "Unexpected difference between
$x and $y");`.  In this case toString() is going to get used to translate x and
y to strings, no matter what.  The case of using a non-string as the assertion
message is going to be the rarer case, so whatever behavior we choose for it
should be as unsurprising as we can feasibly make it.  I like the current
formulation because it makes the semantics of `assert(..., x);` and `assert(...,
"$x")` exactly the same, and I think that will be the least surprising to users.

So personally I am fine leaving it as is.

[gbracha, 2015/11/04 21:27:29]

I agree with Paul. In 99% of the cases, s will be a string anyway, and in the
rest, you'll want the toString() of the object. I'm leaving this as is.

+an \cd{AssertionError} $x$ is created with error message $m$.
+ 
+\rationale {
+The optional argument $s$ is intended to allow a suitable message to be associated with the assertion. An implementation should endeavor to display the message $m$ in a manner that is useful to the developer.
+}
+
+\commentary{
+The definition above implies  that $s$ is not evaluated if the assertion succeeded.
+}
 
 %\Q{Might be cleaner to define it as \code{if (!$e$) \{\THROW{} \NEW{} AssertionError();\}} (in checked mode only).
 %What about an error message as part of the assert?}
 
 \LMHash{}
- It is a static type warning if the type of $e$ may not be assigned to either  \code{bool} or $() \rightarrow$ \code{bool}.  
+ It is a static type warning if the type of $e$ may not be assigned to either  \code{bool} or $() \rightarrow$ \code{bool}. 
 
-\rationale{Why is this a statement, not a built in function call? Because it is handled magically so it has no effect and no overhead in production mode. Also, in the absence of final methods. one could not prevent it being overridden (though there is no real harm in that).  It cannot be viewed as a function call that is being optimized away because the argument might have side effects.
+\rationale{Why is this a statement, not a built in function call? Because it is handled magically so it has no effect and no overhead in production mode. Also, in the absence of final methods. one could not prevent it being overridden (though there is no real harm in that).  It cannot be viewed as a function call that is being optimized away because the argument might have side effects. And lastly, the optional string message would have to be evaluated in all cases if \ASSERT{} were a function.

[Lasse Reichstein Nielsen, 2015/11/04 11:58:46]

string message -> message

[gbracha, 2015/11/04 21:27:29]

Done.

 }
 
 %If a lexically visible declaration named \code{assert} is in scope, an assert statement 
@@ -7321,7 +7335,7 @@ A function type $(T_1, \ldots T_n, \{T_{x_1}$ $x_1, \ldots, T_{x_k}$ $x_k\}) \ri
 \item $\forall i \in 1 .. n, T_i \Longleftrightarrow S_i$.
 \item $k \ge m$ and $y_i \in \{x_1,  \ldots, x_k\}, i \in 1 .. m$.
 %\{x_1,  \ldots, x_k\}$ is a superset of $\{y_1,  \ldots, y_m\}$.
-\item For all $y_i \in \{y_1,  \ldots, y_m\}, y_i = x_j \Rightarrow T_j \Longleftrightarrow S_i$
+\item For all $y_i \in \{y_1,  \ldots, y_m\}, y_i = x_j \Rightarrow T_{x_j} \Longleftrightarrow S_{y_i}$
 \end{enumerate}
 
 %In addition, a function type $(T_1, \ldots, Tn, [T_{n+1} x_{n+1}, \ldots, T_{n+k} x_{n+k}]) \rightarrow T$ is a subtype of the function type $(T_1, \ldots, T_n, T_{n+1} , [T_{n+2} x_{n+2}, \ldots, T_{n+k} x_{n+k}]) \rightarrow T$.