Skip to main content

Debug-String

SYNOPSIS​

Outputs a string in diagnostic form or as source code.

SYNTAX​

Standard (Default)​

Debug-String [-InputObject] <Object[]> [-Delimiters <String[]>] [-NoSpacesAsDots] [-NoEmphasis] [-SingleLine]
 [-UnicodeEscapes] [-ProgressAction <ActionPreference>] [<CommonParameters>]

AsSourceCode​

Debug-String [-InputObject] <Object[]> [-AsSourceCode] [-SingleLine] [-UnicodeEscapes]
 [-ProgressAction <ActionPreference>] [<CommonParameters>]

Caret​

Debug-String [-InputObject] <Object[]> [-Delimiters <String[]>] [-CaretNotation] [-NoSpacesAsDots]
 [-NoEmphasis] [-UnicodeEscapes] [-ProgressAction <ActionPreference>] [<CommonParameters>]

DESCRIPTION​

Author: Michael Klement

Prints a string with control or hidden characters visualized, and optionally all non-ASCII-range Unicode characters represented as escape sequences.

With -AsSourceCode, the result is printed in single-line form as a double-quoted PowerShell string literal that is reusable as source code,

Common control characters are visualized using PowerShell's own escaping notation by default, such as "t" for a tab, "r" for a CR, but a LF is visualized as itself, as an actual newline, unless you specify -SingleLine.

As an alternative, if you want ASCII-range control characters visualized in caret notation (see https://en.wikipedia.org/wiki/Caret_notation), similar to cat -A on Linux, use -CaretNotation. E.g., ^M then represents a CR; but note that a LF is always represented as "$" followed by an actual newline.

Any other control characters as well as otherwise hidden characters or format / punctuation characters in the non-ASCII range are represented in `u{hex-code-point} notation.

To print space characters as themselves, use -NoSpacesAsDots.

$null inputs are accepted, but a warning is issued.

EXAMPLES​

EXAMPLE 1​

"a`ab`t c`0d`r`n" | Debug-String -Delimiters [, ]
[a`0b`t·c`0d`r`
]

EXAMPLE 2​

"a`ab`t c`0d`r`n" | Debug-String -CaretNotation
a^Gb^I c^@d^M$

EXAMPLE 3​

"a-ü`u{2028}" | Debug-String -UnicodeEscapes # The dash is an em-dash (U+2014)
a·`u{2014}·`u{fc}

EXAMPLE 4​

"a`ab`t c`0d`r`n" | Debug-String -AsSourceCode -SingleLine # roundtrip
"a`ab`t c`0d`r`n"

PARAMETERS​

-InputObject​

Defines the string to analyze

Type: Object[]
Parameter Sets: (All)
Aliases:

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

-Delimiters​

You may optionally specify delimiters that the visualization of each input string is enclosed in as a a whole its boundaries. You may specify a single string or a 2-element array.

Type: String[]
Parameter Sets: Standard, Caret
Aliases:

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

-CaretNotation​

Causes LF to be visualized as "$" and all other ASCII-range control characters in caret notation, similar to cat -A on Linux.

Type: SwitchParameter
Parameter Sets: Caret
Aliases:

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

-NoSpacesAsDots​

By default, space chars. are visualized as "·", the MIDDLE DOT char. (U+00B7)

Use this switch to represent spaces as themselves.

Type: SwitchParameter
Parameter Sets: Standard, Caret
Aliases:

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

-NoEmphasis​

By default, those characters (other than spaces) that aren't output as themselves, i.e. control characters and, if requested with -UnicodeEscapes, non-ASCII-range characters, are highlighted by color inversion, using ANSI (VT) escape sequences.

Use this switch to turn off this highlighting.

Note that if $PSStyle.OutputRendering = 'PlainText' is in effect, the highlighting isn't shown even without -NoEmphasis, but the escape sequences are still part of the output string. Only -NoEmphasis prevents inclusion of these escape sequences.

Type: SwitchParameter
Parameter Sets: Standard, Caret
Aliases:

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

-AsSourceCode​

Outputs each input string as a double-quoted PowerShell string that is reusable in source code, with embedded double quotes, backticks, and "$" signs backtick-escaped.

Use -SingleLine to get a single-line representation. Control characters that have no native PS escape sequence are represented using `u{<hex-code-point} notation, which will only work in PowerShell Core (v6+) source code.

Type: SwitchParameter
Parameter Sets: AsSourceCode
Aliases:

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

-SingleLine​

Requests a single-line representation, where LF characters are represented as `n instead of actual line breaks.

Type: SwitchParameter
Parameter Sets: Standard, AsSourceCode
Aliases:

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

-UnicodeEscapes​

Requests that all non-ASCII-range characters - such as accented letters - in the input string be represented as Unicode escape sequences in the form `u{hex-code-point}.

Whe cominbed with -AsSourceCode, the result is a PowerShell string literal composed of ASCII-range characters only, but note that only PowerShell Core (v6+) understands such Unicode escapes.

By default, only control characters that don't have a native PS escape sequence / cannot be represented with caret notation are represented this way.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-ProgressAction​

{{ Fill ProgressAction Description }}

Type: ActionPreference
Parameter Sets: (All)
Aliases: proga

Required: False
Position: Named
Default value: None
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​

OUTPUTS​

NOTES​

EDIT THIS DOC​

This page was auto-generated from the powershell command comment based help. To edit the content of this page, update the script file comment based help on github Github