feat(tests): add enum argument support to FuncTestCase grammar (#1010)

In the FuncTestCase grammar enum arguments were not handled as enum
arguments but as string literals (only example so far the datetime
`extract` function).

- This PR changes the grammar to explicitly support enum arguments with
  a new `enum` data type in the grammar.
- The Python code is regenerated from the grammar.
- The `extract` test cases are updated to use the new syntax.

Signed-off-by: Niels Pardon <par@zurich.ibm.com>

Author: nielspardon

grammar/FuncTestCaseLexer.g4

@@ -113,6 +113,8 @@ StringLiteral
     : '\'' ('\\' . | '\'\'' | ~['\\])* '\''
     ;
 
+EnumType: 'enum' ;
+
 ColumnName
     : 'COL' Int
     ;

grammar/FuncTestCaseParser.g4

@@ -49,6 +49,7 @@ result
 
 argument
     : nullArg
+    | enumArg
     | intArg
     | floatArg
     | booleanArg
@@ -216,6 +217,10 @@ lambdaArg
     : literalLambda DoubleColon funcType
     ;
 
+enumArg
+    : Identifier DoubleColon EnumType
+    ;
+
 literalList
     : OBracket (listElement (Comma listElement)*)? CBracket
     ;

tests/README.md

@@ -104,9 +104,10 @@ test_case   := <function>(<arguments>) ([<options>])? = <result> (#<description>
 description := string
 function    := string
 arguments   := <argument>, <argument>, ... <argument>
-argument    := <literal>
+argument    := <literal> | <enum_value>
 literal     := <literal_value>::<datatype>
-result      := <substrait_error> | <literal>
+enum_value  := <identifier>::enum
+result      := <substrait_error> | <literal> | <enum_value>
 options     := <option>, <option>, ... <option>
 option      := <option_name>:<option_value>
 literal_value := string | integer | decimal | float | boolean | date | time | timestamp | timestamp_tz | interval year | interval days | null
@@ -148,6 +149,9 @@ Integers are represented as sequences of digits. Negative numbers are preceded b
 #### Boolean
 - Valid values: true, false
 
+#### Enum
+- **enum**: An enumeration value represented as an identifier. Enum values are defined in extension files and are used as named constants. Example: `DISTRIBUTION_TYPE::enum` where `DISTRIBUTION_TYPE` is the enum value.
+
 #### Date and Time
 All date and time literals use ISO 8601 format:
 
@@ -264,3 +268,19 @@ In this example:
 - We are testing `functions_list.yaml` (specifically the `transform` function)
 - We need `functions_arithmetic.yaml` as a dependency because the lambda expressions use `multiply` and `add` from that extension
 - Test coverage counts towards `functions_list.yaml`, not `functions_arithmetic.yaml`
+
+### Example of a test file with enum arguments
+
+```code
+### SUBSTRAIT_SCALAR_TEST: v1.0
+### SUBSTRAIT_INCLUDE: '/extensions/functions_datetime.yaml'
+
+# timestamps: examples using the timestamp and timestamptz types
+extract(YEAR::enum, '2016-12-31T13:30:15'::ts) = 2016::i64
+extract(ISO_YEAR::enum, '2016-01-01T13:30:15'::ts) = 2015::i64
+extract(QUARTER::enum, '2016-12-31T13:30:15'::ts) = 4::i64
+```
+
+In this example:
+- Enum values like `YEAR`, `ISO_YEAR` and `QUARTER` are used as arguments with type `enum`
+- Enum types are defined in the extension file and represent named constants for function options

tests/cases/datetime/extract.test

@@ -2,30 +2,30 @@
 ### SUBSTRAIT_INCLUDE: '/extensions/functions_datetime.yaml'
 
 # timestamps: examples using the timestamp and timestamptz types
-extract('YEAR'::str, '2016-12-31T13:30:15'::ts) = 2016::i64
-extract('ISOYEAR'::str, '2016-01-01T13:30:15'::ts) = 2015::i64
-extract('QUARTER'::str, '2016-12-31T13:30:15'::ts) = 4::i64
-extract('MONTH'::str, '2016-12-31T13:30:15'::ts) = 12::i64
-extract('WEEK'::str, '2016-12-31T13:30:15'::ts) = 52::i64
-extract('DAY'::str, '2016-12-31T13:30:15'::ts) = 31::i64
-extract('ISODOW'::str, '2016-12-25T13:30:15'::ts) = 7::i64
-extract('DOW'::str, '2016-12-25T13:30:15'::ts) = 0::i64
-extract('DOY'::str, '2016-12-25T13:30:15'::ts) = 360::i64
-extract('HOUR'::str, '2016-12-31T13:30:15'::ts) = 13::i64
-extract('MINUTE'::str, '2016-12-31T13:30:15'::ts) = 30::i64
-extract('SECOND'::str, '2016-12-31T13:30:15'::ts) = 15::i64
-extract('MILLISECONDS'::str, '2016-12-31T13:30:15'::ts) = 15000::i64
-extract('MICROSECONDS'::str, '2016-12-31T13:30:15.220000'::ts) = 15220000::i64
-extract('EPOCH'::str, '2016-12-31T13:30:15'::ts) = 1483191015::i64
+extract(YEAR::enum, '2016-12-31T13:30:15'::ts) = 2016::i64
+extract(ISO_YEAR::enum, '2016-01-01T13:30:15'::ts) = 2015::i64
+extract(QUARTER::enum, '2016-12-31T13:30:15'::ts) = 4::i64
+extract(MONTH::enum, '2016-12-31T13:30:15'::ts) = 12::i64
+extract(ISO_WEEK::enum, '2016-12-31T13:30:15'::ts) = 52::i64
+extract(DAY::enum, '2016-12-31T13:30:15'::ts) = 31::i64
+extract(SUNDAY_DAY_OF_WEEK::enum, '2016-12-25T13:30:15'::ts) = 7::i64
+extract(MONDAY_DAY_OF_WEEK::enum, '2016-12-25T13:30:15'::ts) = 0::i64
+extract(DAY_OF_YEAR::enum, '2016-12-25T13:30:15'::ts) = 360::i64
+extract(HOUR::enum, '2016-12-31T13:30:15'::ts) = 13::i64
+extract(MINUTE::enum, '2016-12-31T13:30:15'::ts) = 30::i64
+extract(SECOND::enum, '2016-12-31T13:30:15'::ts) = 15::i64
+extract(MILLISECOND::enum, '2016-12-31T13:30:15'::ts) = 15000::i64
+extract(MICROSECOND::enum, '2016-12-31T13:30:15.220000'::ts) = 15220000::i64
+extract(UNIX_TIME::enum, '2016-12-31T13:30:15'::ts) = 1483191015::i64
 
 # date: examples using the date type
-extract('YEAR'::str, '2020-12-31'::date) = 2020::i64
-extract('MONTH'::str, '2020-12-31'::date) = 12::i64
-extract('DAY'::str, '2020-12-31'::date) = 31::i64
+extract(YEAR::enum, '2020-12-31'::date) = 2020::i64
+extract(MONTH::enum, '2020-12-31'::date) = 12::i64
+extract(DAY::enum, '2020-12-31'::date) = 31::i64
 
 # time: examples using the time type
-extract('HOUR'::str, '01:02:03'::time) = 1::i64
-extract('MINUTE'::str, '01:02:03'::time) = 2::i64
-extract('SECOND'::str, '01:02:03'::time) = 3::i64
-extract('MILLISECOND'::str, '01:02:03.155'::time) = 3155::i64
-extract('MICROSECOND'::str, '01:02:03.45'::time) = 3450000::i64
+extract(HOUR::enum, '01:02:03'::time) = 1::i64
+extract(MINUTE::enum, '01:02:03'::time) = 2::i64
+extract(SECOND::enum, '01:02:03'::time) = 3::i64
+extract(MILLISECOND::enum, '01:02:03.155'::time) = 3155::i64
+extract(MICROSECOND::enum, '01:02:03.45'::time) = 3450000::i64