# tbRegExp Package
{: .no_toc }

**Author:** GCuser99. **Version:** 1.9.0.0. **On GitHub:** [GCuser99/tbRegExp](https://github.com/GCuser99/tbRegExp), in the folder *Package*.

The **tbRegExp** contributed package provides regular expressions for twinBASIC projects, as a replacement for the **RegExp** object of VBScript. It follows the same object model. A [**RegExp**](/tB/Packages/Contributed/tbRegExp/RegExp/index.md) is given a pattern and options, its [**Execute**](/tB/Packages/Contributed/tbRegExp/RegExp/Execute.md) method returns a [**MatchCollection**](/tB/Packages/Contributed/tbRegExp/MatchCollection/index.md) of [**Match**](/tB/Packages/Contributed/tbRegExp/Match/index.md) objects, and each **Match** holds the text captured by the groups of the pattern as a [**SubMatches**](/tB/Packages/Contributed/tbRegExp/SubMatches/index.md) object. Positions are zero-based, as in VBScript.

The matching is done by the [vba-regex](https://github.com/sihlfall/vba-regex) engine of sihlfall, which the package includes as a private module, **StaticRegex**.

```tb check_build check_run
Dim re As New RegExp
re.Pattern = "\d+"
re.Global = True
Debug.Print re.Test("a1b22c333")              ' True
Debug.Print re.Execute("a1b22c333").Count     ' 3
Debug.Print re.Execute("a1b22c333")(1).Value  ' 22
Debug.Print re.Replace("a1b22c333", "#")      ' a#b#c#
```

Beyond VBScript's object, **RegExp** has the [**DotAll**](/tB/Packages/Contributed/tbRegExp/RegExp/DotAll.md) and [**Flags**](/tB/Packages/Contributed/tbRegExp/RegExp/Flags.md) options, the [**Split**](/tB/Packages/Contributed/tbRegExp/RegExp/Split.md) method, [**IsValid**](/tB/Packages/Contributed/tbRegExp/RegExp/IsValid.md), [**LastError**](/tB/Packages/Contributed/tbRegExp/RegExp/LastError.md) and [**LastErrorNumber**](/tB/Packages/Contributed/tbRegExp/RegExp/LastErrorNumber.md), which report an invalid pattern before it is used, and [**SearchStepLimit**](/tB/Packages/Contributed/tbRegExp/RegExp/SearchStepLimit.md), which bounds a runaway search. [**Replace**](/tB/Packages/Contributed/tbRegExp/RegExp/Replace.md) reads a `$` in the replacement string as VBScript does, and adds `$<name>` for a named group.

## Pattern syntax

A pattern written for VBScript's **RegExp** needs no change. **tbRegExp** also accepts named groups, lookbehind, and the `i`, `m` and `s` options inside the pattern:

```tb check_build check_run
Dim re As New RegExp
re.Pattern = "(?<year>\d{4})-(?<month>\d{2})"
Debug.Print re.Execute("2026-10")(0).SubMatches("month")  ' 10
Debug.Print re.Replace("2026-10", "$<month>/$<year>")     ' 10/2026
```

[**Pattern syntax**](/tB/Packages/Contributed/tbRegExp/PatternSyntax.md) covers those in full, along with the escapes, the character classes and the brace rules.

## Searches that give up

This is the one place where **tbRegExp** behaves differently from VBScript's **RegExp** rather than adding to it.

A pattern that backtracks without end, such as `(a+)+b` on a string of thirty `a`, does not hang a search as it does in VBScript's **RegExp**. Every search is given a budget of steps, and when it runs out the search raises an error rather than returning a result it never established. A long match is no problem: `a*` and `^.*$` match a string of 1,000,000 `a` whole.

```tb check_build check_run
Dim re As New RegExp
re.Pattern = "(a+)+b"
On Error Resume Next
re.Test String(30, "a")
Debug.Print Err.Number - vbObjectError   ' 3016
On Error GoTo 0
Err.Clear

re.Pattern = "^.*$"
Debug.Print re.Test(String(100000, "a"))   ' True
```

[**SearchStepLimit**](/tB/Packages/Contributed/tbRegExp/RegExp/SearchStepLimit.md) explains the budget, shows the message, and raises the ceiling when a search genuinely needs more.

## Classes

- [Match](/tB/Packages/Contributed/tbRegExp/Match/index.md) -- holds one match that a RegExp found in a string: the matched text, where it starts, how many characters it has, and the text captured by its groups
  - [FirstIndex](/tB/Packages/Contributed/tbRegExp/Match/FirstIndex.md) -- returns the zero-based position where the match starts
  - [Length](/tB/Packages/Contributed/tbRegExp/Match/Length.md) -- returns the number of characters in the match
  - [SubMatches](/tB/Packages/Contributed/tbRegExp/Match/SubMatches.md) -- returns the text captured by the groups of the pattern
  - [Value](/tB/Packages/Contributed/tbRegExp/Match/Value.md) -- returns the matched text (default member)
- [MatchCollection](/tB/Packages/Contributed/tbRegExp/MatchCollection/index.md) -- holds the Match objects that a regular expression finds in a string
  - [Count](/tB/Packages/Contributed/tbRegExp/MatchCollection/Count.md) -- returns the number of matches
  - [Item](/tB/Packages/Contributed/tbRegExp/MatchCollection/Item.md) -- returns one match by position (the default member)
  - [NewEnum](/tB/Packages/Contributed/tbRegExp/MatchCollection/NewEnum.md) -- returns the enumerator that For Each uses (hidden)
- [RegExp](/tB/Packages/Contributed/tbRegExp/RegExp/index.md) -- searches strings with a regular expression: finds the matches, tests for one, replaces them and splits a string at them
  - [DotAll](/tB/Packages/Contributed/tbRegExp/RegExp/DotAll.md) -- returns or sets whether `.` matches a line feed
  - [Execute](/tB/Packages/Contributed/tbRegExp/RegExp/Execute.md) -- returns the matches in a string
  - [Flags](/tB/Packages/Contributed/tbRegExp/RegExp/Flags.md) -- returns or sets the four options as a string of letters
  - [Global](/tB/Packages/Contributed/tbRegExp/RegExp/Global.md) -- returns or sets whether all matches are used
  - [IgnoreCase](/tB/Packages/Contributed/tbRegExp/RegExp/IgnoreCase.md) -- returns or sets whether letter case is ignored
  - [IsValid](/tB/Packages/Contributed/tbRegExp/RegExp/IsValid.md) -- returns whether the pattern compiles
  - [LastError](/tB/Packages/Contributed/tbRegExp/RegExp/LastError.md) -- returns the message of the compile error
  - [LastErrorNumber](/tB/Packages/Contributed/tbRegExp/RegExp/LastErrorNumber.md) -- returns the number of the compile error
  - [MultiLine](/tB/Packages/Contributed/tbRegExp/RegExp/MultiLine.md) -- returns or sets whether `^` and `$` match at line boundaries
  - [Pattern](/tB/Packages/Contributed/tbRegExp/RegExp/Pattern.md) -- returns or sets the regular expression
  - [Replace](/tB/Packages/Contributed/tbRegExp/RegExp/Replace.md) -- replaces the matches in a string
  - [SearchStepLimit](/tB/Packages/Contributed/tbRegExp/RegExp/SearchStepLimit.md) -- returns or sets the step budget that stops a runaway search
  - [Split](/tB/Packages/Contributed/tbRegExp/RegExp/Split.md) -- splits a string at the matches
  - [Test](/tB/Packages/Contributed/tbRegExp/RegExp/Test.md) -- returns whether a string contains a match
- [SubMatches](/tB/Packages/Contributed/tbRegExp/SubMatches/index.md) -- holds the strings that the capture groups of a pattern captured in one Match
  - [Count](/tB/Packages/Contributed/tbRegExp/SubMatches/Count.md) -- returns the number of strings
  - [Item](/tB/Packages/Contributed/tbRegExp/SubMatches/Item.md) -- returns one string by position or by group name (the default member)
  - [NewEnum](/tB/Packages/Contributed/tbRegExp/SubMatches/NewEnum.md) -- returns the enumerator that For Each uses (hidden)

## Test cases

The notes and warnings of this section are checked by the test cases in [tbRegExp-tests.twinproj](tbRegExp-tests.twinproj), a twinBASIC project. It uses tbRegExp as a [linked package](/Features/Packages/Linked.md#manual-management): put the package's `.twinpack` in `%APPDATA%\twinBASIC\packages`, then run the project, and each case prints whether it passes.
