Cucumber.Expression (Cucumber v0.8.0)

View Source

Parser and matcher for Cucumber Expressions used in step definitions.

Cucumber Expressions are a human-friendly alternative to regular expressions, allowing you to define step patterns with typed parameters. This module handles compiling these expressions and extracting/converting parameters using NimbleParsec.

This implementation follows the official Cucumber Expression syntax from https://github.com/cucumber/cucumber-expressions

Parameter Types

The following parameter types are supported:

  • {string} - Matches quoted strings ("example") and converts to string
  • {int} - Matches integers (42, -5) and converts to integer
  • {float} - Matches floating point numbers (3.14, -0.5) and converts to float
  • {word} - Matches a single word (no whitespace) and converts to string
  • {atom} - Matches a word and converts to atom (pending -> :pending)

Advanced Features

  • Optional text: Use (text) for optional text that may or may not be present
  • Alternation: Use word1/word2 to match alternative words (not captured)
  • Optional parameters: Use {int?} for optional matching (returns nil if absent)
  • Escape sequences: Use \(, \), \/, \{, \}, \\ for literal characters

Examples

# Matching a step with a string parameter
"I click {string} button" matches "I click \"Submit\" button"

# Matching a step with multiple parameters
"I add {int} items to my {word} list" matches "I add 5 items to my shopping list"

# Optional text (for pluralization)
"I have {int} cucumber(s)" matches "I have 1 cucumber" and "I have 5 cucumbers"

# Alternation
"I click/tap the button" matches "I click the button" or "I tap the button"

# Optional parameter
"I have {int?} items" matches both "I have 5 items" and "I have items"

Summary

Functions

compile(pattern)

Compiles a Cucumber Expression pattern into a matchable AST.

match(text, compiled)

Matches a step text against a compiled Cucumber Expression.

parse_atom_param(binary, opts \\ [])

Parses the given binary as parse_atom_param.

parse_float_param(binary, opts \\ [])

Parses the given binary as parse_float_param.

parse_int_param(binary, opts \\ [])

Parses the given binary as parse_int_param.

parse_string_param(binary, opts \\ [])

Parses the given binary as parse_string_param.

parse_word_param(binary, opts \\ [])

Parses the given binary as parse_word_param.

Functions

compile(pattern)

Compiles a Cucumber Expression pattern into a matchable AST.

This function transforms a human-readable pattern with typed parameters into an AST that can be used for matching step text.

Parameters

  • pattern - A string containing a Cucumber Expression pattern

Returns

Returns a compiled expression (list of AST nodes) that can be passed to match/2.

Examples

iex> compiled = Cucumber.Expression.compile("I have {int} items")
iex> is_list(compiled)
true

match(text, compiled)

Matches a step text against a compiled Cucumber Expression.

This function attempts to match step text against a compiled Cucumber Expression and extracts/converts any parameters if there's a match.

Parameters

  • text - The step text to match against the pattern
  • compiled - A compiled Cucumber Expression from compile/1

Returns

Returns one of:

  • {:match, args} - If the text matches, where args is a list of converted parameter values
  • :no_match - If the text doesn't match the expression

Examples

iex> compiled = Cucumber.Expression.compile("I have {int} items")
iex> Cucumber.Expression.match("I have 42 items", compiled)
{:match, [42]}
iex> Cucumber.Expression.match("I have no items", compiled)
:no_match

parse_atom_param(binary, opts \\ [])

@spec parse_atom_param(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_atom_param.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_atom_param (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map

parse_float_param(binary, opts \\ [])

@spec parse_float_param(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_float_param.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_float_param (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map

parse_int_param(binary, opts \\ [])

@spec parse_int_param(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_int_param.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_int_param (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map

parse_string_param(binary, opts \\ [])

@spec parse_string_param(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_string_param.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_string_param (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map

parse_word_param(binary, opts \\ [])

@spec parse_word_param(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_word_param.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_word_param (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map