From 95ae1e12fc1a64f9d7106b58341cf9eb7fcf5071 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 13 Jun 2024 10:44:15 -0500 Subject: [PATCH 1/2] Add ref content for TabExpansion2 (#11184) * Add ref content for TabExpansion2 * Apply suggestions from review --------- Co-authored-by: Mikey Lombardi (He/Him) --- .../About/about_Built-in_Functions.md | 40 +-- .../About/about_Tab_Expansion.md | 10 +- .../TabExpansion2.md | 243 ++++++++++++++++++ .../About/about_Built-in_Functions.md | 17 +- .../About/about_Tab_Expansion.md | 4 +- .../TabExpansion2.md | 233 +++++++++++++++++ .../About/about_Built-in_Functions.md | 17 +- .../About/about_Tab_Expansion.md | 4 +- .../TabExpansion2.md | 233 +++++++++++++++++ .../About/about_Built-in_Functions.md | 17 +- .../About/about_Tab_Expansion.md | 6 +- .../TabExpansion2.md | 233 +++++++++++++++++ 12 files changed, 1009 insertions(+), 48 deletions(-) create mode 100644 reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md create mode 100644 reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md create mode 100644 reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md create mode 100644 reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md index c5a9633d468..f9ae6bcc2dc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md @@ -1,7 +1,7 @@ --- description: Describes the built-in functions in PowerShell. Locale: en-US -ms.date: 07/17/2023 +ms.date: 06/13/2024 online version: https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/about/about_built-in_functions?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Built-in Functions @@ -33,10 +33,10 @@ In the Windows CMD shell it's common to run the `cd` command without any spaces between the command and the destination path. This function runs `Set-Location \` to change to the root folder. -## `Clear-Host` +## `Pause` -This function clears the screen. For more information, see -[Clear-Host](xref:Microsoft.PowerShell.Core.Clear-Host). +This function replicates the behavior of the `pause` command from `cmd.exe`. +The script pauses execution and prompts the user to hit a key to continue. ## `Get-Verb` @@ -52,34 +52,36 @@ the systems pager command, `more.com`. This function has been deprecated. It is an empty function that does nothing. -## `mkdir` +## `prompt` -This function provides a short hand way to run `New-Item -Type Directory` with -your parameters. +This is the function that creates the default prompt for the PowerShell command +line. You can customize your prompt by overriding this function with your own. +For more information see [about_Prompts](about_Prompts.md). ## `more` This function is a wrapper around the `more.com` native command. -## `oss` +## `Clear-Host` -This function provides a short hand way to run `Out-String -Stream` in a -pipeline. +This function clears the screen. For more information, see +[Clear-Host](xref:Microsoft.PowerShell.Core.Clear-Host). -## `Pause` +## `TabExpansion2` -This function replicates the behavior of CMD's `pause` command. The script -pauses execution and prompts the user to hit a key to continue. +This is the default function to use for tab expansion. For more information, see +[TabExpansion2](xref:Microsoft.PowerShell.Core.TabExpansion2). -## `prompt` +## `oss` -This is the function that creates the default prompt for the PowerShell command -line. You can customize your prompt by overriding this function with your own. -For more information see [about_Prompts](about_Prompts.md). +This function provides a short hand way to run `Out-String -Stream` in a +pipeline. For more information, see +[Out-String](xref:Microsoft.PowerShell.Utility.Out-String). -## `TabExpansion2` +## `mkdir` -This is the default function to use for tab expansion. +This function provides a short hand way to run `New-Item -Type Directory` with +your parameters. ## Windows drive letter functions diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 13db694412a..f41afac1619 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Tab Expansion feature in PowerShell. Locale: en-US -ms.date: 12/05/2023 +ms.date: 06/13/2024 no-loc: [Tab, Ctrl, Space] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_tab_expansion?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -16,9 +16,9 @@ file paths can all be completed by pressing the Tab key. ## Long description -Tab expansion is controlled by the internal function **TabExpansion** or -**TabExpansion2**. Since this function can be modified or overridden, this -discussion is a guide to the behavior of the default PowerShell configuration. +Tab expansion is controlled by the internal function **TabExpansion2**. Since +this function can be modified or overridden, this discussion is a guide to the +behavior of the default PowerShell configuration. Tab expansion behavior can also be modified by the Predictive IntelliSense feature of the PSReadLine module. For more information, see @@ -109,6 +109,7 @@ for some parameter. For more information, see ## See also +- [TabExpansion2][06] - [about_Comment_Based_Help][03] - [about_Functions_Argument_Completion][04] - [about_Requires][05] @@ -119,3 +120,4 @@ for some parameter. For more information, see [03]: about_Comment_Based_Help.md [04]: about_Functions_Argument_Completion.md [05]: about_Requires.md +[06]: xref:Microsoft.PowerShell.Core.TabExpansion2 diff --git a/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md new file mode 100644 index 00000000000..191548478e0 --- /dev/null +++ b/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md @@ -0,0 +1,243 @@ +--- +external help file: System.Management.Automation.dll-Help.xml +Module Name: Microsoft.PowerShell.Core +ms.date: 06/13/2024 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2?view=powershell-5.1&WT.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# TabExpansion2 + +## SYNOPSIS +A helper function that wraps the `CompleteInput()` method of the **CommandCompletion** class to +provide tab completion for PowerShell scripts. + +## SYNTAX + +### ScriptInputSet (Default) + +``` +TabExpansion2 [-inputScript] [[-cursorColumn] ] [[-options] ] + [] +``` + +### AstInputSet + +``` +TabExpansion2 [-ast] [-tokens] [-positionOfCursor] + [[-options] ] [] +``` + +## DESCRIPTION + +`TabExpansion2` is a built-in function that provides tab completion for user input. PowerShell calls +this function when the user presses the Tab or Ctrl+Space key while +typing a command. The function returns a list of possible completions for the current input. + +`TabExpansion2` isn't normally called directly by users. However, it can be useful for testing tab +completion. To use `TabExpansion2`, you need to provide the current input script and the cursor +position in the script. The function returns a **CommandCompletion** object that contains a list of +possible completions for the current input. This input script can be a string or an abstract syntax +tree (AST) that represents the script. + +You can override the default behavior of `TabExpansion2` by defining a custom function with the same +name in your PowerShell session. This custom function can provide completions for custom commands or +parameters. While it is possible to override `TabExpansion2`, it's not supported. You should create +a custom function only if you have a specific need to customize the tab completion behavior. + +## EXAMPLES + +### Example 1 - Get tab completion for command parameter + +This example shows the same results you would get by entering `Format-Hex -` at the PowerShell +command prompt. The `TabExpansion2` function returns a **CommandCompletion** object that contains a +list of possible completions for the `-` token. + +```powershell +TabExpansion2 -inputScript ($s = 'Format-Hex -') -cursorColumn $s.Length | + Select-Object -ExpandProperty CompletionMatches +``` + +```Output +CompletionText ListItemText ResultType ToolTip +-------------- ------------ ---------- ------- +-Path Path ParameterName [string[]] Path +-LiteralPath LiteralPath ParameterName [string[]] LiteralPath +-InputObject InputObject ParameterName [Object] InputObject +-Encoding Encoding ParameterName [string] Encoding +-Raw Raw ParameterName [switch] Raw +-Verbose Verbose ParameterName [switch] Verbose +-Debug Debug ParameterName [switch] Debug +-ErrorAction ErrorAction ParameterName [ActionPreference] ErrorAction +-WarningAction WarningAction ParameterName [ActionPreference] WarningAction +-InformationAction InformationAction ParameterName [ActionPreference] InformationAction +-ErrorVariable ErrorVariable ParameterName [string] ErrorVariable +-WarningVariable WarningVariable ParameterName [string] WarningVariable +-InformationVariable InformationVariable ParameterName [string] InformationVariable +-OutVariable OutVariable ParameterName [string] OutVariable +-OutBuffer OutBuffer ParameterName [int] OutBuffer +-PipelineVariable PipelineVariable ParameterName [string] PipelineVariable +``` + +### Example 2 - Get tab completion for parameter values + +This example shows how to get tab completion for parameter values. In this example, we expect that +**Stage** parameter has three possible values and that one of the values is `Three`. You can use +this technique to test that tab completion for your function returns the expected results. + +```powershell +function GetData { + param ( + [ValidateSet('One', 'Two', 'Three')] + [string]$Stage + ) + Write-Verbose "Retrieving data for stage $Stage" +} + +$result = TabExpansion2 -inputScript ($line = 'GetData -Stage ') -cursorColumn $line.Length | + Select-Object -ExpandProperty CompletionMatches +$result.Count -eq 3 +$result.CompletionText -contains 'Three' +``` + +```Output +True +True +``` + +## PARAMETERS + +### -ast + +An abstract syntax tree (AST) object that represents the script that you want to expand using tab +completion. + +```yaml +Type: System.Management.Automation.Language.Ast +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -cursorColumn + +The column number of the cursor in the input script string. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Int32 +Parameter Sets: ScriptInputSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -inputScript + +A string that represents the script that you want to expand using tab completion. + +```yaml +Type: System.String +Parameter Sets: ScriptInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -options + +A hashtable of option values to pass to the `CompleteInput()` API. The API accepts the following +boolean options: + +- `IgnoreHiddenShares` - When set to `$true`, ignore hidden UNC shares such as `\\COMPUTER\ADMIN$` + and `\\COMPUTER\C$`. By default, PowerShell includes hidden shares. +- `RelativePaths` - By default, PowerShell decides how to expand paths based on the input you + provided. Setting this value to `$true` forces PowerShell to replace paths with relative paths. + Setting this value to `$false`, forces PowerShell to replace them with absolute paths. +- `LiteralPaths` - By default, PowerShell replace special file characters, such as square brackets + and back-ticks, with their escaped equivalents. Setting this value to `$true` prevents the + replacement. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -positionOfCursor + +The column number of the cursor in the input AST. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.IScriptPosition +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -tokens + +An array of tokens parsed from the input script. The tokens are used to determine the token that +gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.Token[] +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 1 +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, +-ProgressAction -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Management.Automation.CommandCompletion + +## NOTES + +## RELATED LINKS + +[about_Built-in_Functions](./about/about_Built-in_Functions.md) + +[about_Tab_Expansion](./about/about_Tab_Expansion.md) + +[CompleteInput() method](xref:System.Management.Automation.CommandCompletion.CompleteInput*) diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md index 4bd9ddb4ba5..9d8e581669b 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md @@ -1,7 +1,7 @@ --- description: Describes the built-in functions in PowerShell. Locale: en-US -ms.date: 01/03/2023 +ms.date: 06/13/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_built-in_functions?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Built-in Functions @@ -35,14 +35,15 @@ between the command and the destination path. This function runs ## `Pause` -This function replicates the behavior of CMD's `pause` command. The script -pauses execution and prompts the user to hit a key to continue. +This function replicates the behavior of the `pause` command from `cmd.exe`. +The script pauses execution and prompts the user to hit a key to continue. ## `help` This function invokes `Get-Help` with your parameters and passes the output to the systems pager command. On Windows systems, the pager is `more.com`. On -non-Windows systems the pager could be `more` or `less`. +non-Windows systems, `help` uses the pager defined by the `$env:PAGER` +environment variable. ## `prompt` @@ -57,12 +58,14 @@ This function clears the screen. For more information, see ## `TabExpansion2` -This is the default function to use for tab expansion. +This is the default function to use for tab expansion. For more information, see +[TabExpansion2](xref:Microsoft.PowerShell.Core.TabExpansion2). ## `oss` This function provides a short hand way to run `Out-String -Stream` in a -pipeline. +pipeline. For more information, see +[Out-String](xref:Microsoft.PowerShell.Utility.Out-String). ## `mkdir` @@ -79,4 +82,4 @@ drive letter on the command line. PowerShell create a function for every possible drive letter, `A:` through `Z:`. -These functions aren't defined for non-Windows systems. +These drive letter functions aren't defined on non-Windows systems. diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index c6c2c02bc85..82ad6375cce 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Tab Expansion feature in PowerShell. Locale: en-US -ms.date: 12/05/2023 +ms.date: 06/13/2024 no-loc: [Tab, Ctrl, Space] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_tab_expansion?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -203,6 +203,7 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS ## See also +- [TabExpansion2][06] - [about_Comment_Based_Help][03] - [about_Functions_Argument_Completion][04] - [about_Requires][05] @@ -213,3 +214,4 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS [03]: about_Comment_Based_Help.md [04]: about_Functions_Argument_Completion.md [05]: about_Requires.md +[06]: xref:Microsoft.PowerShell.Core.TabExpansion2 diff --git a/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md new file mode 100644 index 00000000000..52d0e09e1d9 --- /dev/null +++ b/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md @@ -0,0 +1,233 @@ +--- +external help file: System.Management.Automation.dll-Help.xml +Module Name: Microsoft.PowerShell.Core +ms.date: 06/13/2024 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2?view=powershell-7.2&WT.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# TabExpansion2 + +## SYNOPSIS +A helper function that wraps the `CompleteInput()` method of the **CommandCompletion** class to +provide tab completion for PowerShell scripts. + +## SYNTAX + +### ScriptInputSet (Default) + +``` +TabExpansion2 [-inputScript] [[-cursorColumn] ] [[-options] ] + [] +``` + +### AstInputSet + +``` +TabExpansion2 [-ast] [-tokens] [-positionOfCursor] + [[-options] ] [] +``` + +## DESCRIPTION + +`TabExpansion2` is a built-in function that provides tab completion for user input. PowerShell calls +this function when the user presses the Tab or Ctrl+Space key while +typing a command. The function returns a list of possible completions for the current input. + +`TabExpansion2` isn't normally called directly by users. However, it can be useful for testing tab +completion. To use `TabExpansion2`, you need to provide the current input script and the cursor +position in the script. The function returns a **CommandCompletion** object that contains a list of +possible completions for the current input. This input script can be a string or an abstract syntax +tree (AST) that represents the script. + +You can override the default behavior of `TabExpansion2` by defining a custom function with the same +name in your PowerShell session. This custom function can provide completions for custom commands or +parameters. While it is possible to override `TabExpansion2`, it's not supported. You should create +a custom function only if you have a specific need to customize the tab completion behavior. + +## EXAMPLES + +### Example 1 - Get tab completion for command parameter + +This example shows the same results you would get by entering `Format-Hex -` at the PowerShell +command prompt. The `TabExpansion2` function returns a **CommandCompletion** object that contains a +list of possible completions for the `-` token. + +```powershell +TabExpansion2 -inputScript ($s = 'Format-Hex -') -cursorColumn $s.Length | + Select-Object -ExpandProperty CompletionMatches +``` + +```Output +CompletionText ListItemText ResultType ToolTip +-------------- ------------ ---------- ------- +-Path Path ParameterName [string[]] Path +-LiteralPath LiteralPath ParameterName [string[]] LiteralPath +-InputObject InputObject ParameterName [psobject] InputObject +-Encoding Encoding ParameterName [Encoding] Encoding +-Count Count ParameterName [long] Count +-Offset Offset ParameterName [long] Offset +``` + +### Example 2 - Get tab completion for parameter values + +This example shows how to get tab completion for parameter values. In this example, we expect that +**Stage** parameter has three possible values and that one of the values is `Three`. You can use +this technique to test that tab completion for your function returns the expected results. + +```powershell +function GetData { + param ( + [ValidateSet('One', 'Two', 'Three')] + [string]$Stage + ) + Write-Verbose "Retrieving data for stage $Stage" +} + +$result = TabExpansion2 -inputScript ($line = 'GetData -Stage ') -cursorColumn $line.Length | + Select-Object -ExpandProperty CompletionMatches +$result.Count -eq 3 +$result.CompletionText -contains 'Three' +``` + +```Output +True +True +``` + +## PARAMETERS + +### -ast + +An abstract syntax tree (AST) object that represents the script that you want to expand using tab +completion. + +```yaml +Type: System.Management.Automation.Language.Ast +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -cursorColumn + +The column number of the cursor in the input script string. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Int32 +Parameter Sets: ScriptInputSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -inputScript + +A string that represents the script that you want to expand using tab completion. + +```yaml +Type: System.String +Parameter Sets: ScriptInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -options + +A hashtable of option values to pass to the `CompleteInput()` API. The API accepts the following +boolean options: + +- `IgnoreHiddenShares` - When set to `$true`, ignore hidden UNC shares such as `\\COMPUTER\ADMIN$` + and `\\COMPUTER\C$`. By default, PowerShell includes hidden shares. +- `RelativePaths` - By default, PowerShell decides how to expand paths based on the input you + provided. Setting this value to `$true` forces PowerShell to replace paths with relative paths. + Setting this value to `$false`, forces PowerShell to replace them with absolute paths. +- `LiteralPaths` - By default, PowerShell replace special file characters, such as square brackets + and back-ticks, with their escaped equivalents. Setting this value to `$true` prevents the + replacement. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -positionOfCursor + +The column number of the cursor in the input AST. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.IScriptPosition +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -tokens + +An array of tokens parsed from the input script. The tokens are used to determine the token that +gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.Token[] +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 1 +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, +-ProgressAction -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Management.Automation.CommandCompletion + +## NOTES + +## RELATED LINKS + +[about_Built-in_Functions](./about/about_Built-in_Functions.md) + +[about_Tab_Expansion](./about/about_Tab_Expansion.md) + +[CompleteInput() method](xref:System.Management.Automation.CommandCompletion.CompleteInput*) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md index f744a96206f..8d403c4ffb6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md @@ -1,7 +1,7 @@ --- description: Describes the built-in functions in PowerShell. Locale: en-US -ms.date: 01/03/2023 +ms.date: 06/13/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_built-in_functions?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Built-in Functions @@ -43,14 +43,15 @@ This function was added in PowerShell 7.4. ## `Pause` -This function replicates the behavior of CMD's `pause` command. The script -pauses execution and prompts the user to hit a key to continue. +This function replicates the behavior of the `pause` command from `cmd.exe`. +The script pauses execution and prompts the user to hit a key to continue. ## `help` This function invokes `Get-Help` with your parameters and passes the output to the systems pager command. On Windows systems, the pager is `more.com`. On -non-Windows systems the pager could be `more` or `less`. +non-Windows systems, `help` uses the pager defined by the `$env:PAGER` +environment variable. ## `prompt` @@ -65,12 +66,14 @@ This function clears the screen. For more information, see ## `TabExpansion2` -This is the default function to use for tab expansion. +This is the default function to use for tab expansion. For more information, see +[TabExpansion2](xref:Microsoft.PowerShell.Core.TabExpansion2). ## `oss` This function provides a short hand way to run `Out-String -Stream` in a -pipeline. +pipeline. For more information, see +[Out-String](xref:Microsoft.PowerShell.Utility.Out-String). ## `mkdir` @@ -87,4 +90,4 @@ drive letter on the command line. PowerShell create a function for every possible drive letter, `A:` through `Z:`. -These functions aren't defined for non-Windows systems. +These drive letter functions aren't defined on non-Windows systems. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 006c899cf9f..cd138410299 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Tab Expansion feature in PowerShell. Locale: en-US -ms.date: 12/05/2023 +ms.date: 06/13/2024 no-loc: [Tab, Ctrl, Space] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_tab_expansion?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -203,6 +203,7 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS ## See also +- [TabExpansion2][06] - [about_Comment_Based_Help][03] - [about_Functions_Argument_Completion][04] - [about_Requires][05] @@ -213,3 +214,4 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS [03]: about_Comment_Based_Help.md [04]: about_Functions_Argument_Completion.md [05]: about_Requires.md +[06]: xref:Microsoft.PowerShell.Core.TabExpansion2 diff --git a/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md new file mode 100644 index 00000000000..4fc9da7401b --- /dev/null +++ b/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md @@ -0,0 +1,233 @@ +--- +external help file: System.Management.Automation.dll-Help.xml +Module Name: Microsoft.PowerShell.Core +ms.date: 06/13/2024 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2?view=powershell-7.4&WT.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# TabExpansion2 + +## SYNOPSIS +A helper function that wraps the `CompleteInput()` method of the **CommandCompletion** class to +provide tab completion for PowerShell scripts. + +## SYNTAX + +### ScriptInputSet (Default) + +``` +TabExpansion2 [-inputScript] [[-cursorColumn] ] [[-options] ] + [] +``` + +### AstInputSet + +``` +TabExpansion2 [-ast] [-tokens] [-positionOfCursor] + [[-options] ] [] +``` + +## DESCRIPTION + +`TabExpansion2` is a built-in function that provides tab completion for user input. PowerShell calls +this function when the user presses the Tab or Ctrl+Space key while +typing a command. The function returns a list of possible completions for the current input. + +`TabExpansion2` isn't normally called directly by users. However, it can be useful for testing tab +completion. To use `TabExpansion2`, you need to provide the current input script and the cursor +position in the script. The function returns a **CommandCompletion** object that contains a list of +possible completions for the current input. This input script can be a string or an abstract syntax +tree (AST) that represents the script. + +You can override the default behavior of `TabExpansion2` by defining a custom function with the same +name in your PowerShell session. This custom function can provide completions for custom commands or +parameters. While it is possible to override `TabExpansion2`, it's not supported. You should create +a custom function only if you have a specific need to customize the tab completion behavior. + +## EXAMPLES + +### Example 1 - Get tab completion for command parameter + +This example shows the same results you would get by entering `Format-Hex -` at the PowerShell +command prompt. The `TabExpansion2` function returns a **CommandCompletion** object that contains a +list of possible completions for the `-` token. + +```powershell +TabExpansion2 -inputScript ($s = 'Format-Hex -') -cursorColumn $s.Length | + Select-Object -ExpandProperty CompletionMatches +``` + +```Output +CompletionText ListItemText ResultType ToolTip +-------------- ------------ ---------- ------- +-Path Path ParameterName [string[]] Path +-LiteralPath LiteralPath ParameterName [string[]] LiteralPath +-InputObject InputObject ParameterName [psobject] InputObject +-Encoding Encoding ParameterName [Encoding] Encoding +-Count Count ParameterName [long] Count +-Offset Offset ParameterName [long] Offset +``` + +### Example 2 - Get tab completion for parameter values + +This example shows how to get tab completion for parameter values. In this example, we expect that +**Stage** parameter has three possible values and that one of the values is `Three`. You can use +this technique to test that tab completion for your function returns the expected results. + +```powershell +function GetData { + param ( + [ValidateSet('One', 'Two', 'Three')] + [string]$Stage + ) + Write-Verbose "Retrieving data for stage $Stage" +} + +$result = TabExpansion2 -inputScript ($line = 'GetData -Stage ') -cursorColumn $line.Length | + Select-Object -ExpandProperty CompletionMatches +$result.Count -eq 3 +$result.CompletionText -contains 'Three' +``` + +```Output +True +True +``` + +## PARAMETERS + +### -ast + +An abstract syntax tree (AST) object that represents the script that you want to expand using tab +completion. + +```yaml +Type: System.Management.Automation.Language.Ast +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -cursorColumn + +The column number of the cursor in the input script string. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Int32 +Parameter Sets: ScriptInputSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -inputScript + +A string that represents the script that you want to expand using tab completion. + +```yaml +Type: System.String +Parameter Sets: ScriptInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -options + +A hashtable of option values to pass to the `CompleteInput()` API. The API accepts the following +boolean options: + +- `IgnoreHiddenShares` - When set to `$true`, ignore hidden UNC shares such as `\\COMPUTER\ADMIN$` + and `\\COMPUTER\C$`. By default, PowerShell includes hidden shares. +- `RelativePaths` - By default, PowerShell decides how to expand paths based on the input you + provided. Setting this value to `$true` forces PowerShell to replace paths with relative paths. + Setting this value to `$false`, forces PowerShell to replace them with absolute paths. +- `LiteralPaths` - By default, PowerShell replace special file characters, such as square brackets + and back-ticks, with their escaped equivalents. Setting this value to `$true` prevents the + replacement. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -positionOfCursor + +The column number of the cursor in the input AST. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.IScriptPosition +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -tokens + +An array of tokens parsed from the input script. The tokens are used to determine the token that +gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.Token[] +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 1 +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, +-ProgressAction -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Management.Automation.CommandCompletion + +## NOTES + +## RELATED LINKS + +[about_Built-in_Functions](./about/about_Built-in_Functions.md) + +[about_Tab_Expansion](./about/about_Tab_Expansion.md) + +[CompleteInput() method](xref:System.Management.Automation.CommandCompletion.CompleteInput*) diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md index 9220b6805af..b1cc3afdd73 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Built-in_Functions.md @@ -1,7 +1,7 @@ --- description: Describes the built-in functions in PowerShell. Locale: en-US -ms.date: 01/03/2023 +ms.date: 06/13/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_built-in_functions?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Built-in Functions @@ -43,14 +43,15 @@ This function was added in PowerShell 7.4. ## `Pause` -This function replicates the behavior of CMD's `pause` command. The script -pauses execution and prompts the user to hit a key to continue. +This function replicates the behavior of the `pause` command from `cmd.exe`. +The script pauses execution and prompts the user to hit a key to continue. ## `help` This function invokes `Get-Help` with your parameters and passes the output to the systems pager command. On Windows systems, the pager is `more.com`. On -non-Windows systems the pager could be `more` or `less`. +non-Windows systems, `help` uses the pager defined by the `$env:PAGER` +environment variable. ## `prompt` @@ -65,12 +66,14 @@ This function clears the screen. For more information, see ## `TabExpansion2` -This is the default function to use for tab expansion. +This is the default function to use for tab expansion. For more information, see +[TabExpansion2](xref:Microsoft.PowerShell.Core.TabExpansion2). ## `oss` This function provides a short hand way to run `Out-String -Stream` in a -pipeline. +pipeline. For more information, see +[Out-String](xref:Microsoft.PowerShell.Utility.Out-String). ## `mkdir` @@ -87,4 +90,4 @@ drive letter on the command line. PowerShell create a function for every possible drive letter, `A:` through `Z:`. -These functions aren't defined for non-Windows systems. +These drive letter functions aren't defined on non-Windows systems. diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 2d40b8aa420..8ba8c7fcd45 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Tab Expansion feature in PowerShell. Locale: en-US -ms.date: 05/16/2024 +ms.date: 06/13/2024 no-loc: [Tab, Ctrl, Space] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_tab_expansion?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -36,7 +36,7 @@ information, see [about_PSReadLine][02]. > contain tabs. If it does, the results will be unpredictable and will almost > certainly not be what you intended. -## File and path name completion +## File and cmdlet name completion To fill in a filename or path from the available choices automatically, type part of the name and press the Tab key. PowerShell automatically @@ -212,6 +212,7 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS ## See also +- [TabExpansion2][06] - [about_Comment_Based_Help][03] - [about_Functions_Argument_Completion][04] - [about_Requires][05] @@ -222,3 +223,4 @@ EXAMPLE FORWARDHELPTARGETNAME LINK PARAMETER SYNOPSIS [03]: about_Comment_Based_Help.md [04]: about_Functions_Argument_Completion.md [05]: about_Requires.md +[06]: xref:Microsoft.PowerShell.Core.TabExpansion2 diff --git a/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md new file mode 100644 index 00000000000..d1019859a83 --- /dev/null +++ b/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md @@ -0,0 +1,233 @@ +--- +external help file: System.Management.Automation.dll-Help.xml +Module Name: Microsoft.PowerShell.Core +ms.date: 06/13/2024 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2?view=powershell-7.5&WT.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# TabExpansion2 + +## SYNOPSIS +A helper function that wraps the `CompleteInput()` method of the **CommandCompletion** class to +provide tab completion for PowerShell scripts. + +## SYNTAX + +### ScriptInputSet (Default) + +``` +TabExpansion2 [-inputScript] [[-cursorColumn] ] [[-options] ] + [] +``` + +### AstInputSet + +``` +TabExpansion2 [-ast] [-tokens] [-positionOfCursor] + [[-options] ] [] +``` + +## DESCRIPTION + +`TabExpansion2` is a built-in function that provides tab completion for user input. PowerShell calls +this function when the user presses the Tab or Ctrl+Space key while +typing a command. The function returns a list of possible completions for the current input. + +`TabExpansion2` isn't normally called directly by users. However, it can be useful for testing tab +completion. To use `TabExpansion2`, you need to provide the current input script and the cursor +position in the script. The function returns a **CommandCompletion** object that contains a list of +possible completions for the current input. This input script can be a string or an abstract syntax +tree (AST) that represents the script. + +You can override the default behavior of `TabExpansion2` by defining a custom function with the same +name in your PowerShell session. This custom function can provide completions for custom commands or +parameters. While it is possible to override `TabExpansion2`, it's not supported. You should create +a custom function only if you have a specific need to customize the tab completion behavior. + +## EXAMPLES + +### Example 1 - Get tab completion for command parameter + +This example shows the same results you would get by entering `Format-Hex -` at the PowerShell +command prompt. The `TabExpansion2` function returns a **CommandCompletion** object that contains a +list of possible completions for the `-` token. + +```powershell +TabExpansion2 -inputScript ($s = 'Format-Hex -') -cursorColumn $s.Length | + Select-Object -ExpandProperty CompletionMatches +``` + +```Output +CompletionText ListItemText ResultType ToolTip +-------------- ------------ ---------- ------- +-Path Path ParameterName [string[]] Path +-LiteralPath LiteralPath ParameterName [string[]] LiteralPath +-InputObject InputObject ParameterName [psobject] InputObject +-Encoding Encoding ParameterName [Encoding] Encoding +-Count Count ParameterName [long] Count +-Offset Offset ParameterName [long] Offset +``` + +### Example 2 - Get tab completion for parameter values + +This example shows how to get tab completion for parameter values. In this example, we expect that +**Stage** parameter has three possible values and that one of the values is `Three`. You can use +this technique to test that tab completion for your function returns the expected results. + +```powershell +function GetData { + param ( + [ValidateSet('One', 'Two', 'Three')] + [string]$Stage + ) + Write-Verbose "Retrieving data for stage $Stage" +} + +$result = TabExpansion2 -inputScript ($line = 'GetData -Stage ') -cursorColumn $line.Length | + Select-Object -ExpandProperty CompletionMatches +$result.Count -eq 3 +$result.CompletionText -contains 'Three' +``` + +```Output +True +True +``` + +## PARAMETERS + +### -ast + +An abstract syntax tree (AST) object that represents the script that you want to expand using tab +completion. + +```yaml +Type: System.Management.Automation.Language.Ast +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -cursorColumn + +The column number of the cursor in the input script string. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Int32 +Parameter Sets: ScriptInputSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -inputScript + +A string that represents the script that you want to expand using tab completion. + +```yaml +Type: System.String +Parameter Sets: ScriptInputSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -options + +A hashtable of option values to pass to the `CompleteInput()` API. The API accepts the following +boolean options: + +- `IgnoreHiddenShares` - When set to `$true`, ignore hidden UNC shares such as `\\COMPUTER\ADMIN$` + and `\\COMPUTER\C$`. By default, PowerShell includes hidden shares. +- `RelativePaths` - By default, PowerShell decides how to expand paths based on the input you + provided. Setting this value to `$true` forces PowerShell to replace paths with relative paths. + Setting this value to `$false`, forces PowerShell to replace them with absolute paths. +- `LiteralPaths` - By default, PowerShell replace special file characters, such as square brackets + and back-ticks, with their escaped equivalents. Setting this value to `$true` prevents the + replacement. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -positionOfCursor + +The column number of the cursor in the input AST. The cursor position is used to determine +the token that gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.IScriptPosition +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -tokens + +An array of tokens parsed from the input script. The tokens are used to determine the token that +gets expanded by tab completion. + +```yaml +Type: System.Management.Automation.Language.Token[] +Parameter Sets: AstInputSet +Aliases: + +Required: True +Position: 1 +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, +-ProgressAction -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Management.Automation.CommandCompletion + +## NOTES + +## RELATED LINKS + +[about_Built-in_Functions](./about/about_Built-in_Functions.md) + +[about_Tab_Expansion](./about/about_Tab_Expansion.md) + +[CompleteInput() method](xref:System.Management.Automation.CommandCompletion.CompleteInput*) From d5c11fe31a5032e79108d57af3ceaa2ac6c7d408 Mon Sep 17 00:00:00 2001 From: Danni X Date: Fri, 14 Jun 2024 01:07:51 +0800 Subject: [PATCH 2/2] fix HTML rendering content issue in code block (#11185) --- .../5.1/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md | 4 ++-- .../7.2/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md | 4 ++-- .../7.4/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md | 4 ++-- .../7.5/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md b/reference/5.1/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md index 374a0ec728a..86d643d9fad 100644 --- a/reference/5.1/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md +++ b/reference/5.1/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md @@ -556,14 +556,14 @@ $xmlQuery = @' + TimeCreated[timediff(@SystemTime) &lt;= 86400000]]] '@ Get-WinEvent -FilterXML $xmlQuery # Using the FilterXPath parameter: -$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) <= 86400000]]]' +$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]' Get-WinEvent -LogName 'Windows PowerShell' -FilterXPath $XPath ``` diff --git a/reference/7.2/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md b/reference/7.2/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md index a5c6f5e96dc..1d117ca4dc2 100644 --- a/reference/7.2/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md +++ b/reference/7.2/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md @@ -558,14 +558,14 @@ $xmlQuery = @' + TimeCreated[timediff(@SystemTime) &lt;= 86400000]]] '@ Get-WinEvent -FilterXML $xmlQuery # Using the FilterXPath parameter: -$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) <= 86400000]]]' +$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]' Get-WinEvent -LogName 'Windows PowerShell' -FilterXPath $XPath ``` diff --git a/reference/7.4/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md b/reference/7.4/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md index 99ad304dfbd..ec840ecf8c8 100644 --- a/reference/7.4/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md +++ b/reference/7.4/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md @@ -558,14 +558,14 @@ $xmlQuery = @' + TimeCreated[timediff(@SystemTime) &lt;= 86400000]]] '@ Get-WinEvent -FilterXML $xmlQuery # Using the FilterXPath parameter: -$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) <= 86400000]]]' +$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]' Get-WinEvent -LogName 'Windows PowerShell' -FilterXPath $XPath ``` diff --git a/reference/7.5/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md b/reference/7.5/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md index 043c1682b4d..78b99e810e9 100644 --- a/reference/7.5/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md +++ b/reference/7.5/Microsoft.PowerShell.Diagnostics/Get-WinEvent.md @@ -558,14 +558,14 @@ $xmlQuery = @' + TimeCreated[timediff(@SystemTime) &lt;= 86400000]]] '@ Get-WinEvent -FilterXML $xmlQuery # Using the FilterXPath parameter: -$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) <= 86400000]]]' +$XPath = '*[System[Level=3 and TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]' Get-WinEvent -LogName 'Windows PowerShell' -FilterXPath $XPath ```