Get-Walkthru.ps1
|
function Get-Walkthru { <# .Synopsis Gets information from a file as a walkthru .Description Parses walkthru steps from a walkthru file. Walkthru files contain step-by-step examples for using PowerShell. .Link Write-WalkthruHTML .Example Get-Walkthru -Text { # Walkthrus are just scripts with comments that start at column 0. # Step 1: Get-Process #Step 2: Get-Command } #> [CmdletBinding(DefaultParameterSetName="File")] [OutputType([PSObject])] param( # The command used to generate walkthrus [Parameter(Mandatory=$true, ParameterSetName="Command", ValueFromPipeline=$true)] [Management.Automation.CommandInfo] $Command, # The module containing walkthrus [Parameter(Mandatory=$true, ParameterSetName="Module", ValueFromPipeline=$true)] [Management.Automation.PSModuleInfo] $Module, # The file used to generate walkthrus [Parameter(Mandatory=$true, ParameterSetName="File", ValueFromPipelineByPropertyName=$true)] [Alias('Fullname')] [string]$File, # The text used to generate walkthrus [Parameter(Mandatory=$true, ParameterSetName="Text")] [String]$Text, # The script block used to generate a walkthru [Parameter(Mandatory=$true, ParameterSetName="ScriptBlock")] [ScriptBlock]$ScriptBlock ) begin { $err = $null #region Create walkthru type if it doesn't exist if (-not ('PSWalkthru.WalkthruData' -as [Type])) { Add-Type -UsingNamespace System.Management.Automation -Namespace PSWalkthru -Name WalkthruData -MemberDefinition ' public string SourceFile = String.Empty;',' public string Command = String.Empty;',' public string Explanation = String.Empty;',' public string AudioFile = String.Empty;',' public string VideoFile = String.Empty;',' public string Question = String.Empty;',' public string Answer = String.Empty;',' public string Link = String.Empty;',' public string Screenshot = String.Empty;',' public string[] Hint;',' public ScriptBlock Script; public ScriptBlock Silent;',' public DateTime LastWriteTime; ' } #endregion Create walkthru type if it doesn't exist } process { if ($psCmdlet.ParameterSetName -eq "File") { # If the walkthru's in a file, open it and send it to Get-Walthru -Text $realItem = Get-Item $file -ErrorAction SilentlyContinue if (-not $realItem) { return } $text = [IO.File]::ReadAllText($realItem.FullName) $Result = Get-Walkthru -Text $text if ($result) { # If there was in fact walkthru information, add on the file name and the last write time. foreach ($r in $result) { $r.Sourcefile = $realItem.Fullname $r.LastWriteTime = $realItem.LastWriteTime $r } } return } elseif ($psCmdlet.ParameterSetName -eq "Command") { # If they want to see a command's examples a a walkthru, then pass each example to Get-Walkthru -Text $help = $command | Get-Help $c= 1 $help.Examples.Example | ForEach-Object { $text = $_.code + ($_.remarks | Out-String) Get-Walkthru -Text $text | ForEach-Object { $_.Command = "$command Walkthru $c" $_ } $c++ } return } elseif ($psCmdlet.ParameterSetName -eq 'Module') { # For modules, enumerate all files for the current culture, then pass them down to Get-Walkthru -File $moduleRoot = Split-Path $module.Path Get-ChildItem -Path (Join-Path $moduleRoot "$(Get-Culture)") -Filter *.walkthru.help.txt | Get-Walkthru return } if ($psCmdlet.ParameterSetName -eq 'ScriptBlock') { $text = "$ScriptBlock" } # Tokenize the script $tokens = [Management.Automation.PSParser]::Tokenize($text, [ref]$err) if ($err.Count) { return } $lastToken = $null $isInContent = $false $lastResult = New-Object PSWalkthru.WalkthruData foreach ($token in $tokens) { if ($token.Type -eq "Newline") { continue } if ($token.Type -ne "Comment" -or $token.StartColumn -gt 1) { $isInContent = $true if (-not $lastToken) { $lastToken = $token } } else { if ($lastToken.Type -ne "Comment" -and $lastToken.StartColumn -eq 1) { $chunk = $text.Substring($lastToken.Start, $token.Start - 1 - $lastToken.Start) $lastResult.Script = [ScriptBlock]::Create($chunk) # mutliparagraph, split up the results if multiparagraph $paragraphs = @() $lastResult $null = $paragraphs $lastToken = $null $lastResult = New-Object PSWalkthru.WalkthruData $isInContent = $false } } if ($isInContent) { if ($token.Type -eq 'Comment' -and $token.StartColumn -eq 1) { $chunk = $text.Substring($lastToken.Start, $token.Start - 1 - $lastToken.Start) $lastResult.Script = [ScriptBlock]::Create($chunk) # mutliparagraph, split up the results if multiparagraph $paragraphs = @() $lastResult $null = $paragraphs $lastToken = $null $lastResult = New-Object PSWalkthru.WalkthruData $isInContent = $false } } if (-not $isInContent) { $lines = $token.Content.Trim("<>#") $lines = $lines.Split([Environment]::NewLine, [StringSplitOptions]"RemoveEmptyEntries") # Handle specialized return data foreach ($_ in $lines) { if ($_ -like ".Audio *" ) { $lastResult.AudioFile = ($_ -ireplace "\.Audio","").Trim() } elseif ($_ -like ".Video *" ) { $lastResult.VideoFile = ($_ -ireplace "\.Video","").Trim() } elseif ($_ -like ".Question *"){ $lastResult.Question = ($_ -ireplace "\.Question","").Trim() } elseif ($_ -like ".Answer *" ) { $lastResult.Answer = ($_ -ireplace "\.Answer","").Trim() } elseif ($_ -like ".Hint *") { $lastResult.Hint = $_.Substring(".Hint ".Length) -split ',' } elseif ($_ -like ".Link *") { $lastResult.Link = ($_ -ireplace "\.link","").Trim() } elseif ($_ -like ".Screenshot *") { $lastResult.Screenshot = ($_ -ireplace "\.Screenshot","").Trim() } elseif ($_ -like "*.Silent *") { $lastResult.Silent = [ScriptBlock]::Create(($_ -ireplace "\.Silent","").Trim()) } else { if ($_.TrimEnd().EndsWith(".")) { $lastResult.Explanation += ($_ + [Environment]::NewLine + [Environment]::NewLine + [Environment]::NewLine ) } else { $lastResult.Explanation += ($_ + [Environment]::NewLine) } } } } } if ($lastToken -and $lastResult) { $chunk = $text.Substring($lastToken.Start) $lastResult.Script = [ScriptBlock]::Create($chunk) $lastResult } elseif ($lastResult) { $lastResult } } } |