[racket-dev] Error message proposal

I think you're asking for two changes to the error-message syntax:

 * Move srcloc back to the front of error messages.

 * Support multi-line messages: the first line is supposed to be useful
   on its own, but extra lines act as a kind of detail field that is
   nicely placed and particularly prominent.

As long as the extra lines are indented by one space to make them
easily parseable, those changes sound fine to me.

Your example message contains a sentence with capitalization and an
ending period. As nice as it looks in the example, that kind of text
composes badly, so I'd prefer to stick with lowercase and (as needed)
semi-colons.

I'm also happy to allow the initial name in an error messages to be
sometimes an entity that is complained about, instead of always the
complaining entity. (That's not in the message below, except by
indirection.)


Meanwhile, I think you're asking for some changes to existing error
messages, such as adapting some existing messages that can be usefully
broken into first and second lines. I have certain specific hanges in
mind; probably we'll have to take them one-by-one at some point.


Finally, I think you're asking for a change to DrRacket:

 * Don't show any fields beyond the first line until the user clicks
   somewhere.

That doesn't sound practical to me. When I call a function with the
wrong number of arguments, for example, I don't want to have to click
to find out how many arguments are expected.

I think it will work better to have a field convention or syntax to
indicate whether a field should be hidden by default. How about using
"..." at the end of a field name to indicate that it could be hidden
by default?

 > (+ 1 'a)
 +: contract violation
   expectation: number?
   given: 'a
   argument position: 2nd
   other arguments...:
    1
   context...:
    /Users/mflatt/proj/plt/collects/racket/private/misc:87:7
 > (add1 1 2 3)
 add1: arity mismatch;
  the expected number of arguments does not match the given number
   expected: 1
   given: 3
   arguments...:
    1
    2
    3
   technical note...: this is a contract violation for the application form
   context...:
    /Users/mflatt/proj/plt/collects/racket/private/misc:87:7


At Thu, 21 Jun 2012 06:03:36 +0800, Matthew Flatt wrote:
> Thanks. I'll give this a try as soon as possible.
> 
> At Wed, 20 Jun 2012 13:32:32 -0400, Eli Barzilay wrote:
> > Here's a concrete proposal for error message structe.  I'll leave the
> > highlevel philosophical discussion to the other threads -- but JFYI,
> > it does require accepting the problems I mention in the "phrasing"
> > thread.
> > 
> > The general idea is that the first line of an error message is a
> > title, and therefore should provide as much helpful information as
> > possible, in a short form that usually will fit on a single line.
> > This works well with the previous error message format, but broken
> > down completely when errors contain a lot of details.  Notable
> > examples: list of paths in a cyclic require; the list of "other
> > arguments" in type errors; the "probably" explanation on an empty
> > () application error; and the suggestion made in the link errors.
> > 
> > So I'm suggesting that the first line is the "error title" which is
> > kept in a form similar to what it was.  That is:
> > 
> >     [optional short location information]
> >     offending token:
> >     short description (fits on one line)
> > 
> > The next line(s) (single or few) add more precise and verbose details
> > on the error.  Examples of that are the suggestion I mentioned above,
> > or the more accurate description of an unbound identifier error, or
> > the `#%app' mention in the () case.
> > 
> > Following that are the "fields", which can stay in a semi-structured
> > textual format for making them parsable.  This structure should be
> > specified, but given the above two parts there is no need for being
> > very specific with various fields etc.
> > 
> > As a concrete example, a contract error could be:
> > 
> >   foo.rkt:10:15: blah: bad input
> >     Contract violation in the first argument, your code broke the
> >     contract of blah from `some-library/blah'.
> >     expected: ...
> >     given: ...
> >     argument position: ...
> >     other arguments: ...
> >     full path: ...
> >     contract location: ...
> >     context: ...
> > 
> > Note how the first line is imprecise, and provides just a summary.
> > The idea is what I discussed previously -- in many cases this error
> > will pop up after some revision to the code that you just did, so
> > that's enough to know what the problem.
> > 
> > The following two lines provide more precise information -- and now
> > that they're on following lines, that description is no longer
> > restriced to be short in any way.  This means, for example, that
> > Ryan's semi-complaint about the non-preciseness of unbound identifier
> > errors can be addressed.
> > 
> > Next to that there is the list of fields, and since it's all "down
> > after the main texts", it's becoming practical to add a lot of
> > relevant information like full paths of the files in question,
> > even more detailed explanations on what the error is, suggestions for
> > fixing it, pointers to URLs about those errors, etc etc.
> > 
> > From a presentation point of view (eg, drracket and xrepl), this
> > format makes things very easy, since it follows the way you'd want to
> > present the information.  For example, drracket can do the following
> > pretty easily (just random suggestions, of course):
> > 
> >   * Show the usual stop-sign line with just the title line (without
> >     the location)
> >   * When you hover over the line, a popup opens up with the detailed
> >     two-line explanation.
> >   * When you click the icon, you jump to the relevant location with
> >     that popup.
> >   * When you hover over the error, or maybe in the popup, you see a
> >     list of field names, and clicking them shows the contents of the
> >     field.
> > 
> > Even a textual interface like xrepl can do something similar, where
> > the exposition of details goes gradually based on your needs.
> > 
> > More benefits:
> > 
> > * It's probably not hard to re-change the code, since it's keeping the
> >   multi-line aspect and the fields.
> > 
> > * Sounds like `error' is not going away in its current format which
> >   already does the first-line thing fine.
> > 
> > * Existing un-updated code works fine too.
> > 
> > * With the assumption that fields are not initially shown (which
> >   translates to some parameter), a lot more information can be added
> >   in them, even when they're irrelevant for human consumption.  For
> >   example, full paths to source files can blow up the message (eg,
> >   paths to the blamed file, the contract definition, and the
> >   contracted file; or list of paths in a cycle; or showing a
> >   *complete* stacktrace).
> > 
> > -- 
> >           ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
> >                     http://barzilay.org/                   Maze is Life!
> > 
> > _________________________
> >   Racket Developers list:
> >   http://lists.racket-lang.org/dev
> _________________________
>   Racket Developers list:
>   http://lists.racket-lang.org/dev