Getting more out of help   Leave a comment

As we were developing PowerShell, we knew that we wanted to provide a capability for searching through the help. Unfortunately, we don’t always get to everything, and this is one of those things that we couldn’t get to.  However, I still sometimes need to search through the help, so I created this little function to do the search.  It searches through the conceptual topics for the string for which I’m looking and with the switch parameter "-all", I search through the descriptions of the cmdlet help as well.

Like most things in PowerShell, it turns out to be pretty simple.  Here’s how I would look for help that has the word "process" in it, I use -all to retrieve cmdlet help in addition to the conceptural (about*) topics. 

PS> search-help process -all
 
HelpTopic                  Reference
---------                  ---------
about_arithmetic_operators The command then processes the parameters as it w...
about_array                .NET Framework. For example, the objects that Get...
about_assignment_operators current process. For example, the following comma...
about_automatic_variables  Contains objects for which an error occurred whil...
about_commonparameters     the command during processing. This variable is
about_environment_variable system path, the number of processors used by the...
about_filter               processes that begin with the letters a through m...
about_foreach              displays any processes whose working-set (memory ...
about_function             filters. The primary difference between the two i...
about_location             As a result, all commands are processed from this...
about_logical_operator     When PowerShell processes this statement, it eval...
about_object               receives the objects from the first command, proc...
about_operator             fact that PowerShell processes operators in a ver...
about_parsing              When processing a command, the PowerShell parser ...
about_pipeline             down the pipeline to the second command. The seco...
about_provider             Alias                ShouldProcess               ...
about_quoting_rules        is passed to the command for processing. Consider...
about_shell_variable       example, the $PID variable stores the process ID ...
about_signing              export process.
about_switch               The keyword "break" indicates that no more proces...
about_wildcard             in order to return specific results. The process ...
default                    get-help get-process   : Displays help about the ...
ForEach-Object             Performs an operation against each of a set of in...
Where-Object               Creates a filter that controls which objects will...
Get-Process                Gets the processes that are running on the local ...
Stop-Process               Stops one or more running processes.
Set-Content                Writes or replaces the content in an item with ne...
Export-Csv                 Creates a comma-separated values (CSV) file that ...
Sort-Object                Sorts objects by property values.
Get-TraceSource            Gets the Windows PowerShell components that are i...

Here’s the search-help script – as you can see, it’s just a few lines.   The interesting bit is the use of Select-Object.  With Select-Object, I create custom objects from both about* help and cmdlet help.  Select-Object allows me to specify which properties I want, but it also allows me to "rename" the property.  This way I can take two disparate bits of information (the bits I get back from Select-String and the bits I get out of the help object) and create objects that will act consistently regardless of their origin.

function Search-Help
{
param ( $pattern, [switch]$all ) $path = “${pshome}\about*.txt” Select-String -list –pattern ${pattern} –path ${path}| select-object @{ n="HelpTopic"; e = {$_.filename -replace ".help.txt"}}, @{n="Reference";e={$_.line.trim()}} if ( $all ) { Get-Help * | where-object { $_.description -match ${pattern}}| select-object @{n="HelpTopic";e={$_.Name}}, @{n="Reference"; e={$_.synopsis}}
} }
I hope this is useful for you!
jim
Advertisements

Posted December 2, 2006 by jtruher3 in PowerShell

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: