Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Coming from PowerShell
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

Regular Expressions

Regular expressions in Nushell's commands and operators (such as =~, str replace --regex, parse --regex, and split row --regex) are handled by the fancy-regex crate. It supports the syntax of Rust's regex crate, and adds features such as look-around and backreferences. If you want to know more, check the crate documentation.

Write patterns in single quotes or raw strings. In a double-quoted string, Nushell reads each backslash as one of its own escapes first, so "\d" is a parse error.

Flags in the pattern

A pattern can turn on flags at its start: (?i) ignores case, (?m) makes ^ and $ match at the start and end of every line instead of the whole text, and (?s) lets . match a newline. They can be combined, as in (?im).

'Nushell' =~ '(?i)^nu'
# => true
'NUSHELL' =~ '^nu'
# => false

Matching text literally

When part of a pattern comes from a variable, characters such as . and + in it still act as regex syntax. Here .txt matches any character followed by txt, so atxt gets through:

let ext = '.txt'
['a.txt' 'atxt' 'b.txt.bak'] | where $it =~ $'($ext)$'
# => ╭───┬───────╮
# => │ 0 │ a.txt │
# => │ 1 │ atxt  │
# => ╰───┴───────╯

str escape-regex puts a backslash in front of each character that has a meaning in a pattern: \ . + * ? ( ) [ ] { } | ^ $ #. The escaped text matches only itself, and the rest of the pattern keeps working:

['a.txt' 'atxt' 'b.txt.bak'] | where $it =~ $'($ext | str escape-regex)$'
# => ╭───┬───────╮
# => │ 0 │ a.txt │
# => ╰───┴───────╯
'1+1=2' | str escape-regex
# => 1\+1=2

You need it only where Nushell reads a regex, such as the =~ and !~ operators and the --regex forms of str replace, parse, split row, split column, split list and find. Without --regex, those commands already match plain text, and so does str contains. Given a list of strings, str escape-regex escapes each one. For a table or record, name the columns to escape, as described in Lists, records and tables.

Replacing with str replace

With --regex, str replace treats the text to find as a regular expression, and the replacement can refer to capture groups. $1, $2 and so on insert numbered groups, and $name inserts a group named with (?<name>...):

'2024-01-15' | str replace --regex '(\d+)-(\d+)-(\d+)' '$3/$2/$1'
# => 15/01/2024
'2024-01-15' | str replace --regex '(?<y>\d+)-(?<m>\d+)-(?<d>\d+)' '${d}th of $m'
# => 15th of 01

A group reference takes every letter, digit and underscore that follows the $. In the second example, $dth would mean a group named dth. No group has that name, so it would insert nothing. Use braces, as in ${d} or ${1}, when more text follows the reference. Write $$ for a literal $. --no-expand (-n) turns all of this off and inserts the replacement as written:

'cost: 5' | str replace --regex '(\d+)' '$$$1'
# => cost: $5
'cost: 5' | str replace --regex --no-expand '(\d+)' '$1'
# => cost: $1

--multiline (-m) implies --regex and adds the (?m) flag, so ^ and $ match at every line. Without it, ^ matches only at the start of the text:

"a\nb" | str replace --all --regex '^' '> '
# => > a
# => b
"a\nb" | str replace --all --multiline '^' '> '
# => > a
# => > b

When the replacement is a closure, it runs once for each match. The whole match is its input, $in, and the capture groups are passed as its parameters, in order. A group that didn't take part in the match is null. The closure has to return a string:

'2024-01-15' | str replace --regex '(\d+)-(\d+)-(\d+)' {|y, m, d| $'($d).($m).($y)' }
# => 15.01.2024

The closure can declare fewer parameters than there are groups, but not more. A parameter with no group to fill it is a "Missing parameter" error.

Capture groups in parse

parse --regex makes a column for each capture group. A named group gives its name to the column. An unnamed group is named capture followed by its position among all the groups, counting from 0:

'ab12' | parse --regex '([a-z]+)(\d+)'
# => ╭───┬──────────┬──────────╮
# => │ # │ capture0 │ capture1 │
# => ├───┼──────────┼──────────┤
# => │ 0 │ ab       │ 12       │
# => ╰───┴──────────┴──────────╯
'ab12' | parse --regex '(?<letters>[a-z]+)(\d+)'
# => ╭───┬─────────┬──────────╮
# => │ # │ letters │ capture1 │
# => ├───┼─────────┼──────────┤
# => │ 0 │ ab      │ 12       │
# => ╰───┴─────────┴──────────╯

Each match in the string becomes a row, and a group that didn't take part in a match is null in that row. Use a non-capturing group, (?:...), for grouping that shouldn't become a column.

Look-around and backreferences make the regex engine backtrack, and a badly written pattern can then take a very long time on some inputs. The engine stops after a set number of backtracking steps, 1,000,000 by default, and parse fails with "Max limit for backtracking count exceeded". --backtrack sets a different limit. A higher one lets a slow pattern finish, and a lower one makes it fail sooner.

Splitting on a pattern

split row --regex and split column --regex split wherever the pattern matches. See Splitting Strings.

Edit this page on GitHub
Contributors: sakimyto, Jakub Žádník, Justin Ma, Hofer-Julian, fdncred
Prev
Working with Strings
Next
Working with Binary Data