# gizdb:sql/types/dialect

A SQL dialect as a value: its name and the rules where the engines it imitates differ in meaning, not spelling. A rule that many modules read is a field (`d.emptyIsNull`), so a new dialect is a new value here. A quirk of one function reads `name` in that function (Oracle's substr of position 0, SQL Server's natural log), and so do PostgreSQL's own types, catalogs and errors (xid, inet, pg_lsn, timetz, pg_catalog, 42P01). Spellings that mean the same in every dialect (lcase, getdate, nvl) are one vocabulary the parser and function library accept everywhere.

```gizlang
import * as Dialect from "gizdb:sql/types/dialect";
```

## Types

### `Dialect`

```gizlang
type Dialect = { name: string; emptyIsNull: bool; affinity: bool; exactDivision: bool; plusConcats: bool; dateIsTimestamp: bool; dateIntervalTimestamp: bool; boolWords: bool; nullsLargest: bool; likeCaseless: bool; bareGroupColumns: bool; abortsOnError: bool; isolation: string; schema: string; zone: string; exprLabels: bool; oraErrors: bool; bareFraction: bool; implicitCommit: bool; trimsDecimals: bool; dateOrder: i64; clock: i64; }
```

name: postgres, oracle, mssql, sqlite or mysql.
- emptyIsNull: '' is NULL (Oracle): a text function's empty result is NULL, || skips NULL.
- affinity: SQLite's dynamic typing: casts take a numeric prefix and truncate, a column keeps
  what does not convert, dates are plain text, reals print with 15 digits, x/0 is NULL.
- exactDivision: integer / integer is exact when it does not divide evenly (Oracle's NUMBER).
- plusConcats: + of text joins it (SQL Server).
- dateIsTimestamp: DATE holds a time of day too (Oracle); date - date is a number of days.
- dateIntervalTimestamp: a date plus an interval of whole days is a timestamp (PostgreSQL).
- boolWords: a boolean as text is true/false (PostgreSQL), else 1/0.
- nullsLargest: NULL sorts after every value ascending (PostgreSQL, Oracle).
- likeCaseless: LIKE ignores ASCII case (SQLite, MySQL).
- bareGroupColumns: a grouped query may name a column outside GROUP BY (SQLite, MySQL).
- abortsOnError: an error inside BEGIN fails the transaction until ROLLBACK, and BEGIN or
  COMMIT out of place only warn (PostgreSQL).
- isolation: what BEGIN starts (Tx.isolation).
- schema: the default schema's name.
- zone: the session's TimeZone as SET gave it ("" is UTC): timestamptz values print and read in it.
- bareFraction: a number as text has no 0 before its point, .4 and -.4 (Oracle's TO_CHAR and
  implicit conversion).
- trimsDecimals: a decimal keeps no scale of its own, 2.50 is 2.5 (Oracle's NUMBER).
- implicitCommit: DDL commits the open transaction, then itself at once, and COMMIT or ROLLBACK
  with none open does nothing (Oracle).
- oraErrors: an error's message starts with Oracle's number, ORA-00001: ... (the PG server).
- exprLabels: a result column is labeled as Oracle labels it: identifiers in uppercase, an
  unaliased expression by its text, uppercased without whitespace (NVL(A,'X')).

- `name`: `string`
- `emptyIsNull`: `bool`
- `affinity`: `bool`
- `exactDivision`: `bool`
- `plusConcats`: `bool`
- `dateIsTimestamp`: `bool`
- `dateIntervalTimestamp`: `bool`
- `boolWords`: `bool`
- `nullsLargest`: `bool`
- `likeCaseless`: `bool`
- `bareGroupColumns`: `bool`
- `abortsOnError`: `bool`
- `isolation`: `string`
- `schema`: `string`
- `zone`: `string`
- `exprLabels`: `bool`
- `oraErrors`: `bool`
- `bareFraction`: `bool`
- `implicitCommit`: `bool`
- `trimsDecimals`: `bool`
- `dateOrder`: `i64` — The order of a date's numbers in input (DateStyle): 0 month-day-year, 1 day-month-year, 2 year-month-day.
- `clock`: `i64` — The statement's wall clock in microseconds (0 when unknown): PostgreSQL's 'now', 'today', 'tomorrow' and 'yesterday' inputs read it.

## Functions

### `sameDialect`

```gizlang
function sameDialect(a: Dialect, b: Dialect): bool
```

Names do not certify customized dialect flags; prepared sources must agree on all semantics.

### `dialectOf`

```gizlang
function dialectOf(name: string): Dialect
```

The dialect named `name` (case ignored); PostgreSQL's for a name it does not know.

Effects: fail.

### `knownDialect`

```gizlang
function knownDialect(name: string): bool
```

Whether `name` names a dialect `dialectOf` knows.

Effects: fail.

### `boolText`

```gizlang
function boolText(d: Dialect, x: bool): string
```

A boolean as a client of the dialect prints it: t and f (PostgreSQL), TRUE and FALSE (Oracle), else 1 and 0.

### `arrayWord`

```gizlang
function arrayWord(s: string): string
```

One element of an array's text as PostgreSQL writes it: in double quotes, with a backslash before each quote and
backslash, when it is empty, spells NULL, or holds a delimiter, a brace, a quote, a backslash or a space.

Effects: fail.

## Methods

### `Dialect.storageType`

```gizlang
function Dialect.storageType(self: Dialect, ty: Type, width: i64): string
```

DDL spelling for the typed physical representation. Logical widths enter
here once; callers do not maintain their own storage type registries.

Effects: fail.