PowerShell

The engine is a PowerShell module, Trex, built from the repository’s powershell/ directory with PWRS. Its 49 cmdlets cover what the command line does. Each takes text from the pipeline or files by path, writes objects a pipeline can sort, group and select, and answers to a second name with the Tx prefix: Select-TxMatch is Select-TrexMatch. It runs in PowerShell 7 on Windows x64, Linux x64, FreeBSD x64 and macOS arm64, and in Windows PowerShell 5.1, from one module; its Pester suites pass on each. The examples are on the task pages, under each one’s PowerShell tab.

Trex installs from the PowerShell Gallery:

Install-Module Trex

A checkout builds the module with PWRS 0.3.1 from crates.io and cargo pwrs of the same release:

cargo install cargo-pwrs --version 0.3.1
cd powershell
cargo pwrs build --release
Import-Module ./target/pwrs/Trex

Built from powershell/, the module’s library targets the baseline CPU of its architecture, x86-64 (apple-a14 on macOS), whatever target-cpu the host’s cargo config names; trex picks its AVX2 and AVX-512 kernels at run time. cargo pwrs test --release runs the module’s Rust tests and then its Pester suites in PowerShell 7 and in Windows PowerShell 5.1. The report suites compare the module’s output with the command’s, so TREX_CLI names a trex binary built from the same tree.

How the cmdlets read and write

Concern	Behavior
Patterns	trex source text inside single quotes, so PowerShell leaves `$` and backslashes alone, or a `Trex.Pattern` from `New-TrexPattern`, compiled against the atoms in force; several patterns scan as one set
Text	`-InputObject`, or strings piped in, each read on its own; `Group-TrexMatch`, `Get-TrexRecordShape`, `New-TrexBpe`, `New-TrexPrefilter` and `Test-TrexPrefilter` read every string piped in as one input
Files	`-Path` expands wildcards; `-LiteralPath` takes a path as written and binds the `Path` of what `Get-ChildItem` pipes. A directory is walked under `.gitignore` and `.ignore` rules with hidden files and files holding a NUL byte skipped, which `-Hidden`, `-NoIgnore` and `-Binary` widen. A file in UTF-16 or UTF-32 with a byte-order mark reads as its text. A relative `@file` a pattern names is read from the current location
Offsets	`Start` and `Length` count UTF-16 code units, so `$text.Substring($m.Start, $m.Length)` is the match; `LineNumber` and `Column` count from 1
Values	a register’s `Value` is the .NET type of its kind: a number a `long` or a `decimal`, a duration a `TimeSpan`, a timestamp a `DateTimeOffset`, an address or a version its canonical text
Atoms	`Register-TrexAtom` and `Import-TrexAtom` declare atoms for the session, held in `$TrexSession`; `-Library` hands a cmdlet a `Trex.Library` in their place
Changes	every cmdlet that writes a file takes `-WhatIf` and `-Confirm`, as do `Set-TrexClock` and `Unregister-TrexAtom`
Refusals	parameters that contradict each other stop the cmdlet with an error that names them

Matching

Select-TrexMatch, Test-TrexMatch, compiled patterns, file walks and indexes.

Rewriting

Edit-TrexText and Protect-TrexText.

Grouping

Group-TrexMatch.

Records and tokens

Tokens, records, record shapes, record queries and built patterns.

Rules

Get-TrexRule, Invoke-TrexRule and ConvertTo-TrexSarif.

Atoms and settings

Atoms for the session or a library, their tests, and the clock.

Property axes

The ten Measure-Trex cmdlets.

Streams and grammars

Stream scanners, token grammars, byte-pair encoders and presence filters.

Types

Every class and enumeration the cmdlets write and take.

Every cmdlet

Cmdlet	Does
Select-TrexMatch	Finds every match of a trex pattern in text, files or directories and writes each as a Trex.Match.
Test-TrexMatch	Tells whether a trex pattern matches text or the files named.
Get-TrexLine	Writes an input’s first lines, its last, or a range of them, as the trex command’s head, tail and lines print them.
New-TrexPattern	Compiles a trex pattern against the atoms in force, for reuse across commands and as an object with IsMatch, Find, FindAll, Replace and Split methods.
Get-TrexFile	Lists the files a scan of the paths would read, without scanning them.
Get-TrexFileType	Lists the file types -FileType and -ExcludeFileType take, each with the globs a file of it matches: ripgrep’s types, under ripgrep’s names.
New-TrexIndex	Writes the index of each tree named at its root, so every later scan of the tree opens only the files that can match.
Get-TrexIndex	Writes what the index at each tree’s root holds.
Edit-TrexText	Replaces each match of a trex pattern with a rendered template or with what a script block returns for it.
Protect-TrexText	Masks each match of a trex pattern, keeping the fields named.
Group-TrexMatch	Groups the matches of a trex pattern by a rendered key, with the count of each and aggregates over a register’s typed values.
Get-TrexToken	Lists the tokens trex reads an input as, with each token’s kind and its value parsed as that kind.
Get-TrexRecord	Splits an input into records: lines, paragraphs, blocks, or the other units trex reads a record as.
Get-TrexRecordShape	Lists the record shapes an input repeats, most frequent first: each distinct sequence of token kinds once, with how many records have it.
Find-TrexRecord	Finds the records of an input that hold all, any, none or at least some number of the patterns given, and none of the patterns -Not gives.
ConvertTo-TrexPattern	Infers the most specific trex pattern every example matches, verified against each.
ConvertFrom-TrexText	Converts lines of text to objects, one per line a pattern reads, with a property per field, as ConvertFrom-String does from a template.
ConvertTo-TrexLiteral	Escapes a text so a trex pattern matches it literally.
Get-TrexRule	Lists the rules declared for the session, in a library, or in the rule files named, in declaration order.
Invoke-TrexRule	Scans the rules declared in pattern files over text, files or directories, and writes each finding as a Trex.Finding.
ConvertTo-TrexSarif	Renders findings as one SARIF 2.1.0 document, for a CI system or an editor that reads one.
Register-TrexAtom	Declares an atom a pattern reads by name as `\{name}`: a byte shape, a kind fused from a pattern, or a named sub-pattern.
Import-TrexAtom	Declares every atom the pattern files say: their `let`, `kind`, `shape`, `shape-after`, `rule` and `test` lines, with a relative `@file` set read from beside each file.
Get-TrexAtom	Lists the atoms declared for this session, in a library, or shipped with trex, in declaration order.
Test-TrexAtom	Runs the `test` lines declared for the session, a library, or the atoms trex ships, and writes one result per line.
Unregister-TrexAtom	Removes atoms from the session or a library: by name, by the pattern file that declared them, or all of them.
New-TrexLibrary	Makes a library: a set of atoms held in an object, passed to a cmdlet with -Library, which reads it in place of the session’s atoms.
Get-TrexClock	Writes the clock typed predicates read: the instant `now` is, whether it is fixed, the offset a timestamp with no zone is read at, and the order of a slash date’s fields.
Set-TrexClock	Sets the clock typed predicates read, for every later scan in this PowerShell process.
Get-TrexInfo	Writes the trex engine’s version and whether a CUDA device is present.
Measure-TrexMagnitude	Reads the magnitude axis: each token’s order of magnitude, its change from the token before, and the energy of the window behind it.
Measure-TrexStress	Reads the stress axis: how deeply the paired brackets nest at each token, how long the innermost has been held open, and how long all of them together.
Measure-TrexFlow	Reads the flow axis: the trend of a per-token signal, the magnitude by default, how long it has run one way, and where it reverses.
Measure-TrexObservation	Reads the observation axis: the entropy of the byte classes behind each byte, ahead of it and around it, and the points where behind and ahead differ most.
Measure-TrexEcho	Reads the echo axis: which words, numbers and literals recur, how many times, and whether they recur at a regular distance.
Measure-TrexOrbit	Reads the orbit axis: each token as the representative of its orbit under a symmetry, and how far the symmetry folds the input’s vocabulary.
Measure-TrexShape	Reads the shape axis: each token’s shape, the period at which the shapes repeat, and the regions that repeat like a table or a list of records.
Measure-TrexRelation	Reads the relation axis: the graph an input’s brackets, binding punctuation, adjacency and repeated content make, and what that graph’s tree and its loops measure.
Measure-TrexSpectral	Reads the spectral axis: the entropy, byte period, novelty and class mix of an input’s bytes along its length, where they change, and the texture of each stretch between, prose, code, mathematics, data or mixed.
Measure-TrexSeam	Reads the seam axis: where an input divides into units, found where the text before a point stops predicting the text after it, read in both directions, with no dictionary.
New-TrexStreamScanner	Begins a scan of input that arrives in pieces: a Trex.StreamScanner whose Push method takes each chunk and gives back the matches no later chunk can change, and whose Finish method gives back the rest.
New-TrexGrammar	Compiles a token grammar for Invoke-TrexGrammar and as an object with Parse, Test, CountParses, BestProbability, TotalProbability, CountSegmentations and BestSegmentationProbability methods.
Invoke-TrexGrammar	Parses text against a token grammar and writes the parse tree, or with -Count, -Best or -Probability a value over every derivation.
New-TrexBpe	Learns a byte-pair encoder from a corpus.
Import-TrexBpe	Reads a byte-pair encoder from a model file, one Export-TrexBpe or the trex command’s `bpe train` wrote.
Export-TrexBpe	Writes a byte-pair encoder’s model to a file, one merge a line with its two symbols separated by a tab, which Import-TrexBpe and the trex command’s `bpe encode --model` read.
ConvertTo-TrexBpe	Splits text into a byte-pair encoder’s subwords, writing each subword.
New-TrexPrefilter	Builds a presence filter over a corpus, as an object whose MightContain method answers whether a literal might occur in it.
Test-TrexPrefilter	Tests literals against a presence filter built over a corpus, or with -Verify every filter’s contract over it.