SQLite Requirements

*** DRAFT ***

1.0 About SQLite Requirements

Requirements consist of excerpts from the documentation. A requirement is usually a one-sentence excerpt but might be a sentence fragment, multiple sentences, a table, or a GIF image of a bubble syntax diagram.
Requirements are written in conversational English and without the modal auxiliary verb "shall". This grows out of the fact that requirements are taken from the documentation. The intended audience for the documentation is application programmers. "Shall" language is appropriate when the audience consists of contract specialists, QA auditors, and lawyers, but it interferes with comprehension when the audience is application programmers. Hence, in order to best serve the intended audience, the "shall" language is omitted.
Requirements are sufficiently detailed and precise to permit a 100% compatible clean-room reimplementation of SQLite.
The word "requirement" in common English usage implies an ordering: that the requirement comes before the implementation. But there is no such ordering with SQLite requirements. What are called "requirements" in SQLite are better described as "testable statements of truth about the behavior of the system".
Every testable statement of truth about SQLite in the documentation becomes a requirement.
Requirement numbers are the MD5 hash of the requirement itself.
1. Requirements are inherently immutable, since any change to the requirement results in a completely different requirement number.
2. For text requirements, the text is normalized prior to computing the MD5 hash:
  - Remove all leading and trailing whitespace.
  - Convert all internal whitespace sequences to a single space character.
  - Convert "<" to "<", ">" to ">", "[" to "[", "]" to "]", and "&" to "&".
3. For GIF syntax diagram requirements, the MD5 hash is computed over the entire content of the GIF image file.
4. The MD5 hash is expressed in human-readable form as follows:
  R-N-N-N-N-N-N-N-N
  Where each N is a 5-digit number between 00000 and 65536 that represents 16 bits of the 128-bit MD5 hash.
5. Requirements may be referenced by any unique prefix of their complete requirement number.
Individual text requirements are identified in the documentation as text between "^" and the first period or full-stop (".") or as text between "^(" and ")^".
1. Text requirements are automatically extracted from the documentation by scripts that run as part of the documentation build process.
2. After requirements have been extracted from the documentation, the requirement markers "^", "^(", and ")^" are removed from the documentation text. This is done automatically by the documentation build scripts.
3. To avoid collisions with these requirements delimiters, "^" characters that are part of the text of a requirement or that are otherwise found in the documentation, should be coded as "^".
Individual GIF syntax diagram requirements are identified in the documentation as HTML image markup of the form
<img alt="syntax diagram NAME" src="FILE">
Where NAME is the name of the syntax diagram and FILE is the name of the GIF file containing the syntax diagram.
1. Syntax diagram requirements are automatically extracted from the documentation by scripts that run as part of the documentation build process.
2. The GIF file is the requirement, not the HTML markup that references the GIF file nor the diagram name.
The documentation that contains the requirement text is generated by scripts that take their input from files in the documentation fossil repository as well as comments in the source code.

2.0 List Of Requirements

This page last modified on 2025-06-12 09:10:23 UTC

*** DRAFT ***