IF Commons GitHub

parser

The parser of SQL (commons lang-sql 0002-sql-ast-parser): the tokens of a text, by index, into the tree of ast.ts. Expressions are read by precedence climbing over the binding powers of grammar.ts, with the operators a dialect adds in tables made once for it; statements, clauses and definitions by recursive descent. A statement that cannot be read becomes an unparsed node and an error value, and the parser goes on at the next ;, so a script with one bad statement still gives the others.

The recursive descent signals a failure by throwing a private Failure that script catches at the statement and turns into an error value; nothing is thrown out of parse. Nesting is limited to 200 levels, so that a text of ((((( is an error value and not a stack overflow. A node is made by one object literal, with its fields in the order its interface declares them.

const { script, errors } = parse("SELECT a, count(*) FROM t WHERE a > 1 GROUP BY a");
errors.length; // 0
script.statements[0]?.kind; // "select"

Spec: 0002-sql-ast-parser FR-008, FR-009, FR-010, FR-011, FR-012, FR-013

Source: commons/lang-sql/src/parser.ts

3 of 9 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Fragmentinterfaceno test imports it
interface Fragment<T>

What a read of a range of a text gives: the node, the errors, and the comments of the range, all with offsets of the whole text.

MemberTypeWhat it is
nodeT | undefined
errorsreadonly ParseError[]
commentsreadonly Comment[]
ParseOptionsinterfaceno test imports it
interface ParseOptions

What a parse may be asked.

MemberTypeWhat it is
attach?booleanWhether to attach the comments to nodes (the default); the comments are returned either way.
Parsedinterface
interface Parsed

What a parse gives.

MemberTypeWhat it is
textstring
scriptScript
errorsreadonly ParseError[]Everything that could not be read, in the order of the text: the lexer's errors and the parser's.
commentsreadonly Comment[]Every comment of the text.
attachmentsCommentTableEach comment's node and placement.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

parsefunction
function parse(text: string, dialect?: Dialect, options?: ParseOptions): Parsed

Parses a text.

ParameterWhat it is
textSQL
dialecthow it is written, the base dialect by default
optionswhether to attach the comments

Returns: the script, the errors, the comments and their attachment; it does not throw

Imported by 96 tests of the run (96 passed, 0 failed): the library's results

parseExpressionRangefunctionno test imports it
function parseExpressionRange(text: string, dialect: Dialect, from: number, to: number): Fragment<Expr>

Reads a range of a text as one expression, with offsets of the whole text (commons lang-sql 0006-sql-routines FR-006).

ParameterWhat it is
textthe whole text
dialecthow it is written
fromwhere the range begins
towhere it ends

Returns: the expression, the errors and the comments; it does not throw

parseStatementRangefunctionno test imports it
function parseStatementRange(text: string, dialect: Dialect, from: number, to: number, options?: StatementRangeOptions): Fragment<Statement>

Reads a range of a text as one statement, with offsets of the whole text (commons lang-sql 0006-sql-routines FR-006).

ParameterWhat it is
textthe whole text
dialecthow it is written
fromwhere the range begins
towhere it ends
optionswhether it is a PERFORM, and what to leave out

Returns: the statement, the errors and the comments; it does not throw

parseStrictfunction
function parseStrict(text: string, dialect?: Dialect): Result<Parsed, readonly ParseError[]>

Parses a text that must be read whole.

ParameterWhat it is
textSQL
dialecthow it is written, the base dialect by default

Returns: the parse, or its errors where there is any

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

parseTypeRangefunctionno test imports it
function parseTypeRange(text: string, dialect: Dialect, from: number, to: number): Fragment<DataType>

Reads a range of a text as one data type, with offsets of the whole text.

StatementRangeOptionsinterfaceno test imports it
interface StatementRangeOptions

What parseStatementRange may be given.

MemberTypeWhat it is
perform?booleanWhether the range is a PERFORM: a select that begins at its select list, with no SELECT.
skip?readonly (readonly [number, number])[]Ranges of the text whose tokens are left out, which is how the INTO of a statement is taken out of it.

Titles, headings, exports, tables, columns and requirements. Esc closes.