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
