Clear‑AnsiSequence

SYNOPSIS

Clears ANSI CSI sequences from a string.

SYNTAX

Clear-AnsiSequence [-InputString] <String> [-RemovePartial] 
 [<CommonParameters>]

DESCRIPTION

The Clear-AnsiSequence command clears ANSI CSI (Control Sequence Introducer) sequences from a string, returning only the visible text content. This includes SGR (Select Graphic Rendition) sequences for colors and formatting, as well as cursor control sequences.

This is useful for calculating the actual visible length of strings that contain ANSI formatting codes, or for extracting plain text from formatted console output.

Note: This function specifically handles CSI sequences (ESC[ or just [). Other ANSI escape sequence types like OSC, DCS, PM, or APC are not processed.

EXAMPLES

EXAMPLE 1

Clear-AnsiSequence -InputString "`e[32mGreen text`e[0m"

This example clears ANSI CSI sequences from a string with properly escaped sequences, returning "Green text".

EXAMPLE 2

Clear-AnsiSequence -InputString "[31mRed text[0m"

This example clears ANSI CSI sequences from a string with unescaped sequences, returning "Red text".

EXAMPLE 3

Clear-AnsiSequence -InputString "Value is [32] units"

This example shows that plain bracketed numbers are preserved, returning "Value is [32] units".

EXAMPLE 4

Clear-AnsiSequence -InputString "[31incomplete" -RemovePartial

This example shows how the -RemovePartial switch removes unterminated sequences, returning "incomplete".

EXAMPLE 5

Clear-AnsiSequence -InputString "`e[1;37;44mBold white on blue`e[0m and plain text"

This example clears complex ANSI CSI sequences, returning "Bold white on blue and plain text".

EXAMPLE 6

$visibleLength = (Clear-AnsiSequence -InputString $formattedString).Length

This example shows how to get the visible length of a string that contains ANSI CSI sequences.

PARAMETERS

-InputString

The string from which ANSI CSI sequences should be cleared. The string can contain any combination of ANSI CSI sequences with or without proper escape characters.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-RemovePartial

When specified, also removes unterminated ANSI CSI sequences that don't end with 'm'. By default, unterminated sequences like "[31" are preserved to avoid accidentally removing plain bracketed numbers.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

OUTPUTS

System.String

NOTES

This function handles various ANSI CSI (Control Sequence Introducer) sequence formats including:

• Properly escaped SGR sequences: `e[32m or [char]0x1b[32m (colors and formatting)
• Unescaped SGR sequences: [32m (only when they end with 'm')
• Non-SGR CSI sequences: ESC[2K, ESC[H (cursor control, only when properly escaped)
• Complex sequences with multiple codes: [1;37;44m

The function uses a three-pass approach: 1. Remove complete CSI sequences that start with an escape character 2. Remove SGR-like patterns that aren't escaped but end with 'm' 3. Optionally remove incomplete sequences with -RemovePartial

Plain bracketed numbers like "[32]" are preserved unless -RemovePartial is used.

Limitation: This function does not handle other ANSI escape sequence types such as OSC (Operating System Command), DCS (Device Control String), PM (Privacy Message), or APC (Application Program Command) sequences.

RELATED LINKS