From 25d138018e5cb02187f9daa670ecd6006298b8d4 Mon Sep 17 00:00:00 2001 From: "Patrick M. Meinecke" Date: Sat, 10 Jun 2017 13:05:19 -0400 Subject: [PATCH] Update help docs for Commands submodule This change fixes some mistakes in the help documents for the Commands module and adds additional examples. --- module/docs/ConvertFrom-ScriptExtent.md | 19 ++++-- module/docs/ConvertTo-ScriptExtent.md | 46 +++++++------ module/docs/Find-Ast.md | 67 +++++++++++++++---- module/docs/Import-EditorCommand.md | 29 ++++++-- module/docs/Join-ScriptExtent.md | 13 ++-- .../docs/PowerShellEditorServices.Commands.md | 10 ++- module/docs/Register-EditorCommand.md | 2 +- module/docs/Set-ScriptExtent.md | 13 ++-- module/docs/Test-ScriptExtent.md | 7 +- module/docs/Unregister-EditorCommand.md | 2 +- 10 files changed, 143 insertions(+), 65 deletions(-) diff --git a/module/docs/ConvertFrom-ScriptExtent.md b/module/docs/ConvertFrom-ScriptExtent.md index 69c84462a..741fe010e 100644 --- a/module/docs/ConvertFrom-ScriptExtent.md +++ b/module/docs/ConvertFrom-ScriptExtent.md @@ -26,18 +26,20 @@ ConvertFrom-ScriptExtent -Extent [-BufferPosition] [-Start] [- ## DESCRIPTION -Translates IScriptExtent object properties into constructors for some common PowerShell EditorServices types. +The ConvertFrom-ScriptExtent function converts ScriptExtent objects to types used in methods found in the $psEditor API. ## EXAMPLES ### -------------------------- EXAMPLE 1 -------------------------- ```powershell -$sb = { Get-ChildItem 'Documents' } -$sb.Ast | Find-Ast { $_ -eq 'Documents' } | ConvertFrom-ScriptExtent -BufferRange +$range = Find-Ast -First { [System.Management.Automation.Language.CommandAst] } | + ConvertFrom-ScriptExtent -BufferRange + +$psEditor.GetEditorContext().SetSelection($range) ``` -Gets the buffer range of the string expression "Documents". +Convert the extent of the first CommandAst to a BufferRange and use that to select it with the $psEditor API. ## PARAMETERS @@ -129,7 +131,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Management.Automation.Language.IScriptExtent -You can pipe IScriptExtent objects to be converted. +You can pass ScriptExtent objects to this function. You can also pass objects with a property named "Extent" such as ASTs from Find-Ast or tokens from Get-Token. ## OUTPUTS @@ -137,10 +139,13 @@ You can pipe IScriptExtent objects to be converted. ### Microsoft.PowerShell.EditorServices.BufferPosition -This function will return an extent converted to one of the above types depending on switch -choices. +This function will return the converted object of one of the above types depending on parameter switch choices. ## NOTES ## RELATED LINKS +[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) +[Test-ScriptExtent](Test-ScriptExtent.md) +[Set-ScriptExtent](Set-ScriptExtent.md) +[Join-ScriptExtent](Join-ScriptExtent.md) diff --git a/module/docs/ConvertTo-ScriptExtent.md b/module/docs/ConvertTo-ScriptExtent.md index ed0a3e95b..f01db70e8 100644 --- a/module/docs/ConvertTo-ScriptExtent.md +++ b/module/docs/ConvertTo-ScriptExtent.md @@ -12,10 +12,10 @@ Converts position and range objects from PowerShellEditorServices to ScriptExten ## SYNTAX -### ByObject +### ByExtent ```powershell -ConvertTo-ScriptExtent [-InputObject ] [] +ConvertTo-ScriptExtent [-Extent ] [] ``` ### ByPosition @@ -41,7 +41,7 @@ ConvertTo-ScriptExtent [-FilePath ] [-StartBuffer ] [-En ## DESCRIPTION -Converts position and range objects from PowerShellEditorServices to ScriptExtent objects. +The ConvertTo-ScriptExtent function can be used to convert any object with position related properties to a ScriptExtent object. You can also specify the parameters directly to manually create ScriptExtent objects. ## EXAMPLES @@ -51,17 +51,25 @@ Converts position and range objects from PowerShellEditorServices to ScriptExten $psEditor.GetEditorContext().SelectedRange | ConvertTo-ScriptExtent ``` -Returns a InternalScriptExtent object of the currently selected range. +Returns a ScriptExtent object of the currently selected range. + +### -------------------------- EXAMPLE 2 -------------------------- + +```powershell +ConvertTo-ScriptExtent -StartOffset 10 -EndOffset 100 +``` + +Returns a ScriptExtent object from a start and end offset. ## PARAMETERS -### -InputObject +### -Extent -This is here so we can pass script extent objects through without any processing. +Specifies a ScriptExtent object to use as a base to create a new editor context aware ScriptExtent object. ```yaml Type: IScriptExtent -Parameter Sets: ByObject +Parameter Sets: ByExtent Aliases: Required: False @@ -223,29 +231,23 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Object -You can pass any object with any of the following properties. +You can pass any object with properties that have position related names. Below is a list of all the property names that can be bound as parameters through the pipeline. -StartLineNumber, StartLine, Line -EndLineNumber, EndLine -StartColumnNumber, StartColumn, Column -EndColumnNumber, EndColumn -StartOffsetNumber, StartOffset, Offset -EndOffsetNumber, EndOffset -StartBuffer, Start -EndBuffer, End +StartLineNumber, StartLine, Line, EndLineNumber, EndLine, StartColumnNumber, StartColumn, Column, EndColumnNumber, EndColumn, StartOffsetNumber, StartOffset, Offset, EndOffsetNumber, EndOffset, StartBuffer, Start, EndBuffer, End -Objects of type IScriptExtent will be passed through with no processing. +You can also pass IScriptExtent objects to be converted to context aware versions. ## OUTPUTS -### System.Management.Automation.Language.IScriptExtent - -### System.Management.Automation.Language.InternalScriptExtent +### Microsoft.PowerShell.EditorServices.FullScriptExtent -This function will return any IScriptExtent object passed without processing. Objects created -by this function will be of type InternalScriptExtent. +The converted ScriptExtent object will be returned to the pipeline. ## NOTES ## RELATED LINKS +[ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md) +[Test-ScriptExtent](Test-ScriptExtent.md) +[Set-ScriptExtent](Set-ScriptExtent.md) +[Join-ScriptExtent](Join-ScriptExtent.md) diff --git a/module/docs/Find-Ast.md b/module/docs/Find-Ast.md index 9752e143e..65a2ac412 100644 --- a/module/docs/Find-Ast.md +++ b/module/docs/Find-Ast.md @@ -8,7 +8,7 @@ schema: 2.0.0 ## SYNOPSIS -Search for a ast within an ast. +Find a specific element in an abstract syntax tree (AST). ## SYNTAX @@ -27,7 +27,9 @@ Find-Ast [-AtCursor] [] ## DESCRIPTION -The Find-Ast function can be used to easily find a specific ast from a starting ast. By default children asts will be searched, but ancestor asts can also be searched by specifying the "Ancestor" switch parameter. +The Find-Ast function can be used to easily find a specific AST within a script file. All ASTs following the inital starting ast will be searched, including those that are not part of the same tree. + +The behavior of the search (such as direction and criteria) can be changed with parameters. Additionally, you can find the Ast closest to the cursor with the "AtCursor" switch parameter. @@ -76,16 +78,50 @@ Returns all variable expressions used in a dot source expression. ### -------------------------- EXAMPLE 6 -------------------------- ```powershell -Find-Ast { 'PowerShellVersion' -eq $_ } | Find-Ast -First | Set-ScriptExtent -Text "'4.0'" +Find-Ast { 'PowerShellVersion' -eq $_ } | + Find-Ast -First | + Set-ScriptExtent -Text '4.0' -AsString +``` + +This example sets the required PowerShell version in a module manifest to 4.0. + +First it finds the AST of the PowerShellVersion manifest field, then finds the first AST directly after it and changes the text to '4.0'. This will not work as is if the field is commented. + +### -------------------------- EXAMPLE 7 -------------------------- + +```powershell +Find-Ast { $_.ArgumentName -eq 'ParameterSetName' -and $_.Argument.Value -eq 'ByPosition' } | + Find-Ast -First -Ancestor { $_ -is [System.Management.Automation.Language.ParameterAst] } | + ForEach-Object { $_.Name.VariablePath.UserPath } +``` + +This example gets a list of all parameters that belong to the parameter set 'ByPosition'. First it uses the ArgumentName and Argument properties of NamedAttributeArgumentAst to find the ASTs of arguments to the Parameter attribute that declare the the parameter set 'ByPosition'. It then finds the closest parent ParameterAst and retrieves the name from it. + +### -------------------------- EXAMPLE 8 -------------------------- + +```powershell +$companyName = Find-Ast { + $_.Value -eq 'CompanyName' -or + (Find-Ast -Ast $_ -First -Before).Value -eq 'CompanyName' +} + +$previousField = $companyName[0] | Find-Ast -First -Before { $_.StringConstantType -eq 'BareWord' } + +$companyNameComments = $companyName.Extent, $previousField.Extent | + Join-ScriptExtent | + Get-Token | + Where-Object Kind -eq 'Comment' + +$fullManifestElement = $companyNameComments.Extent, $companyName.Extent | Join-ScriptExtent ``` -First finds the ast of the PowerShellVersion manifest tag, then finds the first ast after it and changes the text to '4.0'. This will not work as is if the field is commented. +This example shows off ways you can combine the position functions together to get very specific portions of a script file. The result of this example is a ScriptExtent that includes a manifest field, value, and all comments above it. ## PARAMETERS ### -FilterScript -Specifies a ScriptBlock that returns $true if an ast should be returned. Uses $PSItem and $_ like Where-Object. If not specified all asts will be returned. +Specifies a ScriptBlock that returns $true if an AST should be returned. Uses $PSItem and $_ like Where-Object. If not specified all ASTs will be returned. ```yaml Type: ScriptBlock @@ -101,7 +137,7 @@ Accept wildcard characters: False ### -Ast -Specifies the starting ast. The default is the ast of the current file in PowerShell Editor Services. +Specifies the starting AST. The default is the AST of the current file in PowerShell Editor Services. ```yaml Type: Ast @@ -133,7 +169,7 @@ Accept wildcard characters: False ### -Family -If specified only children of the starting ast will be searched. If specified with the "Before" parameter then only ancestors will be searched. +If specified only children of the starting AST will be searched. If specified with the "Before" parameter then only ancestors will be searched. ```yaml Type: SwitchParameter @@ -149,7 +185,7 @@ Accept wildcard characters: False ### -First -If specified will return only the first result. This will be the closest ast that matches. +If specified will return only the first result. This will be the closest AST that matches. ```yaml Type: SwitchParameter @@ -165,7 +201,7 @@ Accept wildcard characters: False ### -Last -If specified will return only the last result. This will be the furthest ast that matches. +If specified will return only the last result. This will be the furthest AST that matches. ```yaml Type: SwitchParameter @@ -181,7 +217,7 @@ Accept wildcard characters: False ### -Ancestor -If specified will only search ancestors of the starting ast. This is a convenience parameter that acts the same as the "Family" and "Before" parameters when used together. +If specified will only search ancestors of the starting AST. This is a convenience parameter that acts the same as the "Family" and "Before" parameters when used together. ```yaml Type: SwitchParameter @@ -197,7 +233,7 @@ Accept wildcard characters: False ### -IncludeStartingAst -If specified the starting ast will be included if matched. +If specified the starting AST will be included if matched. ```yaml Type: SwitchParameter @@ -213,7 +249,7 @@ Accept wildcard characters: False ### -AtCursor -If specified, this function will return the smallest ast that the cursor is within. Requires PowerShell Editor Services. +If specified, this function will return the smallest AST that the cursor is within. ```yaml Type: SwitchParameter @@ -235,15 +271,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Management.Automation.Language.Ast -You can pass asts to search to this function. +You can pass ASTs to search to this function. ## OUTPUTS ### System.Management.Automation.Language.Ast -Asts that match the criteria will be returned to the pipeline. +ASTs that match the criteria will be returned to the pipeline. ## NOTES ## RELATED LINKS +[Get-Token](Get-Token.md) +[Set-ScriptExtent](Set-ScriptExtent.md) +[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) diff --git a/module/docs/Import-EditorCommand.md b/module/docs/Import-EditorCommand.md index fef2cbea2..d84c66d53 100644 --- a/module/docs/Import-EditorCommand.md +++ b/module/docs/Import-EditorCommand.md @@ -8,20 +8,20 @@ schema: 2.0.0 ## SYNOPSIS -Imports commands with the PSEditorCommand attribute into PowerShell Editor Services. +Imports commands with the EditorCommand attribute into PowerShell Editor Services. ## SYNTAX ### ByModule ```powershell -Import-EditorCommand [-Module] [-Force] [-PassThru] [] +Import-EditorCommand [-Module] [-Force] [-PassThru] [] ``` ### ByCommand ```powershell -Import-EditorCommand [-Command] [-Force] [-PassThru] [] +Import-EditorCommand [-Command] [-Force] [-PassThru] [] ``` ## DESCRIPTION @@ -30,6 +30,8 @@ The Import-EditorCommand function will search the specified module for functions Alternatively, you can specify command info objects (like those from the Get-Command cmdlet) to be processed directly. +To tag a command as an editor command, attach the attribute 'Microsoft.PowerShell.EditorServices.Extensions.EditorCommandAttribute' to the function like you would with 'CmdletBindingAttribute'. The attribute accepts the named parameters 'Name', 'DisplayName', and 'SuppressOutput'. + ## EXAMPLES ### -------------------------- EXAMPLE 1 -------------------------- @@ -48,6 +50,23 @@ Get-Command *Editor* | Import-EditorCommand -PassThru Registers all editor commands that contain "Editor" in the name and return all successful imports. +### -------------------------- EXAMPLE 3 -------------------------- + +```powershell +function Invoke-MyEditorCommand { + [CmdletBinding()] + [Microsoft.PowerShell.EditorServices.Extensions.EditorCommand(DisplayName='My Command', SuppressOutput)] + param() + end { + ConvertTo-ScriptExtent -Offset 0 | Set-ScriptExtent -Text 'My Command!' + } +} + +Get-Command Invoke-MyEditorCommand | Import-EditorCommand +``` + +This example declares the function Invoke-MyEditorCommand with the EditorCommand attribute and then imports it as an editor command. + ## PARAMETERS ### -Module @@ -68,7 +87,7 @@ Accept wildcard characters: False ### -Command -Specifies the functions to register as editor commands. If the function does not have the PSEditorCommand attribute it will be ignored. +Specifies the functions to register as editor commands. If the function does not have the EditorCommand attribute it will be ignored. ```yaml Type: string[] @@ -135,3 +154,5 @@ will be returned. This function does not output to the pipeline otherwise. ## RELATED LINKS +[Register-EditorCommand](Register-EditorCommand.md) +[Unregister-EditorCommand](Unregister-EditorCommand.md) diff --git a/module/docs/Join-ScriptExtent.md b/module/docs/Join-ScriptExtent.md index 37fa97f8c..0c622bdb9 100644 --- a/module/docs/Join-ScriptExtent.md +++ b/module/docs/Join-ScriptExtent.md @@ -8,7 +8,7 @@ schema: 2.0.0 ## SYNOPSIS -Combine script extents. +Combine multiple ScriptExtent objects into a single ScriptExtent. ## SYNTAX @@ -18,7 +18,7 @@ Join-ScriptExtent [[-Extent] ] [] ## DESCRIPTION -The Join-ScriptExtent function will combine all ScriptExtent objects piped to it into a single extent. +The Join-ScriptExtent function will combine all ScriptExtent objects piped to it into a single extent. This can be used combine multiple ASTs, tokens, or other script elements into a single object that can then be manipulated or used for more targeted searches. ## EXAMPLES @@ -57,16 +57,19 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Management.Automation.Language.IScriptExtent -You can pass script extent objects to this function. You can also pass objects with a property -named "Extent". +You can pass ScriptExtent objects to this function. You can also pass objects with a property named "Extent" such as ASTs from Find-Ast or tokens from Get-Token. ## OUTPUTS ### System.Management.Automation.Language.IScriptExtent -The combined extent is returned. +The combined ScriptExtent object is returned. ## NOTES ## RELATED LINKS +[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) +[ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md) +[Test-ScriptExtent](Test-ScriptExtent.md) +[Set-ScriptExtent](Set-ScriptExtent.md) diff --git a/module/docs/PowerShellEditorServices.Commands.md b/module/docs/PowerShellEditorServices.Commands.md index 070844b42..f70a39bd7 100644 --- a/module/docs/PowerShellEditorServices.Commands.md +++ b/module/docs/PowerShellEditorServices.Commands.md @@ -16,17 +16,15 @@ Module to facilitate easy manipulation of script files and editor features. ### [ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md) -Translates IScriptExtent object properties into constructors for some common PowerShell EditorServices types. +The ConvertFrom-ScriptExtent function converts ScriptExtent objects to types used in methods found in the $psEditor API. ### [ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) -Converts position and range objects from PowerShellEditorServices to ScriptExtent objects. +The ConvertTo-ScriptExtent function can be used to convert any object with position related properties to a ScriptExtent object. You can also specify the parameters directly to manually create ScriptExtent objects. ### [Find-Ast](Find-Ast.md) -The Find-Ast function can be used to easily find a specific ast from a starting ast. By -default children asts will be searched, but ancestor asts can also be searched by specifying -the "Ancestor" switch parameter. +The Find-Ast function can be used to easily find a specific AST within a script file. All ASTs following the inital starting ast will be searched, including those that are not part of the same tree. ### [Get-Token](Get-Token.md) @@ -40,7 +38,7 @@ Alternatively, you can specify command info objects (like those from the Get-Com ### [Join-ScriptExtent](Join-ScriptExtent.md) -The Join-ScriptExtent function will combine all ScriptExtent objects piped to it into a single extent. +The Join-ScriptExtent function will combine all ScriptExtent objects piped to it into a single extent. This can be used combine multiple ASTs, tokens, or other script elements into a single object that can then be manipulated or used for more targeted searches. ### [Set-ScriptExtent](Set-ScriptExtent.md) diff --git a/module/docs/Register-EditorCommand.md b/module/docs/Register-EditorCommand.md index 6e8ab61a9..605576fd0 100644 --- a/module/docs/Register-EditorCommand.md +++ b/module/docs/Register-EditorCommand.md @@ -150,4 +150,4 @@ Accept wildcard characters: False ## RELATED LINKS [Unregister-EditorCommand](Unregister-EditorCommand.md) - +[Import-EditorCommand](Import-EditorCommand.md) diff --git a/module/docs/Set-ScriptExtent.md b/module/docs/Set-ScriptExtent.md index a65181e81..fb92efe12 100644 --- a/module/docs/Set-ScriptExtent.md +++ b/module/docs/Set-ScriptExtent.md @@ -15,19 +15,19 @@ Replaces text at a specified IScriptExtent object. ### __AllParameterSets (Default) ```powershell -Set-ScriptExtent [-Text] [-Extent ] [] +Set-ScriptExtent [-Text] [-Extent ] [] ``` ### AsString ```powershell -Set-ScriptExtent [-Text] [-AsString] [-Extent ] [] +Set-ScriptExtent [-Text] [-AsString] [-Extent ] [] ``` ### AsArray ```powershell -Set-ScriptExtent [-Text] [-AsArray] [-Extent ] [] +Set-ScriptExtent [-Text] [-AsArray] [-Extent ] [] ``` ## DESCRIPTION @@ -129,7 +129,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Management.Automation.Language.IScriptExtent -You can pass script extent objects to this function. You can also pass objects with a property named "Extent". +You can pass ScriptExtent objects to this function. You can also pass objects with a property named "Extent" such as ASTs from Find-Ast or tokens from Get-Token. ## OUTPUTS @@ -139,3 +139,8 @@ You can pass script extent objects to this function. You can also pass objects ## RELATED LINKS +[Find-Ast](Find-Ast.md) +[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) +[ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md) +[Test-ScriptExtent](Test-ScriptExtent.md) +[Join-ScriptExtent](Join-ScriptExtent.md) diff --git a/module/docs/Test-ScriptExtent.md b/module/docs/Test-ScriptExtent.md index 39177c7f8..bc0ac6841 100644 --- a/module/docs/Test-ScriptExtent.md +++ b/module/docs/Test-ScriptExtent.md @@ -125,7 +125,7 @@ Accept wildcard characters: False ### System.Management.Automation.Language.IScriptExtent -You can pass reference script extent objects to this function. +You can pass ScriptExtent objects to this function. You can also pass objects with a property named "Extent" such as ASTs from Find-Ast or tokens from Get-Token. ## OUTPUTS @@ -138,3 +138,8 @@ If the "PassThru" parameter is specified and the test passed, the reference scri ## NOTES ## RELATED LINKS + +[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md) +[ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md) +[Set-ScriptExtent](Set-ScriptExtent.md) +[Join-ScriptExtent](Join-ScriptExtent.md) diff --git a/module/docs/Unregister-EditorCommand.md b/module/docs/Unregister-EditorCommand.md index 0c9c23c95..61821d24e 100644 --- a/module/docs/Unregister-EditorCommand.md +++ b/module/docs/Unregister-EditorCommand.md @@ -56,4 +56,4 @@ Accept wildcard characters: False ## RELATED LINKS [Register-EditorCommand](Register-EditorCommand.md) - +[Import-EditorCommand](Import-EditorCommand.md)