Splatter

0.5.1

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