Rethink quoting in user-facing messages

[dmajda]

If users use non-ASCII characters in string literals in the grammar, they get ugly error messages from the generated parser. For example, a parser generated from this grammar:

start = "μ"

will produce the following error message on empty input:

Expected "\u03BC" but end of input found.

The generated parser probably shouldn't escape non-ASCII characters in user-facing messages.

There is also a question how to represent control characters line newline or tab. Currently we use JacaScript string representation (e.g. Expected "\n"...) but maybe saying something like Expected newline... would be more user-friendly.

This is a spin-off from #120.

[Skalman]

I think only control characters should be escaped, though it might be an idea to make this an option, to make it possible to determine visibly ambiguous character.

In the case of \n vs newline, I'm not so sure newline is clearer, even by itself. I believe that \0, \t, \n and \r are well-known, maybe even more than NUL, tab, newline and carriage return, where tab is the one I'm least sure of.

[dmajda]

Now that found was removed, escaping in error messages is used only on strings corresponding to grammar literals. This means we can just carry literal raw texts over and avoid the escaping problem completely, leaving it on the grammar writer how he expresses his literals. We already do this for character classes.

[Mingun]

I agree that found property isn't necessary in an exception now, but the exclusion but <xxx> found part of the error message does it to the very little informative.

Anyway, if the user wants to make the error message (for example, to localize it) he has all necessary information. However, then it is necessary to consider that the error function shall create the own property containing the structured information about an error (for example userMessage property) by which it will be possible to determine that this exception is generated by the error function.

Then localization of the message can look somehow so:

catch (e) {// SyntaxError or GrammarError
  if (e.userMessage) {// generated by |error| function
    format(
      "Строка %1, столбец %2: %3",
      e.location.start.line, e.location.start.column,
      e.userMessage
    );
    // e.message === "<|error| argument>";
    // e.expected === null;
  } else {
    format(
      "Строка %1, столбец %2: Ожидается %3, но найдено '%4'",
      e.location.start.line, e.location.start.column,
      formatExpected(e.expected), buildFound(input, e.location)
    );
    // e.message === "Expected <e.expected> but '...' found";
  }
}

Thus, message property will give the clear default already formatted description of an error, and the structured information for detail analysis will contain in separate properties.

[dmajda]

Just noting that I’m considering reverting changes done in 69a0f76 and 25ab980.

The main reason is that raw literal texts probably aren’t the right thing to display to users. For example, it doesn’t feel right that a choice between single and double quotes when writing literals in a grammar influences error messages.

As for the found property and related error message adjustments, I’m not so sure, but there seems to be a value in identifying errors right from their messages (i.e. without location info, which may not always be used by applications in such a way that it helps users to locate errors efficiently).

---

@Mingun Exceptions created by error can be recognized by their expected property being null. If this feels to hackish to you, I wouldn’t be against creating a separate subclass for them (in that case, please file an issue).

[Mingun]

Exceptions created by error can be recognized by their expected property being null . If this feels to hackish to you, I wouldn’t be against creating a separate subclass for them (in that case, please file an issue).

No, this quite normal solution, however, this not documented.

[dmajda]

I reverted the change done in 69a0f76 and implemented a better solution.