Add support for data tables

README.md

@@ -68,6 +68,7 @@ Implemented pieces include:
 - step matching with `{token}` placeholders
 - `Background`, `Scenario`, `Given` / `When` / `Then`, `And` / `But`, and `*`
 - doc strings via Gherkin-style `"""` blocks exposed as `DOC_STRING`
+- data tables exposed as `TABLE_HEADER` and `TABLE_ROWS` arrays
 - colored terminal output and scenario summary
 
 ### Gherkin Feature Support
@@ -86,10 +87,10 @@ Implemented pieces include:
 | Tags (`@tag`)                 | Supported   |
 | `Before`, `After` hooks       | Supported   |
 | `BeforeAll`, `AfterAll` hooks | Supported   |
+| Data tables                   | Supported   |
 | `Rule`                        | Unsupported |
 | `Scenario Outline`            | Unsupported |
 | `Examples`                    | Unsupported |
-| Data tables                   | Unsupported |
 
 Tags can be selected with `--tag` / `-t` and skipped with `--exclude-tag` / `-x`.
 `@Before` and `@After` hooks are declared in step definition files and may be
@@ -373,6 +374,8 @@ Shellkin exposes these variables to step definition bodies:
 | `LAST_STDOUT`    | Standard output captured by the most recent `run` call |
 | `LAST_STDERR`    | Standard error captured by the most recent `run` call  |
 | `DOC_STRING`     | Doc string attached to the current step, if any        |
+| `TABLE_HEADER`   | Header cells from the current step's data table array   |
+| `TABLE_ROWS`     | Tab-separated data rows from the current step's table   |
 
 Example:
 

doc/shellkin-feature.5

@@ -21,6 +21,8 @@ Shellkin currently supports these Gherkin keywords:
 \f[B]Given\f[R], \f[B]When\f[R], \f[B]Then\f[R]
 .IP \(bu 2
 \f[B]And\f[R], \f[B]But\f[R], \f[B]*\f[R]
+.IP \(bu 2
+data tables
 .SH FORMAT
 .SS Feature Header
 Each feature file starts with a \f[B]Feature:\f[R] header.
@@ -124,6 +126,23 @@ Scenario: Match multiline output
 .PP
 The doc string content is exposed to the matching step definition
 through the \f[B]DOC_STRING\f[R] environment variable.
+.SH DATA TABLES
+A data table may follow a step.
+Its first row is exposed to the matching step definition as the
+\f[B]TABLE_HEADER\f[R] array.
+Each remaining row is stored as a tab\-separated value in the
+\f[B]TABLE_ROWS\f[R] array.
+.IP
+.EX
+Given these users exist
+  | name  | role  |
+  | Alice | admin |
+  | Bob   | user  |
+.EE
+.PP
+All rows must contain the same number of cells.
+Cell values are trimmed.
+Escaped pipe characters in cells are not currently supported.
 .SH UNSUPPORTED CONSTRUCTS
 The following common Gherkin constructs are not currently supported:
 .IP \(bu 2
@@ -132,8 +151,6 @@ The following common Gherkin constructs are not currently supported:
 \f[B]Scenario Outline\f[R]
 .IP \(bu 2
 \f[B]Examples\f[R]
-.IP \(bu 2
-data tables
 .SH EXAMPLE
 .IP
 .EX

doc/shellkin-feature.md

@@ -26,6 +26,7 @@ Shellkin currently supports these Gherkin keywords:
 - **Scenario**
 - **Given**, **When**, **Then**
 - **And**, **But**, **\***
+- data tables
 
 FORMAT
 ==================================================
@@ -153,6 +154,23 @@ Scenario: Match multiline output
 The doc string content is exposed to the matching step definition through the
 **DOC_STRING** environment variable.
 
+DATA TABLES
+==================================================
+
+A data table may follow a step. Its first row is exposed to the matching step
+definition as the **TABLE_HEADER** array. Each remaining row is stored as a
+tab-separated value in the **TABLE_ROWS** array.
+
+```gherkin
+Given these users exist
+  | name  | role  |
+  | Alice | admin |
+  | Bob   | user  |
+```
+
+All rows must contain the same number of cells. Cell values are trimmed.
+Escaped pipe characters in cells are not currently supported.
+
 UNSUPPORTED CONSTRUCTS
 ==================================================
 
@@ -161,7 +179,6 @@ The following common Gherkin constructs are not currently supported:
 - **Rule**
 - **Scenario Outline**
 - **Examples**
-- data tables
 
 EXAMPLE
 ==================================================

doc/shellkin-stepdefs.5

@@ -192,6 +192,12 @@ Shellkin exposes these variables to step definition bodies:
 \f[B]run\f[R] call
 .IP \(bu 2
 \f[B]DOC_STRING\f[R] \- doc string attached to the current step, if any
+.IP \(bu 2
+\f[B]TABLE_HEADER\f[R] \- header cells from the current step\(aqs data
+table array
+.IP \(bu 2
+\f[B]TABLE_ROWS\f[R] \- tab\-separated data rows from the current
+step\(aqs data table
 .SH DOC STRINGS
 If a feature step is followed by a Gherkin doc string, its content is
 exposed to the step body through \f[B]DOC_STRING\f[R].
@@ -208,6 +214,18 @@ Then the output should match
 \(atThen the output should match
   \f[B][[\f[R] \(dq$LAST_STDOUT\(dq == \(dq$DOC_STRING\(dq \f[B]]]\f[R]
 .EE
+.SH DATA TABLES
+Data tables are exposed through the \f[B]TABLE_HEADER\f[R] and
+\f[B]TABLE_ROWS\f[R] arrays.
+Split each row on tabs to access its cells.
+.IP
+.EX
+\(atGiven these users exist
+\f[B]for\f[R] row \f[B]in\f[R] \(dq${TABLE_ROWS[\(at]}\(dq\f[B];\f[R] \f[B]do\f[R]
+  IFS=$\(aq\(rst\(aq read \-r name role <<<\(dq$row\(dq
+  create_user \(dq$name\(dq \(dq$role\(dq
+\f[B]done\f[R]
+.EE
 .SH EXAMPLE
 .IP
 .EX

doc/shellkin-stepdefs.md

@@ -204,6 +204,8 @@ Shellkin exposes these variables to step definition bodies:
 - **LAST_STDOUT** - standard output captured by the most recent **run** call
 - **LAST_STDERR** - standard error captured by the most recent **run** call
 - **DOC_STRING** - doc string attached to the current step, if any
+- **TABLE_HEADER** - header cells from the current step's data table array
+- **TABLE_ROWS** - tab-separated data rows from the current step's data table
 
 DOC STRINGS
 ==================================================
@@ -224,6 +226,20 @@ Then the output should match
   [[ "$LAST_STDOUT" == "$DOC_STRING" ]]
 ```
 
+DATA TABLES
+==================================================
+
+Data tables are exposed through the **TABLE_HEADER** and **TABLE_ROWS** arrays.
+Split each row on tabs to access its cells.
+
+```bash
+@Given these users exist
+for row in "${TABLE_ROWS[@]}"; do
+  IFS=$'\t' read -r name role <<<"$row"
+  create_user "$name" "$role"
+done
+```
+
 EXAMPLE
 ==================================================
 

features/fixtures/data_tables/data_tables.feature

@@ -0,0 +1,10 @@
+Feature: data tables
+  Pass structured examples to step definitions
+
+Scenario: Creating several users
+  Given these users exist
+    | name  | role   |
+    | Alice | admin  |
+    | Bob   | member |
+  Then user 'Alice' should have role 'admin'
+  And user 'Bob' should have role 'member'

features/fixtures/data_tables/step_definitions/core.sh

@@ -0,0 +1,20 @@
+@Given these users exist
+  USER_NAMES=()
+  USER_ROLES=()
+  [[ ${TABLE_HEADER[*]} == "name role" ]] || fail "expected name and role columns"
+
+  for row in "${TABLE_ROWS[@]}"; do
+    IFS=$'\t' read -r name role <<<"$row"
+    USER_NAMES+=("$name")
+    USER_ROLES+=("$role")
+  done
+
+@Then user '{name}' should have role '{role}'
+  for index in "${!USER_NAMES[@]}"; do
+    if [[ ${USER_NAMES[$index]} == "$name" ]]; then
+      [[ ${USER_ROLES[$index]} == "$role" ]]
+      return
+    fi
+  done
+
+  fail "user not found: $name"

features/test.feature

@@ -21,6 +21,13 @@ Scenario: Running hooks from step definition files
   And the output should include '2 scenarios, 0 failing'
   And the exit code should mean success
 
+Scenario: Running a feature that uses a data table
+  When I run 'shellkin features/fixtures/data_tables'
+  Then the output should include 'Feature: data tables'
+  And the output should include 'Scenario 1: Creating several users'
+  And the output should include '1 scenario, 0 failing'
+  And the exit code should mean success
+
 Scenario: Running a failing test
   When I run 'shellkin features/fixtures/selective/failing.feature'
   Then the output should include 'Feature: two'