piping empty verses none types, example

Pwsh/Pipeline/DifferentParameterSets PipingNone vs Null/DifferentParameterSets PipingNone vs Null.ps1

@@ -0,0 +1,170 @@
+#requires -Modules Pansies
+# Pushd $PSScriptRoot -ea 'ignore'
+'
+tangent after this discord thread: <https://discord.com/channels/180528040881815552/447475598911340559/1180410764075466793>
+which mentions his WIP
+    <https://github.com/JustinGrote/ModuleFast/blob/f6e2623c5db0edcad6576264d889475722b21a73/ModuleFast.psm1#L39>
+
+
+template from: <https://github.com/ninmonkey/notebooks/tree/main/Pwsh/questions_from_discord/Passing%20Arrays%20as%20both%20Parameters%20and%20ValueFromPipeline>
+'
+$Conf = @{
+    Compress = $true
+}
+$C = @{
+    Fg = '#a4dcff'
+    Fg2 = '#576e7d'
+    Fg3 = '#c99176'
+    Fg4 = '#3d9b69'
+    Fg5 = '#d8821f'
+    False = '#a84c1f'
+    True = '#577859'
+}
+function Format.Bool {
+    <#
+    .SYNOPSIS
+        'afs', $true, 'True', $false, 'truefalse', 'falsetrue' | Format.Bool
+    #>
+    # param( $Text )
+    process {
+        $Text = $_
+        if($Text -match 'false') {
+            $Text | New-Text -fg $c.False | Join-String ; return
+        }
+        if($Text -match 'true') {
+            $Text | New-Text -fg $C.True | Join-String ; return
+        }
+        $Text
+    }
+}
+$Str = @{
+    TrueNull = "[␀.True]"
+    Null = "[␀]"
+    Empty = "[␠]"
+    Blank = "[␠.Blank]"
+}
+function Format.Null {
+    <#
+    .SYNOPSIS
+        render null-like values for the console
+    .EXAMPLE
+        $cases = "`n", '', "`u{0}", "`n", "a`nb", $Null, @(), $null
+        foreach($cur in $cases) { $cur | Format.Null }
+    #>
+    # param( $Text )
+    process {
+        $Text = $_ # technically a maybe-text
+        if($null -eq $Text) {
+            return $Str.TrueNull
+        }
+        if( $Text -is 'string' -and [String]::IsNullOrEmpty( $Text ) ) {
+            return $Str.Null
+        }
+        if( $Text -is 'string' -and [String]::IsNullOrWhiteSpace( $Text ) ) {
+            return $Str.Empty
+        }
+
+        if( $Text -isnot 'string' -and [string]::IsNullOrWhiteSpace( $Text )) {
+            return $Str.Blank
+        }
+        return $Text
+    }
+}
+
+
+
+function Get-Test {
+    [CmdletBinding(SupportsShouldProcess)]
+    param (
+        [Parameter(
+            Mandatory,
+            ParameterSetName = 'Specification', Position = 0, ValueFromPipeline)]
+        [AllowEmptyCollection()]
+        [AllowNull()]
+        [int[]]
+        $InputObject
+    )
+    begin {
+
+
+        $JsonSplat = @{
+            Compress = $Conf.Compress
+            WarningAction = 'SilentlyContinue'
+            Depth = 2
+        }
+
+        'Enter: -Begin' | Write-Host -fg $C.Fg4
+        $PSBoundParameters
+            | ConvertTo-Json @JsonSplat
+            | Write-Host -fg $C.Fg3
+
+        '   ExpectingInput? {0}' -f ( $PSCmdlet.MyInvocation.ExpectingInput | Format.Bool )
+            | write-host -fg $C.Fg2
+        '   ParameterSetName = {0}' -f $PSCmdlet.ParameterSetName
+            | write-host -fg $C.Fg
+    }
+    process {
+        'Enter: -Process' | Write-Host -fg $C.Fg4
+        $PSBoundParameters
+            | ConvertTo-Json @JsonSplat
+            | Write-Host -fg $C.Fg3
+
+        '   ExpectingInput? {0}' -f ( $PSCmdlet.MyInvocation.ExpectingInput | Format.Bool )
+            | write-host -fg $C.Fg2
+        '   ParameterSetName = {0}' -f $PSCmdlet.ParameterSetName
+            | write-host -fg $C.Fg
+
+
+        foreach ($item in $InputObject) {
+            Write-Host "  Item: $item"
+        }
+    }
+    end {
+        'Enter: -End' | Write-Host -fg $C.Fg4
+        $PSBoundParameters
+            | ConvertTo-Json @JsonSplat
+            | Write-Host -fg $C.Fg3
+
+        '   ExpectingInput? {0}' -f ( $PSCmdlet.MyInvocation.ExpectingInput | Format.Bool )
+            | write-host -fg $C.Fg2
+        '   ParameterSetName = {0}' -f $PSCmdlet.ParameterSetName
+            | write-host -fg $C.Fg
+
+
+
+    }
+}
+function GetStuff {
+    param(
+        [ValidateSet(
+            'Emit.Null',
+            'Emit.Void',
+            'NothingWithReturn',
+            'NothingWithoutReturn',
+            'AutomationNull'
+        )]
+        [string]$Mode
+    )
+    switch( $Mode) {
+        'AutomationNull' {
+            throw 'nyi: Find the right exception name'
+        }
+        {
+            $_ -in @( 'Emit.Void', 'NothingWithoutReturn' )
+        } {
+            # no-op
+        }
+        'NothingWithReturn' {
+            return
+        }
+        'Emit.Null' {
+            return $Null
+        }
+        default { "throw: unhandled: $Mode" }
+    }
+}
+
+$null | Get-Test -WhatIf -Verbose -Debug
+,@()| Get-Test -Whatif -Verbose -Debug
+
+# Get-Test

Pwsh/Pipeline/DifferentParameterSets PipingNone vs Null/readme.md

@@ -0,0 +1,164 @@
+- [About](#about)
+- [Individual Cases](#individual-cases)
+- [As One Table](#as-one-table)
+- [Screenshots](#screenshots)
+
+
+### About 
+
+
+Can you distinguish between different types of null values? 
+
+![both tests](./screenshot-both.png)
+
+There are 4 base cases tested. the 4th one is done manually because it's triggered by a missing mandatory parameter.
+I experimented both with returning values, compared to similar expressions in interactive mode.
+
+Piping `$null | ...` verses a function that emits null  `{ return $Null } | ...` or returns nothing `{ return } | ...` and without explicit return `{ } | ...`
+
+`GetTest` and `GetStuff` are defined here: [DifferentParameterSets PipingNone vs Null.ps1](./DifferentParameterSets%20PipingNone%20vs%20Null.ps1) . Here's the abbreviated version of `GetStuff`
+
+```ps1
+function GetStuff {
+    switch( $Mode) {
+        'NothingWithoutReturn' {
+            # no-op
+        }
+        'NothingWithReturn' {
+            return
+        }
+        'Emit.Null' { 
+            return $Null
+        }
+        default { "throw: unhandled $Mode" }
+    }
+}
+```
+
+ParameterSet used:
+
+`NA` or `-` means that `block` was not invoked
+`void` means does not exist, `null` means null value, `[]` means empty list
+
+### Individual Cases
+
+----
+
+```ps1
+Get-Test # hit enter, missing mandatory parameter
+```
+
+| Case                           | Expecting? | Block     | ParameterSetName     | InputObject |
+| ------------------------------ | ---------- | --------- | -------------------- | ----------- |
+| `Interactive.MissingMandatory` | false      | `begin`   | `__AllParameterSets` | `[]`        |
+| `Interactive.MissingMandatory` | false      | `process` | `__AllParameterSets` | `[]`        |
+| `Interactive.MissingMandatory` | false      | `end`     | `__AllParameterSets` | `[]`        |
+
+----
+
+```ps1
+Get-Stuff Emit.Null | Get-Test
+```
+
+| Case        | Expecting? | Block     | ParameterSetName     | InputObject |
+| ----------- | ---------- | --------- | -------------------- | ----------- |
+| `Emit.Null` | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Emit.Null` | true       | `process` | `Specification`      | `null`      |
+| `Emit.Null` | true       | `end`     | `Specification`      | `null`      |
+
+----
+
+```ps1
+Get-Stuff NothingWithoutReturn | Get-Test
+```
+
+| Case                   | Expecting? | Block   | ParameterSetName     | InputObject |
+| ---------------------- | ---------- | ------- | -------------------- | ----------- |
+| `NothingWithoutReturn` | true       | `begin` | `__AllParameterSets` | `void`      |
+| `NothingWithoutReturn` | -          | -       | -                    | -           |
+| `NothingWithoutReturn` | true       | `end`   | `__AllParameterSets` | `void`      |
+
+----
+
+```ps1
+Get-Stuff NothingWithReturn | Get-Test
+```
+
+| Case                | Expecting? | Block   | ParameterSetName     | InputObject |
+| ------------------- | ---------- | ------- | -------------------- | ----------- |
+| `NothingWithReturn` | true       | `begin` | `__AllParameterSets` | -           |
+| `NothingWithReturn` | -          | -       | -                    | -           |
+| `NothingWithReturn` | true       | `end`   | `__AllParameterSets` | -           |
+
+
+----
+
+```ps1
+$Null | Get-Test
+```
+
+| Case                   | Expecting? | Block     | ParameterSetName     | InputObject |
+| ---------------------- | ---------- | --------- | -------------------- | ----------- |
+| `Interactive.TrueNull` | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Interactive.TrueNull` | true       | `process` | `Specification`      | `null`      |
+| `Interactive.TrueNull` | true       | `end`     | `Specification`      | `null`      |
+
+
+----
+
+```ps1
+@() | Get-Test
+```
+
+| Case                    | Expecting? | Block   | ParameterSetName     | InputObject |
+| ----------------------- | ---------- | ------- | -------------------- | ----------- |
+| `Interactive.EmptyList` | true       | `begin` | `__AllParameterSets` | `void`      |
+| `Interactive.EmptyList` | true       | -       | -                    | -           |
+| `Interactive.EmptyList` | true       | `end`   | `__AllParameterSets` | `void`      |
+
+----
+
+```ps1
+,@() | Get-Test
+```
+
+| Case                        | Expecting? | Block     | ParameterSetName     | InputObject |
+| --------------------------- | ---------- | --------- | -------------------- | ----------- |
+| `Interactive.WrapEmptyList` | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Interactive.WrapEmptyList` | true       | `process` | `Specification`      | `[]`        |
+| `Interactive.WrapEmptyList` | true       | `end`     | `Specification`      | `[]`        |
+
+
+### As One Table
+
+| Case                           | Expecting? | Block     | ParameterSetName     | InputObject |
+| ------------------------------ | ---------- | --------- | -------------------- | ----------- |
+| `Interactive.MissingMandatory` | false      | `begin`   | `__AllParameterSets` | `[]`        |
+| `Interactive.MissingMandatory` | false      | `process` | `__AllParameterSets` | `[]`        |
+| `Interactive.MissingMandatory` | false      | `end`     | `__AllParameterSets` | `[]`        |
+| `Emit.Null`                    | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Emit.Null`                    | true       | `process` | `Specification`      | `null`      |
+| `Emit.Null`                    | true       | `end`     | `Specification`      | `null`      |
+| `NothingWithoutReturn`         | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `NothingWithoutReturn`         | -          | -         | -                    | -           |
+| `NothingWithoutReturn`         | true       | `end`     | `__AllParameterSets` | `void`      |
+| `NothingWithReturn`            | true       | `begin`   | `__AllParameterSets` | -           |
+| `NothingWithReturn`            | -          | -         | -                    | -           |
+| `NothingWithReturn`            | true       | `end`     | `__AllParameterSets` | -           |
+| `Interactive.TrueNull`         | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Interactive.TrueNull`         | true       | `process` | `Specification`      | `null`      |
+| `Interactive.TrueNull`         | true       | `end`     | `Specification`      | `null`      |
+| `Interactive.EmptyList`        | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Interactive.EmptyList`        | true       | -         | -                    | -           |
+| `Interactive.EmptyList`        | true       | `end`     | `__AllParameterSets` | `void`      |
+| `Interactive.WrapEmptyList`    | true       | `begin`   | `__AllParameterSets` | `void`      |
+| `Interactive.WrapEmptyList`    | true       | `process` | `Specification`      | `[]`        |
+| `Interactive.WrapEmptyList`    | true       | `end`     | `Specification`      | `[]`        |
+
+### Screenshots
+
+![interactive tests](./screenshot-interactive-mode.png)
+
+----
+
+![emit tests](./screenshot-emit-null-types.png)