SKIP_TOKEN return value unintuive

[NaridaL]

There's no CONSUME_ANY_TOKEN in the public API, but you can use SKIP_TOKEN. However that doesn't return the skipped token (which is what I would expect), but rather the token after the skipped token.

Example to skip over all tokens until the next comma

    const skippedTokens = []
    this.MANY({
      GATE: () => this.LA(1).tokenType !== TOKEN.COMMA,
      DEF: () => skippedTokens.push(this.SKIP_TOKEN()),
    })
    this.CONSUME(TOKEN.COMMA)

[bd82]

I think the main problem is that SKIP_TOKEN lacks documentation

In regards to the code snippet.
There is no need to wrap the SKIP_TOKEN with the MANY you can use a simple loop instead.
The only things that must be wrapped with the grammar methods are the grammar methods themselves, e.g CONSUME inside of MANY

SKIP_TOKEN is currently used internally for recovery related logic, I guess in that scenario it made more sense discard the skipped token. Perhaps other utilities should be exposed to make your use case easy to implement?
Although LA(1) provides you with the "next_token" so maybe that is sufficient for your scenario.