Expand docs for lexical structure

- Add details about decimal, hexadecimal, octal, and binary literals - Add docs for comments - Add info about identifiers - Add info about underscore usage in literals Co-authored by: Manfred Moser <[email protected]>
trinodb · Aug 31, 2023 · 3ed11fd · 3ed11fd
1 parent f343fff
commit 3ed11fd
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 13 deletions.
diff --git a/docs/src/main/sphinx/language/reserved.md b/docs/src/main/sphinx/language/reserved.md
@@ -1,4 +1,7 @@
-# Reserved keywords
+# Keywords and identifiers
+
+(language-keywords)=
+## Reserved keywords
 
 The following table lists all of the keywords that are reserved in Trino,
 along with their status in the SQL standard. These reserved keywords must
@@ -89,3 +92,34 @@ be quoted (using double quotes) in order to be used as an identifier.
 | `WHERE`             | reserved | reserved |
 | `WITH`              | reserved | reserved |
 
+(language-identifiers)=
+## Identifiers
+
+Tokens that identify names of catalogs, schemas, tables, columns, functions, or
+other objects, are identifiers.
+
+Identifiers must start with a letter, and subsequently include alphanumeric
+characters and underscores. Identifiers with other characters must be delimited
+with double quotes (`"`). When delimited with double quotes, identifiers can use
+any character. Escape a `"` with another preceding double quote in a delimited
+identifier.
+
+Identifiers are not treated as case sensitive.
+
+Following are some valid examples:
+
+```sql
+tablename
+SchemaName
+example_catalog.a_schema."table$partitions"
+"identifierWith""double""quotes"
+```
+
+The following identifiers are invalid in Trino and must be quoted when used:
+
+```text
+table-name
+123SchemaName
+colum$name@field
+```
+
diff --git a/docs/src/main/sphinx/language/types.md b/docs/src/main/sphinx/language/types.md
@@ -41,31 +41,55 @@ This type captures boolean values `true` and `false`.
 
 ## Integer
 
+Integer numbers can be expressed as numeric literals in the following formats:
+
+* Decimal integer. Examples are `-7`, `0`, or `3`.
+* Hexadecimal integer composed of `0X` or `0x` and the value. Examples are
+  `0x0A` for decimal `10` or `0x11` for decimal `17`.
+* Octal integer composed of `0O` or `0o` and the value. Examples are `0o40` for
+  decimal `32` or `0o11` for decimal `9`.
+* Binary integer composed of `0B` or `0b` and the value. Examples are `0b1001`
+  for decimal `9` or `0b101010` for decimal `42``.
+
+Underscore characters are ignored within literal values, and can be used to
+increase readability. For example, decimal integer `123_456.789_123` is
+equivalent to `123456.789123`. Preceding and trailing underscores are not
+permitted.
+
+Integers are supported by the following data types.
+
 ### `TINYINT`
 
 A 8-bit signed two's complement integer with a minimum value of
-`-2^7` and a maximum value of `2^7 - 1`.
+`-2^7` or `-0x80` and a maximum value of `2^7 - 1` or `0x7F`.
 
 ### `SMALLINT`
 
 A 16-bit signed two's complement integer with a minimum value of
-`-2^15` and a maximum value of `2^15 - 1`.
+`-2^15` or `-0x8000` and a maximum value of `2^15 - 1` or `0x7FFF`.
 
-### `INTEGER`
+### `INTEGER` or `INT`
 
-A 32-bit signed two's complement integer with a minimum value of
-`-2^31` and a maximum value of `2^31 - 1`.  The name `INT` is
-also available for this type.
+A 32-bit signed two's complement integer with a minimum value of `-2^31` or
+`-0x80000000` and a maximum value of `2^31 - 1` or `0x7FFFFFFF`.  The names
+`INTEGER` and `INT` can both be used for this type.
 
 ### `BIGINT`
 
-A 64-bit signed two's complement integer with a minimum value of
-`-2^63` and a maximum value of `2^63 - 1`.
+A 64-bit signed two's complement integer with a minimum value of `-2^63` or
+`-0x8000000000000000` and a maximum value of `2^63 - 1` or `0x7FFFFFFFFFFFFFFF`.
 
 (floating-point-data-types)=
 
 ## Floating-point
 
+Floating-point, fixed-precision numbers can be expressed as numeric literal
+using scientific notation such as `1.03e1` and are cast as `DOUBLE` data type.
+Underscore characters are ignored within literal values, and can be used to
+increase readability. For example, value `123_456.789e4` is equivalent to
+`123456.789e4`. Preceding underscores, trailing underscores, and underscores
+beside the comma (`.`) are not permitted.
+
 ### `REAL`
 
 A real is a 32-bit inexact, variable-precision implementing the
@@ -84,9 +108,20 @@ Example literals: `DOUBLE '10.3'`, `DOUBLE '1.03e1'`, `10.3e0`, `1.03e1`
 
 ## Fixed-precision
 
+Fixed-precision numbers can be expressed as numeric literals such as `1.1`, and
+are supported by the `DECIMAL` data type.
+
+Underscore characters are ignored within literal values, and can be used to
+increase readability. For example, decimal `123_456.789_123` is equivalent to
+`123456.789123`. Preceding underscores, trailing underscores, and underscores
+beside the comma (`.`) are not permitted.
+
+Leading zeros in literal values are permitted and ignored. For example,
+`000123.456` is equivalent to `123.456`.
+
 ### `DECIMAL`
 
-A fixed precision decimal number. Precision up to 38 digits is supported
+A fixed-precision decimal number. Precision up to 38 digits is supported
 but performance is best up to 18 digits.
 
 The decimal type takes two literal parameters:
@@ -134,9 +169,13 @@ Example type definitions: `char`, `char(20)`
 
 Variable length binary data.
 
-SQL statements support usage of binary data with the prefix `X`. The
-binary data has to use hexadecimal format. For example, the binary form of
-`eh?` is `X'65683F'`.
+SQL statements support usage of binary literal data with the prefix `X` or `x`.
+The binary data has to use hexadecimal format. For example, the binary form of
+`eh?` is `X'65683F'` as you can confirm with the following statement:
+
+```sql
+SELECT from_utf8(x'65683F');
+```
 
 :::{note}
 Binary strings with length are not yet supported: `varbinary(n)`

diff --git a/docs/src/main/sphinx/sql.md b/docs/src/main/sphinx/sql.md
@@ -16,6 +16,7 @@ sql/alter-view
 sql/analyze
 sql/call
 sql/comment
+sql/comments
 sql/commit
 sql/create-materialized-view
 sql/create-role

diff --git a/docs/src/main/sphinx/sql/comment.md b/docs/src/main/sphinx/sql/comment.md
@@ -29,3 +29,7 @@ Change the comment for the `users.name` column to be `full name`:
 ```
 COMMENT ON COLUMN users.name IS 'full name';
 ```
+
+## See also
+
+[](./comments)
diff --git a/docs/src/main/sphinx/sql/comments.md b/docs/src/main/sphinx/sql/comments.md
@@ -0,0 +1,26 @@
+# Comments
+
+## Synopsis
+
+Comments are part of a SQL statement or script that are ignored for processing.
+Comments begin with double dashes and extend to the end of the line. Block
+comments begin with `/*` and extend to the next occurrence of `*/`, possibly
+spanning over multiple lines.
+
+## Examples
+
+The following example displays a comment line, a comment after a valid
+statement, and a block comment:
+
+```sql
+-- This is a comment.
+SELECT * FROM table; -- This comment is ignored.
+
+/* This is a block comment
+   that spans multiple lines
+   until it is closed. */
+```
+
+## See also
+
+[](./comment)