en-us/About_Splatter.help.txt
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 |
## Splatter is a simple Splatting toolkit
Splatting is a technique of passing parameters in PowerShell. Splatter makes splatting more powerful, flexible, and easy to use. With Splatter you can: * Splat any object to any command * Pipe splats to commands * Validate splats * Find commands for a splat Splatter is tiny, and can be easily embedded into any module. ### Using Splatter Splatter has four core commands: * Get-Splat (?@) * Find-Splat (??@) * Merge-Splat (*@) * Use-Splat (.@) #### Get-Splat | Alias | Variables | |-----------|----------------------------| | ?@,gSplat | ${?@}, $gSplat, $GetSplat | Get-Splat returns a Dictionary of parameters, given a command or ScriptBlock. This only contains parameters for the command, and converts the parameters into the desired types. Get-Splat can take any object or Dictionary as input. @{Id=$pid;Junk='Data'} | Get-Splat Get-Process # -or @{Id=$pid;Junk='Data'} | ?@ gps # -or @{Id=$pid;Junk='Data'} | & ${?@} gps Get-Splat can take more than one command as input. If it does, it will return the matching inputs for each command. @{FilePath = 'pwsh';ArgumentList = '-noprofile';PassThru=$true} | Use-Splat Start-Process | Add-Member NoteProperty TimeOut 15 -PassThru | Get-Splat Wait-Process, Stop-Process Get-Splat will also attach a properties to the Dictionary. These property won't be used when calling the splat, but can be peeked at: | Property | Description | |---------------|-----------------------------------------------| | Command | The Command | | CouldRun | If the command could run, given the splat | | Invalid | Parameters that are invalid | | Missing | Mandatory parameters that are missing | | PercentFit | % of properties that map to parameters | | Unmapped | Properties that don't map to parameters | $splat = @{id=$pid;foo='bar'} | ?@ gps $splat.Command, $splat.PercentFit, $splat.Unmapped #### Find-Splat | Alias | Variables | |------------|----------------------------| | ??@,fSplat | ${??@}, $fSplat, $FindSplat| Find-Splat will find commands that match a given splat, and return information about a match. @{id=$pid} | Find-Splat *-Process Find-Splat may also be scoped to a given module @{splat=@{}} | Find-Splat -Module Splatter #### Merge-Splat | Alias | Variables | |------------|----------------------------| | *@,mSplat | ${*@}, $mSplat, $MergeSplat| Merge splat will merge multiple splats together. @{a='b'}, @{c='d'} | Merge-Splat #### Use-Splat | Alias | Variables | |--------------|----------------------------------| | .@,uSplat | ${.@}, $uSplat, $UseSplat | Use-Splat will run a splat against one or more commands. @{id=$pid} | Use-Splat Get-Process # Gets the current process # Gets the process, and then doesn't stop the process because Stop-Process is passed WhatIf @{id=$pid;WhatIf=$true} | .@ Get-Process,Stop-Process ### Using Splatter with ScriptBlocks In PowerShell, you can treat any ScriptBlock as a command. Splatter makes this simpler. Take this example, which takes a little bit of input data and uses it in a few different scripts. @{ Name='James' Birthday = '12/17/1981' City = 'Seattle' State = 'Washington' } | .@ { param($Name) "$name" }, { param([DateTime]$Birthday) $ageTimespan = [DateTime]::Now - $birthday "Age:" + [Math]::Floor($ageTimespan.TotalDays / 365) }, { param($city, $state) "$city, $state" } Since Splatter will also convert objects to hashtables, you could also write something like: Import-Csv .\People.csv | .@ { param($Name) "$name" }, { param([DateTime]$Birthday) $ageTimespan = [DateTime]::Now - $birthday "Age:" + [Math]::Floor($ageTimespan.TotalDays / 365) } ### Embedding Splatter Initialize-Splat will output a script containing the core commands for Splatter. Using this output, you can directly embed Splatter into any script or module. Initialize-Splatter To install this into a module: Get-Module TheNameOfYourModule | Split-Path | Push-Location Initialize-Splatter > '@.ps1' Pop-Location Then add the following line to your module: . $psScriptRoot\@.ps1 By default, when Splatter is embedded, it will not export functions or aliases, and you will need to use the variable syntax: & ${?@} # Get-Splat & ${??@} # Find-Splat & ${*@} # Merge-Splat & ${.@} # Use-Splat You can override this by using -AsFunction Initialize-Splatter -AsFunction If you don't need all of the commands, you can use -Verb Initialize-Splatter -Verb Get, Use |