Fast and easy parser of statements in source code in any language.
parse-statements ✂️ allows you to parse statements consisting of a sequence of tokens
with arbitrary text between them. Statements cannot overlap.
In addition to statements, language comments can be described, which can also be located
inside statements (between its neighboring tokens).
Strings are used to describe (find) tokens, from which regexps with gmu flags
(by default, but flags can be overridden in the parser options) are generated.
Therefore, the backslash in these lines must be escaped, that is, it must be doubled.
For each parsed statement, the optional onParse callback is called with the context,
source code (string), and an array of tokens of statement
(and an array of comments between this token and the next one, if any).
If the sequence of tokens of statement has not completed, instead of the onParse callback,
an onError callback with the same signature is called, receiving an incomplete sequence
of parsed tokens of statement.
Similar optional callbacks can be set for comments.
Callbacks for statements (only for statements, not for comments) can return a number
instead of an undefined — then this number will be used as an index at the source code,
starting from which the parser will find the next statement.
In fact, this index will be interpreted as the end of the statement. By default,
the end of the statement coincides with the end of its last token,
but sometimes we may need to go beyond the boundaries of the found tokens
(or, conversely, reduce the length of the statement, that is, reduce its end index).
With such manual parsing, if we increase the index of the end of the statement,
we must remember to manually parse the comments that may appear
in this part of the statement — because the parser itself will not do this.
It will continue to work from the new end of the statement as usual.
Basic example
Below is a simplified example (see on TypeScript Playground)
of parsing import and export statements in ECMAScript
(a complete example can be found here):
import {createParseFunction} from 'parse-statements';import type {OnCommentError, OnCommentParse, OnParse} from 'parse-statements';const throwError: (message: string) => never = (message) => { throw new Error(message);};type Context = Readonly<{ errors: unknown[]; exports: [exports: string, ...comments: string[]][]; imports: [import: string, ...
The options object defines comments, statements, RegExp flags and a global error callback handler
(all of these fields are optional):
import type {Comment, OnGlobalError, Options, ParsedToken, Statement} from 'parse-statements';const options: Options<Context> = { comments, // an optional array of comments onError, // an optional callback handler for global parsing errors regexpFlags: 'gmu', // an optional `RegExp` flags used to create all regexps (defaults to `'gmu'`) statements, // an optional array of statements};const comments: readonly Comment<Context>[] = [ { onError( context: Context, source: string, parsedToken: {start:
parse-statements ✂️ also exports all types included in the API:
export type { /** * Description of comment as the callback handlers and open and close tokens. */ Comment, /** * Pair of the comment open and close tokens (raw or parsed). */ CommentPair, /** * `onError` callback handler for error on comment parsing. */ OnCommentError, /** * `onParse` callback handler of comment. */ OnCommentParse, /** * Global `onError` callback handler for error on parsing. */ OnGlobalError, /** * `onParse` callback handler of statement with concrete length (number of tokens). */ OnParse, /** * Options of `createParseFunction` function. */ Options,