From 9b3b1dafe834feaea309518e84c4bd58c17819e9 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 13 Jun 2024 09:56:59 -0500 Subject: [PATCH 1/2] Add ref content for TabExpansion2 --- .../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..03fcb73fabc --- /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 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..7d7b6dc7b96 --- /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 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..816bab4b2ef --- /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 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..8a33950c521 --- /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 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 4c49fe7e6ad261227884eb0aefc1aaf9088cc519 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Thu, 13 Jun 2024 10:03:22 -0500 Subject: [PATCH 2/2] Apply suggestions from review --- reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md | 2 +- reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md | 2 +- reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md | 2 +- reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md index 03fcb73fabc..191548478e0 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md +++ b/reference/5.1/Microsoft.PowerShell.Core/TabExpansion2.md @@ -31,7 +31,7 @@ TabExpansion2 [-ast] [-tokens] [-positionOfCursor] Tab or Ctrl+Space key while +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 diff --git a/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md index 7d7b6dc7b96..52d0e09e1d9 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md +++ b/reference/7.2/Microsoft.PowerShell.Core/TabExpansion2.md @@ -31,7 +31,7 @@ TabExpansion2 [-ast] [-tokens] [-positionOfCursor] Tab or Ctrl+Space key while +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 diff --git a/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md index 816bab4b2ef..4fc9da7401b 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md +++ b/reference/7.4/Microsoft.PowerShell.Core/TabExpansion2.md @@ -31,7 +31,7 @@ TabExpansion2 [-ast] [-tokens] [-positionOfCursor] Tab or Ctrl+Space key while +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 diff --git a/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md b/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md index 8a33950c521..d1019859a83 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md +++ b/reference/7.5/Microsoft.PowerShell.Core/TabExpansion2.md @@ -31,7 +31,7 @@ TabExpansion2 [-ast] [-tokens] [-positionOfCursor] Tab or Ctrl+Space key while +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