F051-06, F051-07, F051-08: Basic dates and times (#110)

Adding support for:

1. F051-06: CURRENT_DATE
2. F051-07: LOCALTIME
3. F051-08: LOCALTIMESTAMP

Starting to migrate docs into a new structure, starting with
"Dates and Times".

docs/data-types.rst

@@ -85,101 +85,7 @@ is an alias for ``CHARACTER(1)``.
 Date and Time Types
 -------------------
 
-``DATE``
-^^^^^^^^
-
-A ``DATE`` holds a year-month-day value, such as ``2010-10-25``.
-
-A ``DATE`` value can be created with the ``DATE '2010-10-25'`` literal
-expression.
-
-Valid date ranges are between ``0000-01-01`` and ``9999-12-31``.
-
-A ``DATE`` is stored as 8 bytes.
-
-``TIME(n) WITH TIME ZONE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Holds a time as hour-minute-second-timezone (without respect to a date),
-for example: ``15:12:47+05:30``.
-
-The ``(n)`` describes the sub-second resolution to be stored. It must be
-inclusively between 0 (whole seconds) and 6 (microseconds). If omitted, 0 is
-used.
-
-A ``TIME(n) WITH TIME ZONE`` value is created with the ``TIME 'VALUE'`` literal
-expression. The ``VALUE`` itself will determine whether the time has a time zone
-and its precision. For example:
-
-.. list-table::
-  :header-rows: 1
-
-  * - Expr
-    - Type
-
-  * - ``TIME '15:12:47'``
-    - ``TIME(0) WITHOUT TIME ZONE``
-
-  * - ``TIME '15:12:47.123'``
-    - ``TIME(3) WITHOUT TIME ZONE``
-
-  * - ``TIME '15:12:47+05:30'``
-    - ``TIME(0) WITH TIME ZONE``
-
-  * - ``TIME '15:12:47.000000+05:30'``
-    - ``TIME(6) WITH TIME ZONE``
-
-A ``TIME WITH TIME ZONE`` (with any precision) is stored as 10 bytes.
-
-``TIME(n) WITHOUT TIME ZONE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This works the same way as ``TIME(n) WITH TIME ZONE`` except there is no
-time zone component.
-
-A ``TIME WITHOUT TIME ZONE`` (with any precision) is stored as 8 bytes.
-
-``TIMESTAMP(n) WITH TIME ZONE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Holds a timestamp as year-month-day-hour-minute-second-timezone, for example:
-``2010-10-25 15:12:47+05:30``.
-
-The ``(n)`` describes the sub-second resolution to be stored. It must be
-inclusively between 0 (whole seconds) and 6 (microseconds). If omitted, 6 is
-used. This is different from the behavior of ``TIME`` that uses 0 by default.
-
-A ``TIMESTAMP(n) WITH TIME ZONE`` value is created with the
-``TIMESTAMP 'VALUE'`` literal expression. The ``VALUE`` itself will determine
-whether the timestamp has a time zone and its precision. For example:
-
-.. list-table::
-  :header-rows: 1
-
-  * - Expr
-    - Type
-
-  * - ``TIMESTAMP '2010-10-25 15:12:47'``
-    - ``TIMESTAMP(0) WITHOUT TIME ZONE``
-
-  * - ``TIMESTAMP '2010-10-25 15:12:47.123'``
-    - ``TIMESTAMP(3) WITHOUT TIME ZONE``
-
-  * - ``TIMESTAMP '2010-10-25 15:12:47+05:30'``
-    - ``TIMESTAMP(0) WITH TIME ZONE``
-
-  * - ``TIMESTAMP '2010-10-25 15:12:47.000000+05:30'``
-    - ``TIMESTAMP(6) WITH TIME ZONE``
-
-A ``TIMESTAMP WITH TIME ZONE`` (with any precision) is stored as 10 bytes.
-
-``TIMESTAMP(n) WITHOUT TIME ZONE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This works the same way as ``TIMESTAMP(n) WITH TIME ZONE`` except there is no
-time zone component.
-
-A ``TIMESTAMP WITHOUT TIME ZONE`` (with any precision) is stored as 8 bytes.
+See :doc:`dates-times`.
 
 Unsupported Data Types
 ----------------------

docs/dates-times.rst

@@ -0,0 +1,164 @@
+Dates and Times
+===============
+
+.. contents::
+
+SQL Types
+---------
+
+DATE
+^^^^
+
+A ``DATE`` holds a year-month-day value, such as ``2010-10-25``.
+
+A ``DATE`` value can be created with the ``DATE '2010-10-25'`` literal
+expression.
+
+Valid date ranges are between ``0000-01-01`` and ``9999-12-31``.
+
+A ``DATE`` is stored as 8 bytes.
+
+TIME(n) WITH TIME ZONE
+^^^^^^^^^^^^^^^^^^^^^^
+
+Holds a time as hour-minute-second-timezone (without respect to a date),
+for example: ``15:12:47+05:30``.
+
+The ``(n)`` describes the sub-second resolution to be stored. It must be
+inclusively between 0 (whole seconds) and 6 (microseconds). If omitted, 0 is
+used.
+
+A ``TIME(n) WITH TIME ZONE`` value is created with the ``TIME 'VALUE'`` literal
+expression. The ``VALUE`` itself will determine whether the time has a time zone
+and its precision. For example:
+
+.. list-table::
+  :header-rows: 1
+
+  * - Expr
+    - Type
+
+  * - ``TIME '15:12:47'``
+    - ``TIME(0) WITHOUT TIME ZONE``
+
+  * - ``TIME '15:12:47.123'``
+    - ``TIME(3) WITHOUT TIME ZONE``
+
+  * - ``TIME '15:12:47+05:30'``
+    - ``TIME(0) WITH TIME ZONE``
+
+  * - ``TIME '15:12:47.000000+05:30'``
+    - ``TIME(6) WITH TIME ZONE``
+
+A ``TIME WITH TIME ZONE`` (with any precision) is stored as 10 bytes.
+
+TIME(n) WITHOUT TIME ZONE
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This works the same way as ``TIME(n) WITH TIME ZONE`` except there is no
+time zone component.
+
+A ``TIME WITHOUT TIME ZONE`` (with any precision) is stored as 8 bytes.
+
+TIMESTAMP(n) WITH TIME ZONE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Holds a timestamp as year-month-day-hour-minute-second-timezone, for example:
+``2010-10-25 15:12:47+05:30``.
+
+The ``(n)`` describes the sub-second resolution to be stored. It must be
+inclusively between 0 (whole seconds) and 6 (microseconds). If omitted, 6 is
+used. This is different from the behavior of ``TIME`` that uses 0 by default.
+
+A ``TIMESTAMP(n) WITH TIME ZONE`` value is created with the
+``TIMESTAMP 'VALUE'`` literal expression. The ``VALUE`` itself will determine
+whether the timestamp has a time zone and its precision. For example:
+
+.. list-table::
+  :header-rows: 1
+
+  * - Expr
+    - Type
+
+  * - ``TIMESTAMP '2010-10-25 15:12:47'``
+    - ``TIMESTAMP(0) WITHOUT TIME ZONE``
+
+  * - ``TIMESTAMP '2010-10-25 15:12:47.123'``
+    - ``TIMESTAMP(3) WITHOUT TIME ZONE``
+
+  * - ``TIMESTAMP '2010-10-25 15:12:47+05:30'``
+    - ``TIMESTAMP(0) WITH TIME ZONE``
+
+  * - ``TIMESTAMP '2010-10-25 15:12:47.000000+05:30'``
+    - ``TIMESTAMP(6) WITH TIME ZONE``
+
+A ``TIMESTAMP WITH TIME ZONE`` (with any precision) is stored as 10 bytes.
+
+TIMESTAMP(n) WITHOUT TIME ZONE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This works the same way as ``TIMESTAMP(n) WITH TIME ZONE`` except there is no
+time zone component.
+
+A ``TIMESTAMP WITHOUT TIME ZONE`` (with any precision) is stored as 8 bytes.
+
+Current Date and Time
+---------------------
+
+CURRENT_DATE
+^^^^^^^^^^^^
+
+Provides the current date (eg. ``2022-03-24``) within the time zone of the
+session as a ``DATE`` type.
+
+CURRENT_TIME(p)
+^^^^^^^^^^^^^^^
+
+Provides the time with the timezone (eg. ``15:45:55+05:00``) within the time
+zone of the session as a ``TIME(p) WITH TIME ZONE`` type.
+
+The ``(p)`` is optional and if not provided will use a value of ``0``.
+Otherwise, the value of ``p`` must be between ``0`` and ``6`` and controls both
+the subsecond accuracy and result type.
+
+``CURRENT_TIME`` differs from ``LOCALTIME`` which returns the same time
+component, but without the time zone.
+
+CURRENT_TIMESTAMP(p)
+^^^^^^^^^^^^^^^^^^^^
+
+Provides the date and time with the timezone (eg. ``2022-03-24 15:45:55+05:00``)
+within the time zone of the session as a ``TIMESTAMP WITH TIME ZONE`` type.
+
+The ``(p)`` is optional and if not provided will use a value of ``6``.
+Otherwise, the value of ``p`` must be between ``0`` and ``6`` and controls both
+the subsecond accuracy and result type.
+
+``CURRENT_TIMESTAMP`` differs from ``LOCALTIMESTAMP`` which returns the same
+date and time component, but without the time zone.
+
+LOCALTIME(p)
+^^^^^^^^^^^^
+
+Provides the time with the time zone (eg. ``15:45:55``) within the time zone
+of the session as a ``TIME(p) WITHOUT TIME ZONE`` type.
+
+The ``(p)`` is optional and if not provided will use a value of ``0``.
+Otherwise, the value of ``p`` must be between ``0`` and ``6`` and controls both
+the subsecond accuracy and result type.
+
+``LOCALTIME`` differs from ``CURRENT_TIME`` which returns the same time
+component, but also includes the time zone.
+
+LOCALTIMESTAMP(p)
+^^^^^^^^^^^^^^^^^
+
+Provides the date and time without the time zone (eg. ``2022-03-24 15:45:55``)
+within the time zone of the session as a ``TIMESTAMP WITHOUT TIME ZONE`` type.
+
+The ``(p)`` is optional and if not provided will use a value of ``6``.
+Otherwise, the value of ``p`` must be between ``0`` and ``6`` and controls both
+the subsecond accuracy and result type.
+
+``LOCALTIMESTAMP`` differs from ``CURRENT_TIMESTAMP`` which returns the same
+date and time component, but includes the time zone.

docs/faq.rst

@@ -52,3 +52,10 @@ V code that makes up the parser. The result file ``grammar.v`` is committed so
 there is no need to use python to compile and otherwise work on vsql unless you
 need to change the grammar. However, if you would like to covert this script to
 V, I'd be happy to have your help!
+
+Why is there no `NOW()` function?
+---------------------------------
+
+The ``NOW()`` function commonly found in other databases is not actually part of
+the SQL standard. Instead you must use one off ``CURRENT_TIMESTAMP(p)`` or
+``LOCALTIMESTAMP`` depending if you need to include the time zone or not.

docs/index.rst

@@ -9,5 +9,6 @@ Welcome to the vsql documentation.
    getting-started.rst
    features.rst
    sql-reference.rst
+   sql-language.rst
    development.rst
    appendix.rst

docs/sql-compliance.rst

@@ -234,15 +234,15 @@ The following table is **not complete** and will be filled in as time goes on.
      - Explicit ``CAST`` between date-time types and character string types
 
    * - F051-06
-     - No
+     - Yes
      - ``CURRENT_DATE``
 
    * - F051-07
-     - No
+     - Yes
      - ``LOCALTIME``
 
    * - F051-08
-     - No
+     - Yes
      - ``LOCALTIMESTAMP``
 
    * - **F081**

docs/sql-language.rst

@@ -0,0 +1,7 @@
+The SQL Language
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   dates-times.rst

grammar.bnf

@@ -259,6 +259,35 @@
 
 <datetime primary> /* Expr */ ::=
     <value expression primary>
+  | <datetime value function>
+
+<datetime value function> /* Expr */ ::=
+    <current date value function>
+  | <current time value function>
+  | <current timestamp value function>
+  | <current local time value function>
+  | <current local timestamp value function>
+
+<current date value function> /* Expr */ ::=
+    CURRENT_DATE   -> current_date
+
+<current time value function> /* Expr */ ::=
+    CURRENT_TIME                                               -> current_time1
+  | CURRENT_TIME <left paren> <time precision> <right paren>   -> current_time2
+
+<current timestamp value function> /* Expr */ ::=
+    CURRENT_TIMESTAMP                                  -> current_timestamp1
+  | CURRENT_TIMESTAMP
+    <left paren> <timestamp precision> <right paren>   -> current_timestamp2
+
+<current local time value function> /* Expr */ ::=
+    LOCALTIME                                               -> localtime1
+  | LOCALTIME <left paren> <time precision> <right paren>   -> localtime2
+
+<current local timestamp value function> /* Expr */ ::=
+    LOCALTIMESTAMP                                     -> localtimestamp1
+  | LOCALTIMESTAMP
+    <left paren> <timestamp precision> <right paren>   -> localtimestamp2
 
 <value expression> /* Expr */ ::=
     <common value expression>