# gizmodel/sql/parse

The SQL parser: recursive descent over lex.giz's tokens into ast.giz's nodes. It accepts the union of the dialects' syntax where they do not collide (LIMIT, TOP, FETCH FIRST and ROWNUM limits; `::` and CAST; || and CONCAT; $1, ?, :name and @name parameters; [ ], " " and ` ` identifiers), so a statement written for SQLite, PostgreSQL, SQL Server or Oracle reads as the same tree. Keywords are case-insensitive; identifiers keep their spelling and are compared case-insensitively by the binder.

```gizlang
import * as Parse from "gizmodel/sql/parse";
```

## Functions

### `parse`

```gizlang
function parse(sql: string): Vec<Statement> throws string
```

Every statement of `sql`, or the first syntax error. The parser runs inside a fault boundary (Task.contained): a
runtime fault of it fails this text as a syntax error does, not the caller's loop with every session on it.

Effects: fail, read, alloc.

### `relationText`

```gizlang
function relationText(text: string, dialect: string): string
```

The stored name of the relation TEXT names as regclass input does ('"public"."s"', 'App.S'): an unquoted part
folded to lowercase, a quoted one as engineNameOf keeps it, then kept. TEXT lowercased when it is no such name.

Effects: fail, alloc.

### `schemaOfName`

```gizlang
function schemaOfName(name: string, home: string): string
```

The schema of a name as kept stores it: its prefix, or `home` for an unqualified one.

Effects: fail, alloc.

### `bareName`

```gizlang
function bareName(name: string): string
```

A name as kept stores it, without its schema.

Effects: fail, alloc.

### `shownName`

```gizlang
function shownName(physical: string): string
```

A stored relation's name as PostgreSQL shows it: without its schema, and a temporary one (pg_temp_STAMP_NAME,
pg_temp_vSTAMP_NAME, or pg_temp_STAMP_K_NAME when another table took the name, Conn.work) without its prefix.

Effects: fail, alloc.

### `normalType`

```gizlang
function normalType(t0: string): string
```

A type name as the catalog keys it: lower case, single spaces, PostgreSQL's internal names for the usual aliases.

Effects: fail, alloc.

### `pivotQuery`

```gizlang
function pivotQuery(f: From, names: Vec<string>): From
```

The query of a pivot FROM item (Parser.pivoted) over a source of visible columns `names`: the columns that no
aggregate and no FOR column reads are the groups, and each IN row and aggregate is a column, its aggregate taking
only the rows of that row's values. A column is named by the row's name, then _ and the aggregate's alias.

Effects: fail, alloc.

### `unpivotQuery`

```gizlang
function unpivotQuery(f: From, names: Vec<string>): From
```

The query of an unpivot FROM item (Parser.pivoted) over a source of visible columns `names`: for each IN row, the
columns it does not name, its label in each FOR column (the IN columns' names in uppercase without one) and its
columns as the values; UNION ALL of them. EXCLUDE NULLS (the default) drops a row whose values are all NULL.

Effects: fail, alloc.

### `numberValue`

```gizlang
function numberValue(text: string): Value
```

A number literal: an integer when it fits, else a decimal, else a float. 0x, 0o and 0b literals are integers too.

Effects: fail, alloc.

### `hasExpr`

```gizlang
function hasExpr(xs: Vec<Expr>, x: Expr): bool
```

Whether XS holds an expression that is the same as X.

Effects: fail, alloc.

### `sameExpr`

```gizlang
function sameExpr(a: Expr, b: Expr): bool
```

Whether expressions A and B are the same tree.

Effects: fail, alloc.

### `arrayOf`

```gizlang
function arrayOf(query: Vec<Select>, fields: Vec<string>, joiner: string): Expr
```

The array of a query's rows, (SELECT array_agg(v) FROM (query) AS _array(v)); an empty result is the empty array. A query
of several columns, named `fields`, gives a ROW of them for each element.

Effects: fail, alloc.

### `valuesCte`

```gizlang
function valuesCte(name: string, columns: Vec<string>, rows: Vec<Vec<Value>>): Cte
```

CTE `name` over rows already computed (a data-modifying CTE's RETURNING rows).

Effects: fail, alloc.

### `withInlined`

```gizlang
function withInlined(s0: Statement, ctes: Vec<Cte>): Statement
```

`s` with the CTEs `ctes` visible: each query in it takes them, and a FROM item that names one reads it.

Effects: fail, alloc.

### `syntaxError`

```gizlang
function syntaxError(message0: string): DbError
```

The error a parse message gives: its own SQLSTATE (Parser.failCode), else a syntax error.

Effects: fail, alloc.

### `conjuncts`

```gizlang
function conjuncts(e: Expr, out: mut Vec<Expr>): void
```

The terms of conjunction E, in order, into OUT: E itself when it is not an AND.

Effects: fail, alloc.

### `hasAggregate`

```gizlang
function hasAggregate(x: Expr, windows: bool): bool
```

Whether `x` calls an aggregate outside a subquery's own scope; `windows`: also one with OVER.
The one test that binding (grouping) and SQL function inlining use.

Effects: fail, alloc.

### `unwrapped`

```gizlang
function unwrapped(text: string): string
```

`text` without parentheses around all of it: "(1)" is "1", "(a) + (b)" stays.

Effects: fail, alloc.

## Methods

### `Parser.expression`

```gizlang
function Parser.expression(self: mut Parser): Expr
```

Parses one expression.

Effects: fail, read, alloc.

