How to Access Powershell Select-String Return Values

Santiago Squarzon has provided the crucial pointer in a comment:

• To obtain the line text from a [Microsoft.PowerShell.Commands.MatchInfo] instance that Select-String outputs for each match, access its .Line property.

  • Note: If you're only looking for the line text, PowerShell (Core) 7+ offers a simpler solution, namely the -Raw switch.

  • The property name Line can be misleading, because, strictly speaking, it is the entire text of the matching input string, which, depending on how input is provided, may itself be composed of multiple lines.^[1]

• To obtain which search pattern matched - which is only of interest if multiple patterns were passed - use the .Pattern property.

• To obtain only the matching part of a line, i.e. the part that matched the search pattern, use .Matches.Value (or, more strictly, .Matches[0].Value).

  • Note: .Matches is an array of [System.Text.RegularExpressions.Match] instances, but that array only ever contains multiple elements if -AllMatches was also specified, in order to request potentially multiple matches per line (per input object).

  • If your search regex(es) contain capture groups (subexpressions enclosed in (...)), you can access what they captured via the .Matches[0].Groups property.^[2]

To illustrate all three; note that regex pag. is used to (case-insensitively) match verbatim string PAGE, to illustrate the difference between .Pattern and .Matches.Value; also, the values are enclosed in [...] for delineation:

'PAGE 6' | Select-String -Pattern pag. | ForEach-Object {
  [pscustomobject] @{
    Line = '[{0}]' -f $_.Line
    Pattern = '[{0}]' -f $_.Pattern    
    MatchingLinePart = '[{0}]' -f $_.Matches.Value
  }
}

Output:

Line     Pattern MatchingLinePart
----     ------- ----------------
[PAGE 6] [pag.]  [PAGE]

^{[1] E.g. ("a`nb" | Select-String a).Line outputs the full two-line input string, because it was provided as a single input object.}

^{[2] E.g, 'PAGE 6' | Select-String 'page (\d+)' | ForEach-Object { $_.Matches[0].Groups[1].Value } outputs string 6; index 1 refers to the first (and only) capture group ((...)) in the regex.}

Discovering a cmdlet's output data type:

• Via Get-Member:

  • Pipe a concrete call to Get-Member to discover that call's output type and its members; add -Type Properties to limit the display of members; e.g.:

    PS> 'foo' | Select-String foo | Get-Member -Type Properties 
    
        TypeName: Microsoft.PowerShell.Commands.MatchInfo
    
     Name       MemberType Definition
     ----       ---------- ----------
     Context    Property   Microsoft.PowerShell.Commands.MatchInfoContext Context {get;set;}
     Filename   Property   string Filename {get;}
     IgnoreCase Property   bool IgnoreCase {get;set;}
     Line       Property   string Line {get;set;}
     LineNumber Property   int LineNumber {get;set;}
     Matches    Property   System.Text.RegularExpressions.Match[] Matches {get;set;}
     Path       Property   string Path {get;set;}
     Pattern    Property   string Pattern {get;set;}
    

• Via a cmdlet's documentation: A cmdlet's help contains an OUTPUTS section that describes the .NET data type(s) of the objects output by that cmdlet.

  • To see this section locally, you must invoke Get-Help with the -Full switch, e.g. Get-Help Select-String -Full

    • -Full results in lengthy output in which the OUTPUTS section may get buried; to isolate it, use something like the following:

      (Get-Help Select-String -Full | Out-String) -replace '(?sm).+^(OUTPUTS.+?)^\S.+$', '$1'
      

  • Note that a given cmdlet may situationally produce different output types; e.g., with the -Quiet switch Select-String emits a Boolean.