IF Commons GitHub

Quoting, placeholders and a registry of dialects

0007Active

0007-sql-emit · owner if · domain lang-sql

Quoting

FR-001checkpassing

quoteIdent(dialect, name) MUST give the name written as the dialect's first quoted-identifier syntax writes it (its open quote, the name with the close quote written twice, its close quote) and MUST be an error value for a dialect that has no quoted identifier; identifier(dialect, name) MUST give the name bare where it is a plain lower-case word (letters a to z, digits and _, not beginning with a digit) that is not one of the dialect's keywords, and quoted as quoteIdent quotes it otherwise; qualified(dialect, parts) MUST give the parts joined by ., each as identifier gives it.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/emit.test.ts: an identifier is quoted as the dialect's first syntax writes it, bare only where it is a plain lower-case word that is not a keyword, and a dialect with no quote gives an error value

Proved by: lang-sql/suite/emit.test.ts

Tests: passed: suite/emit.test.ts an identifier is quoted as the dialect's first syntax writes it, bare only where it is a p

Cited by: emit, Lang Sql

FR-002checkpassing

quoteString(dialect, value) MUST give the value written as the dialect's first string syntax writes it: a close quote inside written twice where the escape is double, and a backslash and a close quote each after a backslash where the escape is backslash or both; for the escape none a value that holds the close quote MUST be an error value.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/emit.test.ts: a string is written as the dialect's first string syntax writes it, and a quote that cannot be written inside is an error value

Proved by: lang-sql/suite/emit.test.ts

Tests: passed: suite/emit.test.ts a string is written as the dialect's first string syntax writes it, and a quote that canno

Cited by: emit

FR-003checkpassing

What quoteIdent and quoteString give MUST be read back by the lexer of the same dialect as exactly one token (a quoted identifier, a string) that holds the whole text, for any name or value without a character the lexer reports as an error, in every dialect of this library.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/emit.test.ts: what quoteIdent and quoteString give is read back as exactly one token of the same dialect's lexer, in every dialect

Proved by: lang-sql/suite/emit.test.ts

Tests: passed: suite/emit.test.ts what quoteIdent and quoteString give is read back as exactly one token of the same dialect

Placeholders

FR-004checkpassing

paramStyles(dialect) MUST give the styles of parameter that the dialect reads, in the order its lexical lists them; placeholder(dialect, position, name?) MUST give the text of a parameter of the dialect: for a name, the first of the colon, at and dollar styles the dialect has (:name, @name, $name); for a position (from 1), $n where the dialect has the dollar-number style and ? where it has the question style; and an error value where the dialect has no style that fits (a name where it has no named style, a position where it has no positional one).

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/emit.test.ts: the styles of a dialect are listed, a name takes the colon, at or dollar style, a position takes $n or ?, and a dialect without a fitting style gives an error value

Proved by: lang-sql/suite/emit.test.ts

Tests: passed: suite/emit.test.ts the styles of a dialect are listed, a name takes the colon, at or dollar style, a position

Cited by: emit

FR-005checkpassing

What placeholder gives MUST be read back by the lexer of the same dialect as exactly one token of the kind parameter, in every dialect of this library that has a style that fits.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/emit.test.ts: what placeholder gives is read back as exactly one parameter token of the same dialect's lexer, in every dialect that has a style that fits

Proved by: lang-sql/suite/emit.test.ts

Tests: passed: suite/emit.test.ts what placeholder gives is read back as exactly one parameter token of the same dialect's l

Cited by: emit, Lang Sql

The registry

FR-006checkpassing

createRegistry() MUST give a registry that holds the base dialect ansi and its catalog of functions; register(dialect) MUST add a dialect, found afterwards by get(name) without regard to case, and MUST be an error value where the name is taken (by another dialect) or where the dialect extends a dialect that is not in the registry; registering the same dialect value twice MUST change nothing and succeed; names() MUST give the names in the order of registration.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/registry.test.ts: a registry holds ansi, adds a dialect found by name without regard to case, refuses a name taken or a parent that is not registered, and takes the same dialect twice

Proved by: lang-sql/suite/registry.test.ts

Tests: passed: suite/registry.test.ts a registry holds ansi, adds a dialect found by name without regard to case, refuses a name

Cited by: Lang Sql, registry

FR-007checkpassing

registerFunctions(dialect, functions) MUST add the functions to the catalog of a registered dialect and lookupFunction(dialect, name) MUST find a function by name without regard to case, in the catalog of the dialect first and then in the catalog of each dialect it extends, so that a dialect's function replaces its parent's of the same name; a function whose name is empty, whose smallest number of arguments is more than its largest, or whose dialect is not registered MUST be an error value and MUST change nothing; functionsOf(dialect) MUST give every function the dialect finds, each name once.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/registry.test.ts: functions are registered per dialect, found without regard to case in the dialect and then in those it extends, and a function that cannot be is an error value that changes nothing

Proved by: lang-sql/suite/registry.test.ts

Tests: passed: suite/registry.test.ts functions are registered per dialect, found without regard to case in the dialect and then

Cited by: registry

FR-008checkpassing

None of these functions MUST throw for any value.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/registry.test.ts: no function of the registry or of quoting throws for an unusual value

Proved by: lang-sql/suite/registry.test.ts

Tests: passed: suite/registry.test.ts no function of the registry or of quoting throws for an unusual value

Cited by: Lang Sql, registry

Out of scope

  • Writing a whole statement from a syntax tree, and the rules of a dialect for the case of an unquoted identifier (a name that is not a lower-case word is quoted, so that its case is kept where the engine folds an unquoted one).
  • Checking the call of a function against its catalog.

Edge cases

  • A name with the close quote inside (a"b): written twice, per FR-001.
  • it's in a dialect whose strings are written with a backslash: 'it\'s', per FR-002.
  • A dialect that lists both ? and $n: $n for a position, per FR-004.

Assumptions

  • A parameter of the question style is written ?, one of the dollar-number style $1, and a position is from 1.

Open questions

  • None.

Key entities

  • Quoting - the functions that write an identifier or a string as a dialect does.
  • Placeholder - the text of a parameter in a dialect.
  • Registry - the dialects registered, with the catalog of functions of each.

Success criteria

SC-001success criterion

A library outside this one builds a statement for any dialect, and registers a dialect of its own, without writing a quote or a placeholder by hand.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

emit, Lang Sql, print, registry, Lang Sql, The printer and unit literals

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