Document the error.format() method - how is this supposed to work?

[AndrewRayCode]

The documentation says:

Both of these errors have the format() method that takes an array of mappings from source to grammar text: console.log(e.format([ { source, text }, { source: source2, text: input }, ... ]));

What does this mean? What is a mapping from source to grammar? Why is it an array?

lib/peg.d.ts says

/**
 * The entry that maps object in the `source` property of error locations
 * to the actual source text of a grammar. That entries is necessary for
 * formatting errors.
 */
export interface SourceText {
  /**
   * Identifier of a grammar that stored in the `location().source` property
   * of error and diagnostic messages.
   *
   * This one should be the same object that used in the `location().source`,
   * because their compared using `===`.
   */
  source: any;

What does this mean? What is an "identifier of a grammar"?

Why does format require an array argument? Doesn't it already have error location information, and source lexeme information, to generate a useful error message?

The error will have a format(SourceText[]) function, to which you pass an array of objects that look like { source: grammarSource, text: string }; this will return a nicely-formatted error suitable for human consumption.

It doesn't for me, and I'm not sure how it's supposed to work.

  try {
    return parser.parse(src, {
      ...options,
      grammarSource: '<anonymous glsl>',
    });
  } catch (e) {
    console.error((e as GrammarError).format([{ source: src, text: src }]));
    throw e;
  }

This logs:

 Error: Expected ";" or "{" but "_" found.
  at <anonymous glsl>:4:17

Which doesn't have any of the ^^^^^ / --> ASCII arrows promised in the documentation.

I'd like to update the documentation on this function as well, but I'm not yet sure what the API is trying to convey.

[Mingun]

Which doesn't have any of the ^^^^^ / --> ASCII arrows promised in the documentation.

This is because source is a key, that should match grammarSource in options

What is an "identifier of a grammar"?

Literally, this is an identifier, like <anonymous glsl> in your case.

Why is it an array?

Locations in generated errors can have different sources. Well, right now, because #298 does not yet implemented, the source is always one.

Why does format require an array argument? Doesn't it already have error location information, and source lexeme information, to generate a useful error message?

It contains positions in some input, but not the input itself. To show you pretty printed error with a part of the input you should provide it somehow.

[hildjj]

Does #382 fix this adequately for you yet?

[AndrewRayCode]

@Mingun ah that makes sense. The array thing confused me. Your reply gave me enough information to open https://github.com/peggyjs/peggy/pull/389/files

[hildjj]

Fixed in #389