0
# Gherkin Java Parser
1

2
Gherkin is a comprehensive parser and compiler for the Gherkin language used by Cucumber for behavior-driven development (BDD). It parses Gherkin feature files into Abstract Syntax Trees (AST) and compiles them into executable 'Pickles' for test automation frameworks, supporting internationalization with multiple language keywords and providing streaming APIs for efficient processing.
3

4
## Package Information
5

6
- **Package Name**: gherkin
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>io.cucumber</groupId><artifactId>gherkin</artifactId><version>31.0.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import io.cucumber.gherkin.GherkinParser;
15
import io.cucumber.gherkin.GherkinDialectProvider;
16
import io.cucumber.messages.types.Envelope;
17
import io.cucumber.messages.types.GherkinDocument;
18
import io.cucumber.messages.types.Pickle;
19
```
20

21
## Basic Usage
22

23
```java
24
import io.cucumber.gherkin.GherkinParser;
25
import io.cucumber.messages.types.Envelope;
26
import java.nio.file.Paths;
27
import java.util.stream.Stream;
28

29
// Parse a Gherkin feature file
30
GherkinParser parser = GherkinParser.builder().build();
31
Stream<Envelope> messages = parser.parse(Paths.get("features/example.feature"));
32

33
// Process the parsed messages
34
messages.forEach(envelope -> {
35
    if (envelope.getGherkinDocument().isPresent()) {
36
        System.out.println("Feature: " + 
37
            envelope.getGherkinDocument().get().getFeature().get().getName());
38
    }
39
    if (envelope.getPickle().isPresent()) {
40
        System.out.println("Scenario: " + 
41
            envelope.getPickle().get().getName());
42
    }
43
});
44
```
45

46
## Architecture
47

48
Gherkin Java is built around several key components:
49

50
- **GherkinParser**: High-level streaming parser with builder configuration pattern
51
- **Language Support**: Multi-language keyword support through dialect providers
52
- **Token Processing**: Internal tokenization and parsing pipeline for grammar recognition
53
- **AST Generation**: Abstract Syntax Tree creation from parsed tokens
54
- **Pickle Compilation**: Conversion of AST scenarios into executable test units
55
- **Cucumber Messages**: Integration with Cucumber's messaging protocol for interoperability
56

57
## Capabilities
58

59
### High-Level Parsing
60

61
Main entry point for parsing Gherkin files with configurable options for output formats and content inclusion.
62

63
```java { .api }
64
public final class GherkinParser {
65
    public static Builder builder();
66
    public Stream<Envelope> parse(Path source) throws IOException;
67
    public Stream<Envelope> parse(String uri, InputStream source) throws IOException;
68
    public Stream<Envelope> parse(String uri, byte[] source);
69
    public Stream<Envelope> parse(Envelope envelope);
70
}
71

72
public static final class Builder {
73
    public Builder includeSource(boolean includeSource);
74
    public Builder includeGherkinDocument(boolean includeGherkinDocument);
75
    public Builder includePickles(boolean includePickles);
76
    public Builder idGenerator(IdGenerator idGenerator);
77
    public GherkinParser build();
78
}
79
```
80

81
[High-Level Parsing](./parsing.md)
82

83
### Language Support
84

85
Comprehensive support for Gherkin in multiple languages with keyword translation and dialect management.
86

87
```java { .api }
88
public final class GherkinDialectProvider {
89
    public GherkinDialectProvider();
90
    public GherkinDialectProvider(String defaultDialectName);
91
    public GherkinDialect getDefaultDialect();
92
    public Optional<GherkinDialect> getDialect(String language);
93
    public Set<String> getLanguages();
94
}
95

96
public final class GherkinDialect {
97
    public String getLanguage();
98
    public String getName();
99
    public String getNativeName();
100
    public List<String> getFeatureKeywords();
101
    public List<String> getRuleKeywords();
102
    public List<String> getScenarioKeywords();
103
    public List<String> getScenarioOutlineKeywords();
104
    public List<String> getBackgroundKeywords();
105
    public List<String> getExamplesKeywords();
106
    public List<String> getGivenKeywords();
107
    public List<String> getWhenKeywords();
108
    public List<String> getThenKeywords();
109
    public List<String> getAndKeywords();
110
    public List<String> getButKeywords();
111
    public List<String> getStepKeywords();
112
    public List<StepKeywordType> getStepKeywordTypes(String keyword);
113
}
114
```
115

116
[Language Support](./languages.md)
117

118
## Types
119

120
```java { .api }
121
// Cucumber Messages integration types (external dependency)
122
import io.cucumber.messages.types.Envelope;
123
import io.cucumber.messages.types.GherkinDocument;
124
import io.cucumber.messages.types.Pickle;
125
import io.cucumber.messages.types.PickleStep;
126
import io.cucumber.messages.types.PickleTag;
127
import io.cucumber.messages.types.Source;
128
import io.cucumber.messages.types.ParseError;
129
import io.cucumber.messages.types.Feature;
130
import io.cucumber.messages.types.Scenario;
131
import io.cucumber.messages.types.Step;
132
import io.cucumber.messages.types.Background;
133
import io.cucumber.messages.types.Rule;
134
import io.cucumber.messages.types.Tag;
135
import io.cucumber.messages.types.Comment;
136
import io.cucumber.messages.types.TableRow;
137
import io.cucumber.messages.types.TableCell;
138
import io.cucumber.messages.types.DataTable;
139
import io.cucumber.messages.types.DocString;
140
import io.cucumber.messages.types.Examples;
141
import io.cucumber.messages.types.StepKeywordType;
142
import io.cucumber.messages.types.Location;
143
import io.cucumber.messages.IdGenerator;
144

145
// StepKeywordType enum values (from io.cucumber.messages.types)
146
StepKeywordType.CONTEXT    // Given steps
147
StepKeywordType.ACTION     // When steps
148
StepKeywordType.OUTCOME    // Then steps  
149
StepKeywordType.CONJUNCTION // And, But steps
150
StepKeywordType.UNKNOWN    // Ambiguous steps
151

152
// Exception types (from io.cucumber.gherkin package)
153
// These are package-private but thrown from public APIs
154
ParserException.NoSuchLanguageException    // Unsupported language
155
ParserException.UnexpectedTokenException   // Parse syntax errors
156
ParserException.UnexpectedEOFException     // Premature end of file
157
ParserException.CompositeParserException   // Multiple parse errors
158
ParserException.AstBuilderException        // AST construction errors
159
GherkinException                           // General processing errors
160
```