Regex

Learn how to use regex in Vale.

Vale runs its rules on regexp2, in its RE2 compatibility mode: the syntax of Go's standard regexp package, plus the lookahead and lookbehind assertions that package leaves out.

This guide provides an overview of regex syntax supported by Vale, along with tips for writing regular expressions in YAML files.

Syntax

For the base syntax, see the Go docs. For what regexp2 adds, see its README.

The most commonly used assertion constructs are:

• Positive lookahead: (?=re)
• Negative lookahead: (?!re)
• Positive lookbehind: (?<=re)
• Negative lookbehind: (?<!re)

This extended syntax is supported everywhere in Vale, except for script-based rules (which are limited to the standard Go regex syntax).

YAML

Wrap all regex in single (') or double (") quotes to avoid YAML interpreting special characters:

• Single quotes ('): Prevent YAML from interpreting any characters except single quotes themselves.
• Double quotes ("): Allow YAML to interpret escape sequences like \n and \t, so you’ll need to escape backslashes.

In general, this means that you should prefer single quotes for most cases:

extends: existence
message: Consider removing '%s'
level: warning
# A typical rule with single quotes:
tokens:
  - '([A-Z]\w+)([A-Z]\w+)'

If you need to use a single quote in your regex, you can escape it with another single quote:

extends: existence
message: Consider removing '%s'
level: warning
# A rule with a single quote in the regex:
tokens:
  - '([A-Z]\w+)([A-Z]\w+)''s'

Vale Studio

Vale Studio provides a rule editor that integrates with regex101 to allow you to inspect the compiled regex pattern and test it against sample text. This can be a helpful way to debug your regex patterns.

Vale Studio

Common Issues

Word Boundaries

In regex, \b is a word boundary assertion that matches the position between a word character and a non-word character.

For example, the regex \bfoo\b will only match the word “foo” and not “foobar” or “foo-bar”.

By default, existence and substitution rules in Vale will automatically add word boundaries to the beginning and end of each token.

To disable this behavior, set nonword to true:

extends: existence
message: Consider removing '%s'
nonword: true
tokens:
  - some token

raw is the other way out: it takes your pattern verbatim, boundaries and all.

Word boundaries need watching in non-Latin scripts. \b sits between a word character ([0-9A-Za-z_]) and anything else, so in a script with no word characters it never matches—and the rule finds nothing at all, with no error to say why. See WordTemplate if that's your content.

Scoping

For markup-based rules, Vale converts each document to HTML and applies a scoping system before running any rules.

This means that if you’re writing a rule that targets markup syntax or needs to match across block boundaries, the results may be different from what you expect.

If you like to apply a rule to the entire, unprocessed document, you can use scope: raw:

extends: existence
message: Consider removing '%s'
scope: raw
tokens:
  - some token