Skip to content

Commit 0875a40

Browse files
aslakhellesoyaurelien-reeves
aslakhellesoy
and
aurelien-reeves
authored
Move documentation from the docs repo (#3)
* Move documentation from the docs repo * Update README.md Co-authored-by: Aurélien Reeves <[email protected]> * Extract ARCHITECTURE.md Co-authored-by: Aurélien Reeves <[email protected]>
1 parent 5b34585 commit 0875a40

File tree

2 files changed

+253
-55
lines changed

2 files changed

+253
-55
lines changed

‎ARCHITECTURE.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Architecture
2+
3+
This document describes the grammar and production rules of Cucumber Expressions.
4+
5+
## Grammar
6+
7+
A Cucumber Expression has the following [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) grammar:
8+
9+
```ebnf
10+
cucumber-expression = ( alternation | optional | parameter | text )*
11+
alternation = (?<=left-boundary), alternative*, ( "/" + alternative* )+, (?=right-boundary)
12+
left-boundary = whitespace | "}" | "^"
13+
right-boundary = whitespace | "{" | "$"
14+
alternative = optional | parameter | text
15+
optional = "(", option*, ")"
16+
option = optional | parameter | text
17+
parameter = "{", name*, "}"
18+
name = whitespace | .
19+
text = whitespace | ")" | "}" | .
20+
```
21+
22+
The AST is constructed from the following tokens:
23+
24+
```ebnf
25+
escape = "\"
26+
token = whitespace | "(" | ")" | "{" | "}" | "/" | .
27+
. = any non-reserved codepoint
28+
```
29+
30+
Note:
31+
* While `parameter` is allowed to appear as part of `alternative` and
32+
`option` in the AST, such an AST is not a valid a Cucumber Expression.
33+
* While `optional` is allowed to appear as part of `option` in the AST,
34+
such an AST is not a valid a Cucumber Expression.
35+
* ASTs with empty alternatives or alternatives that only
36+
contain an optional are valid ASTs but invalid Cucumber Expressions.
37+
* All escaped tokens (tokens starting with a backslash) are rewritten to their
38+
unescaped equivalent after parsing.
39+
40+
### Production Rules
41+
42+
The AST can be rewritten into a regular expression by the following production
43+
rules:
44+
45+
```
46+
cucumber-expression -> '^' + rewrite(node[0]) + ... + rewrite(node[n-1]) + '$'
47+
alternation -> '(?:' + rewrite(node[0]) + '|' + ... + '|' + rewerite(node[n-1]) + ')'
48+
alternative -> rewrite(node[0]) + ... + rewrite(node[n-1])
49+
optional -> '(?:' + rewrite(node[0]) + ... + rewrite(node[n-1]) + ')?'
50+
parameter -> {
51+
parameter_name := node[0].text + ... + node[n-1].text
52+
parameter_pattern := parameter_type_registry[parameter_name]
53+
'((?:' + parameter_pattern[0] + ')|(?:' ... + ')|(?:' + parameter_pattern[n-1] + '))'
54+
}
55+
text -> {
56+
escape_regex := escape '^', `$`, `[`, `]`, `(`, `)` `\`, `{`, `}`, `.`, `|`, `?`, `*`, `+`
57+
escape_regex(token.text)
58+
}
59+
```

‎README.md‎

Lines changed: 194 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,210 @@
1-
See [website docs](https://cucumber.io/docs/cucumber/cucumber-expressions/)
2-
for more details.
3-
4-
## Grammar ##
5-
6-
A Cucumber Expression has the following AST:
7-
8-
```ebnf
9-
cucumber-expression := ( alternation | optional | parameter | text )*
10-
alternation := (?<=left-boundary) + alternative* + ( '/' + alternative* )+ + (?=right-boundary)
11-
left-boundary := whitespace | } | ^
12-
right-boundary := whitespace | { | $
13-
alternative := optional | parameter | text
14-
optional := '(' + option* + ')'
15-
option := optional | parameter | text
16-
parameter := '{' + name* + '}'
17-
name := whitespace | .
18-
text := whitespace | ')' | '}' | .
1+
# Cucumber Expressions
2+
3+
Cucumber Expressions is an alternative to [Regular Expressions](https://en.wikipedia.org/wiki/Regular_expression)
4+
with a more intuitive syntax.
5+
6+
Cucumber supports both Cucumber Expressions and Regular Expressions for defining
7+
[Step Definitions](https://cucumber.io/docs/cucumber/step-definitions), but you cannot
8+
mix Cucumber Expression syntax with Regular Expression syntax in the same expression.
9+
10+
On platforms that don't have a literal syntax for regular expressions (such as Java),
11+
Cucumber will create a Cucumber Expression by default. To use Regular Expressions, add anchors (starting with `^` and ending with `$`) or forward slashes (`/`). For more information, see
12+
[Cucumber Expression - Java Heuristics](https://github.com/cucumber/cucumber-expressions/blob/main/java/heuristics.adoc).
13+
14+
## Introduction
15+
16+
Let's write a Cucumber Expression that matches the following Gherkin step (the `Given`
17+
keyword has been removed here, as it's not part of the match).
18+
19+
I have 42 cucumbers in my belly
20+
21+
The simplest Cucumber Expression that matches that text would be the text itself,
22+
but we can also write a more generic expression, with an `int` *output parameter*:
23+
24+
I have {int} cucumbers in my belly
25+
26+
When the text is matched against that expression, the number `42` is extracted
27+
from the `{int}` output parameter and passed as an argument to the [step definition](https://cucumber.io/docs/cucumber/step-definitions).
28+
29+
The following text would **not** match the expression:
30+
31+
I have 42.5 cucumbers in my belly
32+
33+
This is because `42.5` has a decimal part, and doesn't fit into an `int`.
34+
Let's change the output parameter to `float` instead:
35+
36+
I have {float} cucumbers in my belly
37+
38+
Now the expression will match the text, and the float `42.5` is extracted.
39+
40+
## Parameter types
41+
42+
Text between curly braces reference a *parameter type*. Cucumber comes with
43+
the following built-in parameter types:
44+
45+
| Parameter Type | Description |
46+
| --------------- | ----------- |
47+
| `{int}` | Matches integers, for example `71` or `-19`. |
48+
| `{float}` | Matches floats, for example `3.6`, `.8` or `-9.2`. |
49+
| `{word}` | Matches words without whitespace, for example `banana` (but not `banana split`). |
50+
| `{string}` | Matches single-quoted or double-quoted strings, for example `"banana split"` or `'banana split'` (but not `banana split`). Only the text between the quotes will be extracted. The quotes themselves are discarded. Empty pairs of quotes are valid and will be matched and passed to step code as empty strings. |
51+
| `{}` anonymous | Matches anything (`/.*/`). |
52+
53+
### Cucumber-JVM additions
54+
55+
On the JVM, there are additional parameter types for `biginteger`, `bigdecimal`,
56+
`byte`, `short`, `long` and `double`.
57+
58+
The anonymous parameter type will be converted to the parameter type of the step definition using an object mapper.
59+
Cucumber comes with a built-in object mapper that can handle most basic types. Aside from `Enum` it supports conversion
60+
to `BigInteger`, `BigDecimal`, `Boolean`, `Byte`, `Short`, `Integer`, `Long`, `Float`, `Double` and `String`.
61+
62+
To automatically convert to other types it is recommended to install an object mapper. See [configuration](https://cucumber.io/docs/cucumber/configuration)
63+
to learn how.
64+
65+
### Custom Parameter types
66+
67+
Cucumber Expressions can be extended so they automatically convert
68+
output parameters to your own types. Consider this Cucumber Expression:
69+
70+
I have a {color} ball
71+
72+
If we want the `{color}` output parameter to be converted to a `Color` object,
73+
we can define a custom parameter type in Cucumber's [configuration](https://cucumber.io/docs/cucumber/configuration).
74+
75+
The table below explains the various arguments you can pass when defining
76+
a parameter type.
77+
78+
| Argument | Description |
79+
| ------------- | ----------- |
80+
| `name` | The name the parameter type will be recognised by in output parameters.
81+
| `regexp` | A regexp that will match the parameter. May include capture groups.
82+
| `type` | The return type of the transformer {{% stepdef-body %}}.
83+
| `transformer` | A function or method that transforms the match from the regexp. Must have arity 1 if the regexp doesn't have any capture groups. Otherwise the arity must match the number of capture groups in `regexp`. |
84+
| `useForSnippets` / `use_for_snippets` | Defaults to `true`. That means this parameter type will be used to generate snippets for undefined steps. If the `regexp` frequently matches text you don't intend to be used as arguments, disable its use for snippets with `false`. |
85+
| `preferForRegexpMatch` / `prefer_for_regexp_match` | Defaults to `false`. Set to `true` if you have step definitions that use regular expressions, and you want this parameter type to take precedence over others during a match. |
86+
87+
#### Java
88+
89+
```java
90+
@ParameterType("red|blue|yellow") // regexp
91+
public Color color(String color){ // type, name (from method)
92+
return new Color(color); // transformer function
93+
}
1994
```
2095

21-
The AST is constructed from the following tokens:
22-
```ebnf
23-
escape := '\'
24-
token := whitespace | '(' | ')' | '{' | '}' | '/' | .
25-
. := any non-reserved codepoint
96+
#### Kotlin
97+
98+
```kotlin
99+
@ParameterType("red|blue|yellow") // regexp
100+
fun color(color: String): Color { // name (from method), type
101+
return Color(color) // transformer function
102+
}
26103
```
27104

28-
Note:
29-
* While `parameter` is allowed to appear as part of `alternative` and
30-
`option` in the AST, such an AST is not a valid a Cucumber Expression.
31-
* While `optional` is allowed to appear as part of `option` in the AST,
32-
such an AST is not a valid a Cucumber Expression.
33-
* ASTs with empty alternatives or alternatives that only
34-
contain an optional are valid ASTs but invalid Cucumber Expressions.
35-
* All escaped tokens (tokens starting with a backslash) are rewritten to their
36-
unescaped equivalent after parsing.
37-
38-
### Production Rules
39-
40-
The AST can be rewritten into a regular expression by the following production
41-
rules:
42-
43-
```ebnf
44-
cucumber-expression -> '^' + rewrite(node[0]) + ... + rewrite(node[n-1]) + '$'
45-
alternation -> '(?:' + rewrite(node[0]) +'|' + ... +'|' + rewerite(node[n-1]) + ')'
46-
alternative -> rewrite(node[0]) + ... + rewrite(node[n-1])
47-
optional -> '(?:' + rewrite(node[0]) + ... + rewrite(node[n-1]) + ')?'
48-
parameter -> {
49-
parameter_name := node[0].text + ... + node[n-1].text
50-
parameter_pattern := parameter_type_registry[parameter_name]
51-
'((?:' + parameter_pattern[0] + ')|(?:' ... + ')|(?:' + parameter_pattern[n-1] + '))'
52-
}
53-
text -> {
54-
escape_regex := escape '^', `$`, `[`, `]`, `(`, `)` `\`, `{`, `}`, `.`, `|`, `?`, `*`, `+`
55-
escape_regex(token.text)
56-
}
105+
#### Scala
106+
107+
```scala
108+
ParameterType("color", "red|blue|yellow") { color: String => // name, regexp
109+
Color(color) // transformer function, type
110+
}
57111
```
58112

113+
#### JavaScript / TypeScript
114+
115+
```javascript
116+
import { defineParameterType } from 'cucumber'
117+
118+
defineParameterType({
119+
name: 'color',
120+
regexp: /red|blue|yellow/,
121+
transformer: s => new Color(s)
122+
})
123+
```
124+
125+
The `transformer` function may return a `Promise`.
126+
127+
#### Ruby
128+
129+
```ruby
130+
ParameterType(
131+
name: 'color',
132+
regexp: /red|blue|yellow/,
133+
type: Color,
134+
transformer: ->(s) { Color.new(s) }
135+
)
136+
```
137+
138+
## Optional text
139+
140+
It's grammatically incorrect to say *1 cucumbers*, so we should make the plural **s**
141+
optional. That can be done by surrounding the optional text with parentheses:
142+
143+
I have {int} cucumber(s) in my belly
144+
145+
That expression would match this text:
146+
147+
I have 1 cucumber in my belly
148+
149+
It would also match this text:
150+
151+
I have 42 cucumbers in my belly
152+
153+
In Regular Expressions, parentheses indicate a capture group, but in Cucumber Expressions
154+
they mean *optional text*.
155+
156+
## Alternative text
157+
158+
Sometimes you want to relax your language, to make it flow better. For example:
159+
160+
I have {int} cucumber(s) in my belly/stomach
161+
162+
This would match either of those texts:
163+
164+
I have 42 cucumbers in my belly
165+
I have 42 cucumbers in my stomach
166+
167+
Alternative text only works when there is no whitespace between the alternative parts.
168+
169+
## Escaping
170+
171+
If you ever need to match `()` or `{}` literally, you can escape the
172+
opening `(` or `{` with a backslash:
173+
174+
I have {int} \{what} cucumber(s) in my belly \(amazing!)
175+
176+
This expression would match the following examples:
177+
178+
I have 1 {what} cucumber in my belly (amazing!)
179+
I have 42 {what} cucumbers in my belly (amazing!)
180+
181+
You may have to escape the `\` character itself with another `\`, depending on your programming language.
182+
For example, in Java, you have to use escape character `\` with another backslash.
183+
184+
I have {int} \\{what} cucumber(s) in my belly \\(amazing!)
185+
186+
Then this expression would match the following example:
187+
188+
I have 1 \{what} cucumber in my belly \(amazing!)
189+
I have 42 \{what} cucumbers in my belly \(amazing!)
190+
191+
There is currently no way to escape a `/` character - it will always be interpreted
192+
as alternative text.
193+
194+
## Architecture
195+
196+
See [ARCHITECTURE.md](ARCHITECTURE.md)
197+
59198
## Acknowledgements
60199

61200
The Cucumber Expression syntax is inspired by similar expression syntaxes in
62-
other BDD tools, such as [Turnip](https://github.com/jnicklas/turnip),
63-
[Behat](https://github.com/Behat/Behat) and
201+
other BDD tools, such as [Turnip](https://github.com/jnicklas/turnip),
202+
[Behat](https://github.com/Behat/Behat) and
64203
[Behave](https://github.com/behave/behave).
65204

66205
Big thanks to Jonas Nicklas, Konstantin Kudryashov and Jens Engel for
67206
implementing those libraries.
68207

69208
The [Tiny-Compiler-Parser tutorial](https://blog.klipse.tech/javascript/2017/02/08/tiny-compiler-parser.html)
70209
by [Yehonathan Sharvit](https://github.com/viebel) inspired the design of the
71-
Cucumber expression parser.
210+
Cucumber expression parser.

0 commit comments

Comments
 (0)