antlr · incident-recipient · Jul 22, 2025 · Jul 24, 2025 · Jul 24, 2025
diff --git a/gherkin/GherkinLexer.g4 b/gherkin/GherkinLexer.g4
diff --git a/gherkin/GherkinParser.g4 b/gherkin/GherkinParser.g4
@@ -0,0 +1,16 @@
+parser grammar GherkinParser; 
+
+options { tokenVocab=GherkinLexer; } 
+
+gherkinDocument : LANGUAGE_HEADER? COMMENT* feature
+	| COMMENT+
+	| EOF
+	;
+feature : TAGS*? FEATURE_TITLE LONG_DESCRIPTION*?  background?  (ruleBlock | scenario)*;
+ruleBlock : RULE_TITLE  LONG_DESCRIPTION*  background? scenario*;
+background : BACKGROUND_TITLE  LONG_DESCRIPTION*? stepBody? ;
+scenario : TAGS*? (SCENARIO_TITLE | SCENARIO_OUTLINE_TITLE) LONG_DESCRIPTION* stepBody? examplesBody*;
+stepBody :  startingStep  (anyStep)* ;
+examplesBody : TAGS*?  EXAMPLES_TITLE  LONG_DESCRIPTION*?  DATA_ROW* ;
+startingStep : (GIVEN_STEP | WHEN_STEP | THEN_STEP | WILD_STEP) (DATA_ROW* | DOCSTRING) ;
+anyStep : (GIVEN_STEP | WHEN_STEP | THEN_STEP | AND_STEP | BUT_STEP | WILD_STEP) (DATA_ROW* | DOCSTRING) ;
diff --git a/gherkin/README.md b/gherkin/README.md
@@ -0,0 +1,25 @@
+# Background
+
+Gherkin is the protocol used by the Cucumber test framework for "Business Driven Development". It is a domain specific language for defining business scenarios in natural languages which in turn can be turned into automated tests.
+
+## Updating the parser
+
+The parser here was created and shared from the [PolymorphicDSL Test Framework](https://github.com/google/polymorphicDSL/tree/main/src/main/antlr4/com/pdsl/gherkin/parser) which also uses supports Gherkin for creating tests. This is a viable source of truth if you need to get updates as it aspires to support all gherkin features.
+
+The lexer is rather large because Gherkin aspires to support all natural languages (English, French, Spanish, etc). They even have some toy languages for "pirate" and a comical localization for Australian.
+
+This parser was up to date at the time it was created in 2021 and there do not appear to be any major changes to the Gherkin spec since that time. 
+
+## Updating the Lexer
+
+The lexer is likely to be the thing that changes from year to year as the gherkin protocol expands to include more natural languages. This is cumbersome to do by hand. In the event new languages or keywords need to be added the best bet is probably to use the [PolymorphicDSL python script](https://github.com/google/polymorphicDSL/blob/main/src/main/antlr4/com/pdsl/gherkin/parser/gherkin_template_processor.py) designed to consume the JSON format that the gherkin project uses to define the keywords. The most recent JSON language file can be found [here](gherkin-languages.json).
+
+## Examples
+
+The examples were originally created by the original Cucumber framework's Gherkin repository [here](https://github.com/cucumber/gherkin/tree/08305501ee838d1e036f13306e1a9e745ac1f6a1/testdata/good)
+
+Sadly, it seems most Cucumber implementations do not support the full Gherkin spec, including things like making "Scenario Outline" optional, the "Rule" keywords or even things as simple as multiline descriptors for scenarios. Using the above examples is the best way to keep the parser up to date. Ironically, it is "Business Driven Development" that lets you know clearly if you support the spec well, but most implementors seem to be unaware of it.
+
+
+
+
diff --git a/gherkin/desc.xml b/gherkin/desc.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<desc xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../_scripts/desc.xsd">
+   <targets>Antlr4ng;CSharp;Cpp;Dart;Go;Java;Python3</targets>
+   <!-- PHP, JavaScript, TypeScript don't work, likely binary input.
+   -->
+</desc>
+
diff --git a/gherkin/examples/background.feature b/gherkin/examples/background.feature
@@ -0,0 +1,11 @@
+Feature: Background
+
+  Background: a simple background
+    Given the minimalism inside a background
+
+
+  Scenario: minimalistic
+    Given the minimalism
+
+  Scenario: also minimalistic
+    Given the minimalism
diff --git a/gherkin/examples/complex_background.feature b/gherkin/examples/complex_background.feature
@@ -0,0 +1,24 @@
+Feature: Complex background
+  We want to ensure PickleStep all have different IDs
+
+  Background: a simple background
+    Given the minimalism inside a background
+
+  Scenario: minimalistic
+    Given the minimalism
+
+  Scenario: also minimalistic
+    Given the minimalism
+
+  Rule: My Rule
+
+    Background:
+      Given a rule background step
+
+    Scenario: with examples
+      Given the <value> minimalism
+
+      Examples:
+      | value |
+      | 1     |
+      | 2     |
diff --git a/gherkin/examples/datatables.feature b/gherkin/examples/datatables.feature
@@ -0,0 +1,18 @@
+Feature: DataTables
+
+  Scenario: minimalistic
+    Given a simple data table
+      | foo | bar |
+      | boz | boo |
+    And a data table with a single cell
+      | foo |
+    And a data table with different fromatting
+      |   foo|bar|    boz    |    
+    And a data table with an empty cell
+      |foo||boz|
+    And a data table with comments and newlines inside
+      | foo | bar |
+
+      | boz  | boo  |
+      # this is a comment
+      | boz2 | boo2 |
diff --git a/gherkin/examples/datatables_with_new_lines.feature b/gherkin/examples/datatables_with_new_lines.feature
@@ -0,0 +1,7 @@
+Feature: DataTables
+
+  Scenario: some whitespace is important
+    Given 3 lines of poetry on 5 lines
+      |  \nraindrops--\nher last kiss\ngoodbye.\n  |
+    Given an example of negative space
+      |        lost        i n        space        |
diff --git a/gherkin/examples/descriptions.feature b/gherkin/examples/descriptions.feature
@@ -0,0 +1,52 @@
+Feature: Descriptions everywhere
+  This is a single line description
+
+  Scenario: two lines
+  This description
+  has two lines and indented with two spaces
+    Given the minimalism
+
+Scenario: without indentation
+This is a description without indentation
+  Given the minimalism
+
+  Scenario: empty lines in the middle
+  This description
+
+  has an empty line in the middle
+    Given the minimalism
+
+  Scenario: empty lines around
+
+  This description
+  has an empty lines around
+
+    Given the minimalism
+
+  Scenario: comment after description
+  This description
+  has a comment after
+
+# this is a comment
+    Given the minimalism
+
+  Scenario: comment right after description
+  This description
+  has a comment right after
+    #  this is another comment
+
+    Given the minimalism
+
+  Scenario: description with escaped docstring separator
+  This description has an \"\"\" (escaped docstring sparator)
+
+    Given the minimalism
+
+  Scenario Outline: scenario outline with a description
+This is a scenario outline description
+    Given the minimalism
+
+  Examples: examples with description
+This is an examples description
+    | foo |
+    | bar |
diff --git a/gherkin/examples/docstrings.feature b/gherkin/examples/docstrings.feature
@@ -0,0 +1,49 @@
+Feature: DocString variations
+
+  Scenario: minimalistic
+    Given a simple DocString
+      """
+      first line (no indent)
+        second line (indented with two spaces)
+
+      third line was empty
+      """
+    Given a DocString with content type
+      """xml
+      <foo>
+        <bar />
+      </foo>
+      """
+    And a DocString with wrong indentation
+      """
+    wrongly indented line
+      """
+    And a DocString with alternative separator
+      ```
+      first line
+      second line
+      ```
+    And a DocString with normal separator inside
+      ```
+      first line
+      """
+      third line
+      ```
+    And a DocString with alternative separator inside
+      """
+      first line
+      ```
+      third line
+      """
+    And a DocString with escaped separator inside
+      """
+      first line
+      \"\"\"
+      third line
+      """
+    And a DocString with an escaped alternative separator inside
+      ```
+      first line
+      \`\`\`
+      third line
+      ```
diff --git a/gherkin/examples/empty.feature b/gherkin/examples/empty.feature
diff --git a/gherkin/examples/escaped_pipes.feature b/gherkin/examples/escaped_pipes.feature
@@ -0,0 +1,11 @@
+Feature: Escaped pipes
+    The \-character will be considered as an escape in table cell
+    iff it is followed by a |-character, a \-character or an n.
+
+  Scenario: They are the future
+    Given they have arrived
+      | æ | o |
+      | a | ø |
+    Given they have arrived
+      | \|æ\\n     | \o\no\  |
+      | \\\|a\\\\n | ø\\\nø\\|
diff --git a/gherkin/examples/example_token_multiple.feature b/gherkin/examples/example_token_multiple.feature
@@ -0,0 +1,8 @@
+Feature: Example token used multiple times
+
+  Scenario Outline: Token used twice in a single step
+    Given <what> <what>
+
+    Examples:
+      | what  |
+      | usage |
diff --git a/gherkin/examples/example_tokens_everywhere.feature b/gherkin/examples/example_tokens_everywhere.feature
@@ -0,0 +1,14 @@
+Feature: Example tokens everywhere
+
+  Scenario Outline: the <one>
+    Given the <two>:
+      """
+      <three>
+      """
+    Given the <four>:
+      | <five> |
+
+    Examples:
+      | one | two  | three | four   | five  |
+      | un  | deux | trois | quatre | cinq  |
+      | uno | dos  | tres  | quatro | cinco |
diff --git a/gherkin/examples/i18n_emoji.feature b/gherkin/examples/i18n_emoji.feature
@@ -0,0 +1,5 @@
+# language: em
+📚: 🙈🙉🙊
+
+  📕: 💃
+    😐🎸
diff --git a/gherkin/examples/i18n_fr.feature b/gherkin/examples/i18n_fr.feature
@@ -0,0 +1,63 @@
+#language:fr
+Fonctionnalité: i18n support
+
+  Scénario: Support des caractères spéciaux
+    Soit un exemple de scénario en français
+    Quand j'ai 1 gâteau
+    Alors je suis heureux
+
+  Scénario: Support du mot-clef "Etant donné que "
+    Etant donné que j'aime les gâteaux
+    Lorsqu'on m'offre 1 gâteau
+    Alors je suis heureux
+
+  Scénario: Support du mot-clef "Etant donné qu'"
+    Etant donné qu'offrir un gâteau rend heureux
+    Lorsqu'on m'offre 1 gâteau
+    Alors je suis heureux
+
+  Scénario: Support du mot-clef "Étant donné que "
+    Étant donné que j'aime les gâteaux 
+    Lorsqu'on m'offre 1 gâteau
+    Alors je suis heureux
+
+  Scénario: Support du mot-clef "Étant donné qu'"
+    Étant donné qu'offrir un gâteau rend heureux
+    Lorsqu'on m'offre 1 gâteau
+    Alors je suis heureux
+
+  Scénario: Support du mot-clef "Et que "
+    Soit un exemple de scénario en français
+    Lorsque j'ai 2 gâteaux
+    Et que quelqu'un m'offre 1 gâteau
+    Alors j'ai 3 gâteaux
+
+  Scénario: Support du mot-clef "Et qu'"
+    Soit un exemple de scénario en français
+    Lorsque j'ai 2 gâteaux
+    Et qu'on m'offre 1 gâteau
+    Alors j'ai 3 gâteaux
+
+  Scénario: Support du mot-clef "Et "
+    Soit un exemple de scénario en français
+    Quand j'ai 2 gâteaux
+    Et quelqu'un m'offre 1 gâteau
+    Alors j'ai 3 gâteaux
+
+  Scénario: Support du mot-clef "Mais que "
+    Soit un exemple de scénario en français
+    Lorsque j'ai 2 gâteaux
+    Mais que quelqu'un me vole 1 gâteau
+    Alors j'ai 1 gâteau
+
+  Scénario: Support du mot-clef "Mais qu'"
+    Soit un exemple de scénario en français
+    Lorsque j'ai 2 gâteaux
+    Mais qu'on me vole 1 gâteau
+    Alors j'ai 1 gâteau
+
+  Scénario: Support du mot-clef "Mais "
+    Soit un exemple de scénario en français
+    Quand j'ai 2 gâteaux
+    Mais quelqu'un me vole 1 gâteau
+    Alors j'ai 1 gâteau
diff --git a/gherkin/examples/i18n_no.feature b/gherkin/examples/i18n_no.feature
@@ -0,0 +1,7 @@
+#language:no
+Egenskap: i18n support
+
+  Scenario: Parsing many languages
+    Gitt Gherkin supports many languages
+    Når Norwegian keywords are parsed
+    Så they should be recognized
diff --git a/gherkin/examples/incomplete_background_1.feature b/gherkin/examples/incomplete_background_1.feature
@@ -0,0 +1,6 @@
+Feature: Incomplete backgrounds, Part 1
+
+  Background: no steps
+
+  Scenario: still pickles up
+    * a step
diff --git a/gherkin/examples/incomplete_background_2.feature b/gherkin/examples/incomplete_background_2.feature
@@ -0,0 +1,7 @@
+Feature: Incomplete backgrounds, Part 2
+
+  Background: just a description
+    A short description
+
+  Scenario: still pickles up
+    * a step
diff --git a/gherkin/examples/incomplete_feature_1.feature b/gherkin/examples/incomplete_feature_1.feature
@@ -0,0 +1,2 @@
+Feature: Just a description
+  A short description
diff --git a/gherkin/examples/incomplete_feature_2.feature b/gherkin/examples/incomplete_feature_2.feature
@@ -0,0 +1 @@
+Feature: Empty feature
diff --git a/gherkin/examples/incomplete_feature_3.feature b/gherkin/examples/incomplete_feature_3.feature
@@ -0,0 +1 @@
+# Just a comment
diff --git a/gherkin/examples/incomplete_scenario.feature b/gherkin/examples/incomplete_scenario.feature
@@ -0,0 +1,6 @@
+Feature: Incomplete scenarios
+
+  Background: Adding a background won't make a pickle
+    * a step
+
+  Scenario: no steps
diff --git a/gherkin/examples/incomplete_scenario_outline.feature b/gherkin/examples/incomplete_scenario_outline.feature
@@ -0,0 +1,24 @@
+Feature: Incomplete scenario outlines
+
+  Background: Adding a background won't make a pickle
+    * a step
+
+  Scenario Outline: steps, no examples
+    Given a step
+
+  Scenario Outline: no steps, no examples
+
+  Scenario Outline: no steps, no table
+
+    Examples:
+
+  Scenario Outline: no steps, only table header
+
+    Examples:
+    | what |
+
+  Scenario Outline: no steps, one example header
+
+    Examples:
+    | nope |
+    | nada |
diff --git a/gherkin/examples/language.feature b/gherkin/examples/language.feature
@@ -0,0 +1,6 @@
+#language:en
+
+Feature: Explicit language specification
+
+  Scenario: minimalistic
+    Given the minimalism
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Feature: Just a description
		A short description