Change specification of main.

docs/language/dartLangSpec.tex

Index: docs/language/dartLangSpec.tex
diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex
index f643ef1b4c525783671578723d7bb4eb0c3ac4ee..e616ecffbaf4c550d2d5fc1d9c4aeb662b467d1f 100644
--- a/docs/language/dartLangSpec.tex
+++ b/docs/language/dartLangSpec.tex
@@ -7159,36 +7159,47 @@ It's a compile-time error if the same library contains two part directives with
 \LMLabel{scripts}
 
 \LMHash{}
-A {\em script} is a library whose exported namespace  (\ref{exports}) includes a top-level member named  \code{main}. It is a static warning if the static type of \code{main} is not assignable to a function type or is a function type with more than two required parameters.
+A {\em script} is a library whose exported namespace (\ref{exports}) includes
+a top-level function declaration named \code{main}
+that can be called with zero, one or two positional arguments.

[eernst, 2017/05/10 09:30:34]

So the situation before: A library containing `main(a,b,c){}` is a script and
there is a static warning (because it takes >2 required arguments). The
situation with this change: A library containing `main(a,b,c){}` is not a script
(and there are no diagnostic messages of any kind).

This means that separate compilation cannot detect any problems with a
declaration like `main(a,b,c){}`. To me that looks like a step backwards.

Given that we have had a warning in this case until now (except that the
analyzer doesn't detect it ;-), couldn't we keep it flagged (and maybe make it
an error)? How is it going to help people that they can have these "bad main
functions"?

To keep it, we could have `A {\em script} is a library whose exported namespace
(\ref{exports}) includes a top-level function declaration named \code{main}. It
is a static warning if it cannot be called with zero, one, or two positional
arguments.`

There's a small formatting thing, too: I'm used to grepping the LaTeX source for
relevant parts of the spec on various topics. That will slowly get more and more
error-prone if we insert newlines in phrases (e.g., if we start formatting the
spec in 80 columns, maybe even using auto-fill-mode in Emacs). I can see that
the lines above are somewhat phrase-oriented (one line contains "one meaning"),
but I might well be searching for 'includes a top-level', which won't work any
more.

Because of this, I've avoided reformatting to 80 columns in a lot of cases where
I touched the spec source, in order to keep obvious "units of meaning" on a
single line, e.g., by having one whole sentence per line.

In this particular case I'd keep the whole sentence on one line, and in general
I would prefer a somewhat more conservative approach to the insertion of
newlines.

[Lasse Reichstein Nielsen, 2017/05/30 05:45:38]

As discussed, I disagree that we should impose constraints on unrelated
libraries by saying that all top-level functions called `main` must be script
entry points.
It's true that it might not help anybody because they won't be writing those,
but it also enshrines the `main` function in the specification as special. If an
embedder wants to have a different entry point, like the Windows "winmain"
method which is different from "main", that's OK, and they can enforce whatever
they want on their entry-point library, and they shouldn't affect other
libraries. I hold ourselves to the same standard - the "main" function is not a
*Dart language* feature, it's a tooling feature, it's the *standard* way to
execute a Dart program, the hook that the embedder/compiler uses to start
execution, but the *language* doesn't require it.

Basically, the entire section should probably be considered non-normative.

[eernst, 2017/05/30 09:14:42]

Unsurprisingly, I would still prefer to go from "static warning" to
"compile-time error" rather than going to "no issues according to the spec!" (at
least, separate compilation and hence the analyzer cannot do anything else). But
being in the minority in the discussions IRL, I won't insist.

 
-A script $S$ may be executed as follows:
+A script $S$ is executed as follows:
 
 \LMHash{}
-First, $S$ is compiled as a library as specified above. Then, the top-level function \code{main} that is in the exported namespace of $S$ is invoked. If \code{main} has no positional parameters, it is invoked with no arguments. Otherwise if \code{main} has exactly one positional parameter, it is invoked with a single actual argument whose runtime type implements \code{List<String>}.  Otherwise \code{main} is invoked with the following two actual arguments:
+First, $S$ is compiled as a library as specified above.
+Then, the top-level function defined by \code{main}

[eernst, 2017/05/10 09:30:34]

An exported namespace is a mapping that binds names to declarations. We can't
really invoke a declaration, but I think we do have precedence for talking about
a declaration and the semantic entity that its name denotes at run time as the
same thing. So let's say that there is a top-level function which is bound to
\code{main} in that namespace.

I think 'the top-level function \code{main}` would then be OK; also `the
top-level function bound to \code{main} in the exported namespace..` and (of
course) `the top-level function defined by the declaration bound to \code{main}
in the exported namespace..`. But `the top-level function defined by
\code{main}..` seems to use `defined by` to refer to the declaration, and then
instead proceeds with `\code{main}` which is clearly the name. I think that's
more twisted than it needs to be.

[Lasse Reichstein Nielsen, 2017/05/30 05:45:38]

Going for "top level function \code{main}".

[eernst, 2017/05/30 09:14:42]

Acknowledged.

+in the exported namespace of $S$ is invoked (\ref{functionInvocation})
+with up to two arguments, depending on how many it will accept.

[eernst, 2017/05/10 09:30:34]

The 'depending ..' is too imprecise. Just `up to two arguments: If
\code{main}..` is better.

[Lasse Reichstein Nielsen, 2017/05/30 05:45:38]

Going for just "as follows:".
The "up to two arguments" is specified in the following anyway.

[eernst, 2017/05/30 09:14:42]

Acknowledged.

+If \code{main} can be be called with with two positional arguments,
+it is invoked with the following two actual arguments:
 \begin{enumerate}
 \item An object whose runtime type implements \code{List<String>}.
-\item The initial message of the current isolate $i$ as determined by the invocation of \code{Isolate.spawnUri} that spawned $i$.
+\item An object specified when the current isolate $i$ was created,
+for example through the invocation of \code{Isolate.spawnUri} that spawned $i$,
+or \NULL{} if no such object was supplied.
 \end{enumerate}
-
-\LMHash{}
-It is a run time error if $S$ does not declare or export either:
-\begin{itemize}
-\item  A top-level function named  \code{main}, or
-\item A top-level getter named  \code{main} that returns a function.
-\end{itemize}
+If \code{main} cannot be called with two positional arguments,
+but it can be called with one positional argument,
+it is invoked an object whose runtime type implements \code{List<String>}

[eernst, 2017/05/10 09:30:34]

`invoked [with] an object`

[Lasse Reichstein Nielsen, 2017/05/30 05:45:37]

Done.

+as the only argument.
+If \code{main} cannot be called with one or two positional arguments,
+it is invoked with no arguments.
 
 \commentary {
-Note that if \code{main} requires more than two arguments, a run time error will occur.
-}
-
-\rationale{
-The names of scripts are optional, in the interests of interactive, informal use. However, any script of long term value should be given a name as a matter of good practice.
+Note that if \code{main} requires more than two positional arguments,
+the library is not considered a script.

[eernst, 2017/05/10 09:30:34]

If we keep the approach where `main(a,b,c){}` is detected and flagged at
compile-time then this is no longer true. I believe it can be omitted.

[Lasse Reichstein Nielsen, 2017/05/30 05:45:37]

I don't plan to keep that approach, so retaining this comment.

[eernst, 2017/05/30 09:14:42]

Right, that's the consistent approach.

 }
 
 \commentary {
 A Dart program will typically be executed by executing a script.
 }
 
+\LMHASH{}

[eernst, 2017/05/10 09:30:34]

`\LMHash{}`.

[Lasse Reichstein Nielsen, 2017/05/30 05:45:38]

Done.

+If a non-script library is provided where a script is expected,
+it precludes execution.
+As such, it should be reported as a compile-time error,
+even if that library compiles successfully as a non-script library.

[eernst, 2017/05/10 09:30:34]

If we keep the "`main(a,b,c){}` is detected at compile-time" approach, there is
no need to describe something which is clearly a run-time thing, and then
claiming that we can emit a compile-time error here. ;-)

[Lasse Reichstein Nielsen, 2017/05/30 05:45:38]

As discussed, I disagree on that.

It is not a runtime error to not be a script where a script is expected. Runtime
starts when main is executed, and it isn't executed if it is not a script.

So, it's either a compile-time error or just user error (like specifying an
entry point that isn't a Dart file at all). 

[eernst, 2017/05/30 09:14:42]

At this point I'm trying really hard to find a way to make this approach work
well (that is, where `main(a,b,c) {}` is not an error, it's just the library
which isn't a script).

I assume that we do not want to add a section about linking. We also do not want
to imply that separate compilation is a violation of the spec.

This means that we just _cannot_ say that it is compile time when 'a non-script
library is provided where a script is expected'. If a script is expected then we
have a closed world, and we do not wish to require that the closed world is
known during compilation.

Please just drop lines 7200 and 7201.

This means that it is up to the implementation to do something meaningful which
will preclude that execution, and we do not specify what it is.
User error is fine! And we don't specify that.

+
 \subsection{URIs}
 \LMLabel{uris}