Data table and Doc string are not documented as mutually exclusive

[DDtKey]

👓 What did you see?

    When user does something
      """
        ok
      """
      | a | b |

leads to

expected: #EOF, #StepLine, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got '| a | b |

✅ What did you expect to see?

I expect combination of Data-Table and DocString to work, because actually there is no mentions in documentation it's disallowed.
And (subjectively) not clear why it should be disallowed.

In some cases it's really useful.

📦 Which tool/library version are you using?

I actually use cucumber for rust (third-party), and it works really good.
But I wanted to add a linter for gherkin files and encountered this issue, because the linter uses go implementation of this repo.

🔬 How could we reproduce it?

Actually it's enough to add such case to testdata and run make acceptance test:

    When user does something
      """
        ok
      """
      | a | b |

📚 Any additional context?

The issues actually comes from antham/ghokin#124

I checked several languages from the repo, and for all of them it doesn't work. So it's rather a feature request than a bug?

---

This text was originally generated from a template, then edited by hand. You can modify the template here.

[mpkorstanje]

I'm not privy the original reason for preventing the use of doc strings and data tables together. But looking back that decision seems to have been intentional.

For example in cucumber/cucumber-jvm#1183 I do see that the Gherkin v2.12.2 accepted the combination. Though it did cause an error in Cucumber JVM.

And looking at cucumber-attic/gherkin2#138 being able to parse any combination of docstrings and data tables (and incorrectly assign it to the wrong step) was considered a bug in Gherkin v2 in 2011 already.

I suspect the complexity of dealing with both docstring and data tables together in dynamically typed languages is was considered to be too much at the time.

@brasmusson @aslakhellesoy do you have anything to add to that?

In some cases it's really useful.

Such as?

Moreover, it works with quite a lot of cucumber-runners, JetBrains plugin also marks such syntax as valid.

Do you have a list of runners? I'm curious to see how they behave.

[DDtKey]

In some cases it's really useful.

Such as?

Well, can't imagine all ways to use it, but even taking example from reference it can be combined. Let's take a look at:

It could be something like User sends a message to:, where content of DocString is a message and DataTable is kinda "mailing list"

Or, for example, DocString is SQL and DataTable contains sources to select.

It can be done by splitting to different steps ofc, but it would require to handle more states and preserve data for following steps.

[DDtKey]

Moreover, it works with quite a lot of cucumber-runners, JetBrains plugin also marks such syntax as valid.

Do you have a list of runners? I'm curious to see how they behave.

I currently mostly work with rust runner (unofficial) as I mentioned above, it works like a charm to me.
It's possible to work with gherkin::Step which can have both docstring and table at the same time.

Sorry, I think "quite a lot" was too strong claim, at least for now - when I checked impls in this repo.
I can’t remember when and what kind of runner that was, but this syntax worked in another implementation (could be specific period of time?).
Therefore, perhaps I had a false feeling that this is allowed (also taking into account plugin highlighting and auto-formatting over all the time)

[DDtKey]

Just to clarify: I'm totally ok if it's disallowed by intention.

Would be nice to consider allowing this or explicitly mention in documentation it's invalid gherkin syntax

[mpkorstanje]

It is a complicated question.

Gherkins grammar is specified in Berp. And in that grammar, doc strings and data tables are mutually exclusive:

https://github.com/cucumber/gherkin/blob/24952f9ad5b90d6f3df2e0868e932a9c519a767e/gherkin.berp#L27-L28

But Berp is only used for Gherkin. So there is effectively no technical specification to violate. You could still ask the cucumber-rs team to match the behavior of the Cucumber Gherkin parser though.

As for IDEA. the Gherkin syntax is not versioned and has had some breaking changes over time. So it is not surprising their parser supports a superset of the different versions of Gherkin.

[mpkorstanje]

If you want to update the docs, the sentence:

In some cases you might want to pass more data to a step than fits on a single line. For this purpose Gherkin has Doc Strings and Data Tables.

Could be rewritten to more strongly suggest they're mutually exclusive. Not too technically though, these are end user documentation, not technical specifications. Something like (though I think it is a bit repetitive, repeating the you every sentence):

In some cases you might want to pass more data to a step than fits on a single line. For this purpose you can either use Doc Strings or Data Tables.

We take pull requests for the docs at: https://github.com/cucumber/docs

If you want to send one that would be nice, if not I can move this whole issue there.