https://github.com/StartAutomating/Splatter

Simple Scripts to Supercharge Splatting
https://github.com/StartAutomating/Splatter

powershell splatting

Last synced: 2 months ago
JSON representation

Simple Scripts to Supercharge Splatting

• Host: GitHub
• URL: https://github.com/StartAutomating/Splatter
• Owner: StartAutomating
• License: mit
• Created: 2019-07-06T08:11:46.000Z (over 5 years ago)
• Default Branch: main
• Last Pushed: 2023-05-16T03:05:08.000Z (over 1 year ago)
• Last Synced: 2024-05-02T02:59:01.459Z (8 months ago)
• Topics: powershell, splatting
• Language: PowerShell
• Size: 221 KB
• Stars: 62
• Watchers: 9
• Forks: 0
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

• jimsghstars - StartAutomating/Splatter - Simple Scripts to Supercharge Splatting (PowerShell)

README

        





Simple Scripts to Supercharge Splatting



[![Test Build And Publish](https://github.com/StartAutomating/Splatter/actions/workflows/TestBuildAndPublish.yml/badge.svg)](https://github.com/StartAutomating/Splatter/actions/workflows/TestBuildAndPublish.yml)

## 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, or used to generate splatting code.

### 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

### Generating Splatting Code

You can use Out-Splat to generate code that splats.

    Out-Splat -CommandName Get-Command -DefaultParameter @{Module='Splatter';CommandType='Alias'} | Invoke-Expression

You can use also use Out-Splatter to generate whole functions, including help.

    $scriptBlock = 

        Out-Splat -FunctionName Get-SplatterAlias -CommandName Get-Command -DefaultParameter @{

            Module='Splatter';CommandType='Alias'

        } -ExcludeParameter * -Synopsis 'Gets Splatter Aliases' -Description 'Gets aliases from the module Splatter'

    . ([ScriptBlock]::Create($scriptBlock))

    Get-SplatterAlias | Out-String

    Get-Help Get-SplatterAlias | Out-String