Welcome to OStack Knowledge Sharing Community for programmer and developer-Open, Learning and Share
Welcome To Ask or Share your Answers For Others

Categories

0 votes
1.9k views
in Technique[技术] by (71.8m points)

powershell - Get-Help for .trim / -trim, .replace / -replace, .split / -split and other string operators

PowerShell has a pretty good built-in help system that I use a lot and I'm able to see all help options with Get-Help * and query Cmdlets or can look up Topics with Get-Help about_* and then say Get-Help about_compar* to open the Comparison Operators topic which is all very good.

However, I was trying to find how to get help on the various string operators, like .replace, .compare, .split, .substring. Does anyone know how to pull these topics up on the PowerShell console (possibly, they might be hidden inside some of the about_* topics, but it's not obvious or clear to me where to look)?

Also, the string operators have -replace, -compare, -split variants etc and while almost the same as the .replace etc, one version uses regular expressions and the other does not. Does anyone know if there are help topics (again, available from the console!) that clarifies all of this? The PowerShell help system will feel quite lacking if it is missing clarifications on all of this in its built-in help system as these are a very heavily used part of the language (so hopefully this is all tucked away in some about_* topics that I've not found yet).

See Question&Answers more detail:os

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome To Ask or Share your Answers For Others

1 Answer

0 votes
by (71.8m points)
  • As has been noted, methods of .NET types such as System.String.Split() are not part of PowerShell, but of the .NET framework that PowerShell is built on, so you'll have to consult the official documentation at https://docs.microsoft.com.

  • That said, given the close integration between PowerShell and .NET, it would be nice to be able to easily consult this documentation from within PowerShell - see this GitHub suggestion.

  • However, operators such as -split are PowerShell language features, and both discovering their documentation altogether and getting focused, operator-specific information is currently cumbersome.

    • Documentation for language features such as operators is contained in about_* help topics, which can be targeted with Get-Help -Category HelpFile, and you can combine that with passing the (quoted) name of the operator in order to search the contents of these topics:

      • For example, Get-Help -Category HelpFile -Name '-replace' at least narrows the search down, but still includes all help topics that mention -replace; the result will comprise the about_Operators help topic, which is the overview page that links to more specific pages focused on specific categories of operators, such as arithmetic operators, comparison operators, ..., but also describes some general-purpose operators directly.
  • There is currently no direct way to get focused information for a given operator, but there should be: see this GitHub suggestion.


Below are two helper functions that try to overcome the current limitations (as of v7.0), Show-OperatorHelp and Show-TypeHelp.

Note:

  • Both functions (of necessity) don't show the documentation in the console (terminal), but open the online documentation in your default web browser.

    • In Show-TypeHelp, support is limited to those (public) types that ship with .NET and therefore have documentation pages at https://docs.microsoft.com.

    • Show-OperatorHelp opens the specific section describing just the operator of interest whenever possible; some operators, such as the arithmetic operators +, -, don't have individual sections, but the overall topic is usually short enough in these cases to make it easy to find the parts of interest.

  • They come with comment-based help, so you can use -? and Get-Help to learn more about them.

  • You can place them in your $PROFILE file, for instance, or - given their length - you may want to create external scripts (*.ps1) based on them that you place in a directory listed in $env:Path. To that end, simply strip the function <name> { line and the final } and save them to a *.ps1 file.

Example uses:

Show-OperatorHelp:

# Opens the home (overview) page for all PowerShell operators
Show-OperatorHelp

# Lists all operators in the console, 
# along with their friendly names and categories.
Show-OperatorHelp -List

# Opens the help topic (section) for the -replace operator.
# Equivalent of 
    Show-OperatorHelp -Name '-replace'
# because you omit the initial '-'; if you do specify it, quote the entire argument.
Show-OperatorHelp replace

# Opens the help topic (section) for @(...), the array-subexpression operator.
# Note the need for quoting.
Show-OperatorHelp '@()'

Show-TypeHelp:

# Opens the documentation for the System.String.Split() method.
#  You can specify a type name ('string' in this example) as follows:
#    * Use a full type name, with the initial 'System.' component optionally omitted (e.g. 'Text.Encoding' for 'System.Text.Encoding'
#    * Use a type accelerator such as 'xml' for 'System.Xml.XmlDocument'
# Tab-completion: You can type (part of) a the name of a type
# (last component of the full name) and cycle through loaded types by that name.
# E.g., typing `arrayli` tab-completes to 'System.Collections.ArrayList'.
# Alternatively, *pipe* an instance of a string to the function (see next example).
Show-TypeHelp string split # Short for: Show-TypeHelp -Type string -Member split

# Opens the documentation for the [Microsoft.PowerShell.Commands.MatchInfo]
# type, instances of which Select-String outputs.
'foo' | Select-String o | Show-TypeHelp

I suggest getting the source code from the following MIT-licensed Gists instead, as only they will be maintained; assuming you have looked at the code (which I can personally assure you is safe, but you should always check), you can install them directly:

irm https://gist.github.com/mklement0/146f3202a810a74cb54a2d353ee4003f/raw/Show-OperatorHelp.ps1 | iex

irm https://gist.github.com/mklement0/50a1b101cd53978cd147b4b138fe6ef4/raw/Show-TypeHelp.ps1 | iex

Note: Ignore the broken syntax highlighting below.

Show-OperatorHelp source code:

function Show-OperatorHelp {
  <#
.SYNOPSIS
Shows documentation for PowerShell's operators.

.DESCRIPTION
Navigates to operator-specific or -related online help topics in your default 
web browser.

Invoke argument-less to see the operators overview help topic.
-Precedence shows the topic about operator precedence.
-QuotingRules shows the topic about string literals and quoting.
-Name <name> targets a specific operator.

.PARAMETER Name
The name of an operator.

Note that most names must be passed *in quotes* for syntactic reasons;
e.g., '-match' instead of -match
However, you may omit the initial '-', in which case you needn't quote.

Use -List to see all names.

.PARAMETER Precedence
Opens the help topic that describes operator precedence.

.PARAMETER List
Parameter description

.PARAMETER QuotingRules
Opens the help topic that describes the quoting rules and syntax for
string literals.

.PARAMETER CopyUrl
Instead of opening the topic page in a browser, copies the page's URL to
the clipboard.

.PARAMETER Version
Specify a specific PowerShell version number (e.g., 7 or 5.1) for which to
display the requested help topic.
By default, the executing engine's version number is used.

.EXAMPLE
Show-OperatorHelp

Opens the home (overview) page for all PowerShell operators.

.EXAMPLE
Show-OperatorHelp replace

Opens the help topic (section) for the -replace operator.
Equivalent of: Show-OperatorHelp -Name '-replace'

.EXAMPLE
Show-OperatorHelp -List

Lists all operators, along with their friendly names and categories.

.EXAMPLE
Show-OperatorHelp -Precedence

Shows the help topic about operator precedence.
#>

  [CmdletBinding(DefaultParameterSetName = 'HomePage', SupportsShouldProcess, PositionalBinding = $false)]
  param (
    [Parameter(ParameterSetName = 'Name', Mandatory, Position = 0)]
    [string] $Name
    ,
    [Parameter(ParameterSetName = 'Precedence')]
    [switch] $Precedence
    ,
    [Parameter(ParameterSetName = 'List')]
    [Alias('ListAvailable')]
    [switch] $List
    ,
    [Parameter(ParameterSetName = 'QuotingRules')]
    [Alias('StringLiterals')]
    [switch] $QuotingRules
    ,
    [Parameter(ParameterSetName = 'Name')]
    [Parameter(ParameterSetName = 'Precedence')]
    [Parameter(ParameterSetName = 'QuotingRules')]
    [Parameter(ParameterSetName = 'HomePage')]
    [Alias('cp')]
    [switch] $CopyUrl
    ,
    [Parameter(ParameterSetName = 'Name')]
    [Parameter(ParameterSetName = 'Precedence')]
    [Parameter(ParameterSetName = 'QuotingRules')]
    [Parameter(ParameterSetName = 'HomePage')]
    [string] $Version # PowerShell version
  )

  # Default to the executing PowerShell engine's version.
  # Note: If no "?view=powershell-<ver>" query string is present,
  #       the currently highest stable version overall is targeted.
  if ($Version) {
    $verObj = $Version -as [version]
    if (-not $verObj) { $verObj = "$Version.0" -as [version] }
    if (-not $verObj) { Throw "Unrecognized PowerShell version number: $Version" }
  }
  else {
    $verObj = $PSVersionTable.PSVersion
  }
  $Version = ('{0}.{1}' -f $verObj.Major, $verObj.Minor) -replace '.0$'

  $opTable = @{
    # about_Arithmetic_Operators
    '-'            = [pscustomobject] @{ Name = '-'; FriendlyName = 'subtraction / sign inversion'; Topic = 'about_Arithmetic_Operators'; Category = 'Arithmetic' } 
    '*'            = [pscustomobject] @{ Name = '*'; FriendlyName = 'multiplication / string replication'; Topic = 'about_Arithmetic_Operators'; Category = 'Arithmetic' } 
    '/'            = [pscustomobject] @{ Name = '/'; FriendlyName = 'division'; Topic = 'about_Arithmetic_Operators'; Category = 'Arithmetic' } 
    '%'            = [pscustomobject] @{ Name = '%'; FriendlyName = 'modulus'; Topic = 'about_Arithmetic_Operators'; Category = 'Arithmetic' } 
    '+'            = [pscustomobject] @{ Name = '+'; FriendlyName = 'addition / string conatenation'; Topic = 'about_Arithmetic_Operators'; Category = 'Arithmetic' } 
    '-band'        = [pscustomobject] @{ Name = '-band'; FriendlyName = 'bitwise AND'; Topic = 'about_Arithmetic_Operators'; Category = 'Bitwise' } 
    '-bor'         = [pscustomobject] @{ Name = '-bor'; FriendlyName = 'bitwise OR'; Topic = 'about_Arithmetic_Operators'; Category = 'Bitwise' } 
    '-bxor'        = [pscustomobject] @{ Name = '-bxor'; FriendlyName = 'bitwise XOR'; Topic = 'about_Arithmetic_Operators'; Category = 'Bitwise' } 
    '-bNot'        = [pscustomobject] @{ Name = '-bNot'; FriendlyName = 'bitwise complement'; Topic = 'about_Arithmetic_Operators'; Category = 'Bitwise' } 
    # about_Assignment_Operators
    '='            = [pscustomobject] @{ Name = '='; FriendlyName = 'assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '+='           = [pscustomobject] @{ Name = '+='; FriendlyName = 'compound assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '-='           = [pscustomobject] @{ Name = '-='; FriendlyName = 'compound assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '*='           = [pscustomobject] @{ Name = '*='; FriendlyName = 'compound assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '/='           = [pscustomobject] @{ Name = '/='; FriendlyName = 'compound assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '%='           = [pscustomobject] @{ Name = '%='; FriendlyName = 'compound assignment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '++'           = [pscustomobject] @{ Name = '++'; FriendlyName = 'increment'; Topic = 'about_Assignment_Operators'; Category = 'Assignment' } 
    '--'           = [pscustomobject] @{ Name 

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome to OStack Knowledge Sharing Community for programmer and developer-Open, Learning and Share
Click Here to Ask a Question

...