Pegjs: Отчеты об ошибках редизайна

Я вижу три проблемы с текущей системой отчетов об ошибках в PEG.js:

1. Действия сообщают об ошибках, возвращая null

Reporting using `null` is inflexible (it doesn't allow to carry any information about the kind of error) and makes it impossible to return `null` as a regular value from actions, which would be useful sometimes (for example [in a JSON parser](https://github.com/dmajda/pegjs/blob/791034fad92c9cd7a9d1c71187df03441bbfd521/examples/json.pegjs#L45)).

См. также № 17.

1. Невозможно создать ошибки с полностью пользовательскими сообщениями.

For example, imagine a HTTP 1.1 parser that wants to report an error about missing `Host` header in a HTTP request with a message like "A HTTP 1.1 request must contain a Host header". Currently the only way to do this is to throw an exception with desired message manually. This is cumbersome and it does not interact well with the backtracking behavior (throwing an exception halts the parsing completely, even when it is possible to backtrack and try another alternatives).

1. Свойство expected SyntaxError трудно обрабатывать механически.

The `expected` property of `SyntaxError` is either an array of expectations (each describing one alternative which the parser expected at the position of error) or `null` (meaning that the end of input was expected).

Каждое ожидание представлено строкой. Эта строка может означать ожидаемый литерал (представленный с использованием синтаксиса PEG.js — строка в кавычках), класс символов (представленный с использованием синтаксиса PEG.js — [...] ) или любой символ (представленный строкой "any" ). Чтобы различать эти случаи, необходимо вручную анализировать строковые представления, что делает инструменты построения на основе PEG.js, такие как автозаполнения, излишне сложными.

Я планирую изменить систему сообщений об ошибках, чтобы исправить эти проблемы. Прежде чем я опишу изменения, о которых я думаю, необходимо небольшое описание того, как работает текущая система.

Как сейчас работает отчет об ошибках?

Когда синтаксический анализатор PEG.js пытается сопоставить строковый литерал, класс символов или . и терпит неудачу, он выдает _match failure_. Он состоит из _position_ и _expectation_ (описание того, что парсер пытался сопоставить).

После неудачного сопоставления синтаксический анализатор отступает и, возможно, пробует другие альтернативы. Если ни одна из них не увенчалась успехом и больше пробовать нечего, синтаксический анализатор выдает исключение SyntaxError . При настройке его свойств (таких как позиция, ожидания, сообщение об ошибке и т. д.) синтаксический анализатор учитывает только самое дальнее несоответствие (с наибольшей позицией). Если таких отказов больше, их ожидания объединяются.

Ситуация немного усложняется, если используются именованные правила, но это не имеет отношения к данному обсуждению.

Предлагаемые изменения

Я думаю о следующих изменениях в системе сообщений об ошибках:

1. Ожидания в SyntaxError.expected будут представлены не строками, а объектами. Объекты будут иметь свойство type (с такими значениями, как "literal" , "class" , "any" , "eof" ), которое будет определять тип ожидания. Для некоторых типов ожиданий подробности будут содержаться в других свойствах (например, для ожидания "literal" где будет свойство value , содержащее ожидаемую строку). Это упростит механическую обработку ожиданий.

Альтернативой свойству type является использование классов. Но я думаю, что пользователям будет проще обращаться со свойством type .

1. Действиям будет разрешено возвращать null . Это будет обычное значение и не будет означать ошибку.
2. Действия смогут инициировать сбой совпадения с помощью новой функции error . В качестве параметра он примет сообщение об ошибке. Сбои, вызванные этой функцией (называемые _неудачными совпадениями_), будут состоять из _позиции_ и _сообщения об ошибке_. У них не будет никаких ожиданий.

Функция error не будет прерывать выполнение действия, она просто пометит его как неудачное и сохранит сообщение об ошибке. Фактический сбой будет произведен только после завершения выполнения действия. Если функция error вызывается несколько раз, победит последний вызов (будет использовано его сообщение об ошибке).

Сбои пользовательского совпадения будут обрабатываться как обычные сбои совпадения, то есть они не будут полностью останавливать синтаксический анализ и позволять синтаксическому анализатору вернуться и, возможно, попробовать другие альтернативы. Однако есть одно отличие — при окончательном генерировании исключения SyntaxError правило комбинации ожиданий, которое применяется к обычным неудачным совпадениям, не будет применяться к пользовательским. Если в наборе неудачных совпадений с самой дальней позицией есть хотя бы один пользовательский, он просто полностью переопределит обычные. Если пользовательских сбоев больше, то победит тот, который был создан последним.

Исключение SyntaxError , основанное на сбое пользовательского совпадения, будет отличаться от исключений, основанных на обычном сбое. Его свойство message будет равно сообщению об ошибке, а его свойство expected будет равно null .

Пример

```
начало = знак:[+-]? цифры:[0-9]+ {
var result = parseInt((sign || "") + digits.join(""), 10);

 if (result % 2 == 0) {
   error("The number must be an odd integer.");
 }

 return result;

}
```

При вводе 2 синтаксический анализатор, сгенерированный из приведенной выше грамматики, выдаст SyntaxError с message , установленным в "The number must be an odd integer." , и expected , установленным в null

1. Действия также смогут вызвать обычную ошибку совпадения с помощью функции expected . В качестве параметра будет использоваться описание ожидаемого значения. Эта функция будет предоставлена ​​в основном для удобства в ситуациях, когда не нужно генерировать полное сообщение об ошибке и автоматически генерировать форму «Ожидается _X_, но найдено «2». достаточно.

Исключение SyntaxError , основанное на сбое совпадения, сгенерированном функцией expected , будет аналогично исключениям, основанным на обычном сбое.

Пример

```
начало = знак:[+-]? цифры:[0-9]+ {
var result = parseInt((sign || "") + digits.join(""), 10);

 if (result % 2 == 0) {
   expected("odd integer");
 }

 return result;

}
```

При вводе 2 синтаксический анализатор, сгенерированный из приведенной выше грамматики, выдаст SyntaxError с message , установленным в "Expected odd integer but "2" found." , и expected , установленным в [ { type: "user", description: "odd integer" } ]

Следующие шаги

Я приветствую любые примечания к предлагаемым изменениям — пожалуйста, добавляйте их в качестве комментариев. Я планирую начать реализацию предложения (или какой-то измененной версии на основе отзывов) в ближайшее время.