Elizium.Loopz

1.1.1

Elizium.Loopz.psm1

Set-StrictMode -Version 1.0

$global:LoopzHelpers = @{
  # Helper Script Blocks
  #
  WhItemDecoratorBlock = [scriptblock] {
    param(
      [Parameter(Mandatory)]
      $_underscore,

      [Parameter(Mandatory)]
      [int]$_index,

      [Parameter(Mandatory)]
      [System.Collections.Hashtable]$_passThru,

      [Parameter(Mandatory)]
      [boolean]$_trigger
    )

    return Write-HostFeItemDecorator -Underscore $_underscore `
      -Index $_index `
      -PassThru $_passThru `
      -Trigger $_trigger
  } # WhItemDecoratorBlock

  DefaultHeaderBlock    = [scriptblock] {
    param(
      [System.Collections.Hashtable]$PassThru = @{}
    )

    show-DefaultHeaderBlock -PassThru $PassThru;
  } # SimpleHeaderBlock

  SimpleSummaryBlock   = [scriptblock] {
    param(
      [int]$Count,
      [int]$Skipped,
      [boolean]$Triggered,
      [System.Collections.Hashtable]$PassThru = @{}
    )
  
    show-SimpleSummaryBlock -Count $Count -Skipped $Skipped -Triggered $Triggered -PassThru $PassThru;
  } # SimpleSummaryBlock
}

# Session UI state
#
[int]$global:_LineLength = 121;
[int]$global:_SmallLineLength = 81;
#
$global:LoopzUI = [ordered]@{
  # Line definitions:
  #
  UnderscoreLine      = (New-Object String("_", $_LineLength));
  EqualsLine          = (New-Object String("=", $_LineLength));
  DotsLine            = (New-Object String(".", $_LineLength));
  DashLine            = (New-Object String("-", $_LineLength));
  LightDotsLine       = ((New-Object String(".", (($_LineLength - 1) / 2))).Replace(".", ". ") + ".");
  LightDashLine       = ((New-Object String("-", (($_LineLength - 1) / 2))).Replace("-", "- ") + "-");
  TildeLine           = (New-Object String("~", $_LineLength));

  SmallUnderscoreLine = (New-Object String("_", $_SmallLineLength));
  SmallEqualsLine     = (New-Object String("=", $_SmallLineLength));
  SmallDotsLine       = (New-Object String(".", $_SmallLineLength));
  SmallDashLine       = (New-Object String("-", $_SmallLineLength));
  SmallLightDotsLine  = ((New-Object String(".", (($_SmallLineLength - 1) / 2))).Replace(".", ". ") + ".");
  SmallLightDashLine  = ((New-Object String("-", (($_SmallLineLength - 1) / 2))).Replace("-", "- ") + "-");
  SmallTildeLine      = (New-Object String("~", $_SmallLineLength));
}

function Invoke-ForeachFsItem {
  <#
  .NAME
    Invoke-ForeachFsItem
 
  .SYNOPSIS
    Allows a custom defined scriptblock or function to be invoked for all file system
  objects delivered through the pipeline.
 
  .DESCRIPTION
    2 parameters sets are defined, one for invoking a named function (InvokeFunction) and
  the other (InvokeScriptBlock, the default) for invoking a script-block. An optional
  Summary script block can be specified which will be invoked at the end of the pipeline
  batch. The user should assemble the candidate items from the file system, be they files or
  directories typically using Get-ChildItem, or can be any other function that delivers
  file systems items via the PowerShell pipeline. For each item in the pipeline,
  Invoke-ForeachFsItem will invoke the script-block/function specified. Invoke-ForeachFsItem
  will deliver what ever is returned from the script-block/function, so the result of
  Invoke-ForeachFsItem can be piped to another command.
 
  .PARAMETER pipelineItem
    This is the pipeline object, so should not be specified explicitly and can represent
  a file object (System.IO.FileInfo) or a directory object (System.IO.DirectoryInfo).
 
  .PARAMETER Condition
    This is a predicate scriptblock, which is invoked with either a DirectoryInfo or
  FileInfo object presented as a result of invoking Get-ChildItem. It provides a filtering
  mechanism that is defined by the user to define which file system objects are selected
  for function/scriptblock invocation.
 
  .PARAMETER Block
    The script block to be invoked. The script block is invoked for each item in the
  pipeline that satisfy the Condition with the following positional parameters:
    * pipelineItem: the item from the pipeline
    * index: the 0 based index representing current pipeline item
    * PassThru: a hash table containing miscellaneous information gathered internally
  throughout the pipeline batch. This can be of use to the user, because it is the way
  the user can perform bi-directional communication between the invoked custom script block
  and client side logic.
    * trigger: a boolean value, useful for state changing idempotent operations. At the end
  of the batch, the state of the trigger indicates whether any of the items were actioned.
  When the script block is invoked, the trigger should indicate if the trigger was pulled for
  any of the items so far processed in the pipeline. This is the responsibility of the
  client's block implementation. The trigger is only of use for state changing operations
  and can be ignored otherwise.
   
  In addition to these fixed positional parameters, if the invoked scriptblock is defined
  with additional parameters, then these will also be passed in. In order to achieve this,
  the client has to provide excess parameters in BlockParam and these parameters must be
  defined as the same type and in the same order as the additional parameters in the
  scriptblock.
 
  .PARAMETER BlockParams
    Optional array containing the excess parameters to pass into the script block.
 
  .PARAMETER Functee
    String defining the function to be invoked. Works in a similar way to the Block parameter
  for script-blocks. The Function's base signature is as follows:
    * Underscore: (See pipelineItem described above)
    * Index: (See index described above)
    * PassThru: (See PathThru described above)
    *Trigger: (See trigger described above)
 
  .PARAMETER FuncteeParams
    Optional hash-table containing the named parameters which are splatted into the Functee
  function invoke. As it's a hash table, order is not significant.
 
  .PARAMETER PassThru
    A hash table containing miscellaneous information gathered internally throughout the
  pipeline batch. This can be of use to the user, because it is the way the user can perform
  bi-directional communication between the invoked custom script block and client side logic.
 
  .PARAMETER Header
    A script-block that is invoked at the start of the pipeline batch. The script-block is
  invoked with the following positional parameters:
    * PassThru: (see PassThru previously described)
 
    The Header can be customised with the following PassThru entries:
    - 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use
    - 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header
    - 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '
    - 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed
    - 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are
    predefined lines available to use in $LoopzUI, or a custom one can be used instead)
 
  .PARAMETER Summary
    A script-block that is invoked at the end of the pipeline batch. The script-block is
  invoked with the following positional parameters:
    * count: the number of items processed in the pipeline batch.
    * skipped: the number of items skipped in the pipeline batch. An item is skipped if
    it fails the defined condition or is not of the correct type (eg if its a directory
    but we have specified the -File flag). Also note that, if the script-block/function
    sets the Break flag causing further iteration to stop, then those subsequent items
    in the pipeline which have not been processed are not reflected in the skip count.
    * trigger: Flag set by the script-block/function, but should typically be used to
    indicate whether any of the items processed were actively updated/written in this batch.
    This helps in written idempotent operations that can be re-run without adverse
    consequences.
    * PassThru: (see PassThru previously described)
 
  .PARAMETER File
    Switch to indicate that the invoked function/script-block (invokee) is to handle FileInfo
  objects. Is mutually exclusive with the Directory switch. If neither switch is specified, then
  the invokee must be able to handle both therefore the Underscore parameter it defines must
  be declared as FileSystemInfo.
 
  .PARAMETER Directory
    Switch to indicate that the invoked function/script-block (invokee) is to handle Directory
  objects.
 
  .PARAMETER StartIndex
    Some calling functions interact with Invoke-ForeachFsItem in a way that may require that
  there is external control of the starting index. For example, Invoke-TraverseDirectory
  (which invokes Invoke-ForeachFsItem) handles the root Directory separately from its descendants
  and to ensure that the allocated indices are correct, the starting index should be set to 1,
  because the root Directory has already been allocated index 0, outside of the ForeachFsItem
  batch.
    Normal use of ForeachFsItem does not require StartIndex to be specified.
 
  .EXAMPLE 1
  Invoke a script-block to handle .txt file objects from the same directory (without -Recurse):
  (NB: first parameter is of type FileInfo, -File specified on Get-ChildItem and
  Invoke-ForeachFsItem. If Get-ChildItem is missing -File, then any Directory objects passed in
  are filtered out by Invoke-ForeachFsItem. If -File is missing from Invoke-ForeachFsItem, then
  the script-block's first parameter, must be a FileSystemInfo to handle both types)
 
    [scriptblock]$block = {
      param(
        [System.IO.FileInfo]$FileInfo,
        [int]$Index,
        [System.Collections.Hashtable]$PassThru,
        [boolean]$Trigger
      )
      ...
    }
 
    Get-ChildItem './Tests/Data/fefsi' -Recurse -Filter '*.txt' -File | `
      Invoke-ForeachFsItem -File -Block $block;
 
  .EXAMPLE 2
  Invoke a function with additional parameters to handle directory objects from multiple directories
  (with -Recurse):
 
  function invoke-Target {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger,
      [string]$Format
    )
    ...
  }
 
  [System.Collections.Hashtable]$parameters = @{
    'Format'
  }
  Get-ChildItem './Tests/Data/fefsi' -Recurse -Directory | `
    Invoke-ForeachFsItem -Directory -Functee 'invoke-Target' -FuncteeParams $parameters
 
  .EXAMPLE 3
  Invoke a script-block to handle empty .txt file objects from the same directory (without -Recurse):
    [scriptblock]$block = {
      param(
        [System.IO.FileInfo]$FileInfo,
        [int]$Index,
        [System.Collections.Hashtable]$PassThru,
        [boolean]$Trigger
      )
      ...
    }
 
    [scriptblock]$fileIsEmpty = {
      param(
        [System.IO.FileInfo]$FileInfo
      )
      return (0 -eq $FileInfo.Length)
    }
 
    Get-ChildItem './Tests/Data/fefsi' -Recurse -Filter '*.txt' -File | Invoke-ForeachFsItem `
      -Block $block -File -condition $fileIsEmpty;
 
  .EXAMPLE 4
  Invoke a script-block only for directories whose name starts with "A" from the same
  directory (without -Recurse); Note the use of the LOOPZ function "Select-FsItem" in the
  directory include filter:
 
    [scriptblock]$block = {
      param(
        [System.IO.FileInfo]$FileInfo,
        [int]$Index,
        [System.Collections.Hashtable]$PassThru,
        [boolean]$Trigger
      )
      ...
    }
 
  [scriptblock]$filterDirectories = {
    [OutputType([boolean])]
    param(
      [System.IO.DirectoryInfo]$directoryInfo
    )
    Select-FsItem -Name $directoryInfo.Name -Includes 'A*';
  }
 
    Get-ChildItem './Tests/Data/fefsi' -Directory | Invoke-ForeachFsItem `
      -Block $block -Directory -DirectoryIncludes $filterDirectories;
 
  .EXAMPLE 5
  Invoke a script-block to handle .txt file objects from the same directory. This
  example illustrates the use of the Header and Summary blocks. Blocks predefined
  in LoopzHelpers are illustrated but the user can defined their own.
 
    [scriptblock]$block = {
      param(
        [System.IO.FileInfo]$FileInfo,
        [int]$Index,
        [System.Collections.Hashtable]$PassThru,
        [boolean]$Trigger
      )
      ...
    }
 
    $passThru = @{
      'LOOPZ.KRAYOLA-THEME' = $(Get-KrayolaTheme);
      'LOOPZ.HEADER-BLOCK.MESSAGE' = 'The owls are not what they seem';
      'LOOPZ.HEADER-BLOCK.PROPERTIES' = @(@('A', 'One'), @('B', 'Two'), @('C', 'Three'));
      'LOOPZ.HEADER-BLOCK.LINE' = $LoopzUI.TildeLine;
      'LOOPZ.SUMMARY-BLOCK.LINE' = $LoopzUI.DashLine;
    }
 
    Get-ChildItem './Tests/Data/fefsi' -Recurse -Filter '*.txt' -File | `
      Invoke-ForeachFsItem -File -Block $block -PassThru $passThru `
        -Header $LoopzHelpers.DefaultHeaderBlock -Summary $LoopzHelpers.SimpleSummaryBlock;
  #>
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  [CmdletBinding(DefaultParameterSetName = 'InvokeScriptBlock')]
  [Alias('ife', 'Foreach-FsItem')]
  param(
    [Parameter(ParameterSetName = 'InvokeScriptBlock', Mandatory, ValueFromPipeline = $true)]
    [Parameter(ParameterSetName = 'InvokeFunction', Mandatory, ValueFromPipeline = $true)]
    [System.IO.FileSystemInfo]$pipelineItem,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Condition = ( { return $true; }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock', Mandatory)]
    [scriptblock]$Block,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [ValidateScript( { $_ -is [Array] })]
    $BlockParams = @(),

    [Parameter(ParameterSetName = 'InvokeFunction', Mandatory)]
    [ValidateScript( { -not([string]::IsNullOrEmpty($_)); })]
    [string]$Functee,

    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$FuncteeParams = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$PassThru = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Header = ( {
        param(
          [System.Collections.Hashtable]$_passThru
        )
      }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Summary = ( {
        param(
          [int]$_count,
          [int]$_skipped,
          [boolean]$_trigger,
          [System.Collections.Hashtable]$_passThru
        )
      }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [ValidateScript( { -not($PSBoundParameters.ContainsKey('Directory')) })]
    [switch]$File,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [ValidateScript( { -not($PSBoundParameters.ContainsKey('File')) })]
    [switch]$Directory,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [int]$StartIndex = 0
  ) # param

  begin {
    [boolean]$manageIndex = -not($PassThru.ContainsKey('LOOPZ.FOREACH.INDEX'));
    [int]$index = $manageIndex ? $StartIndex : $PassThru['LOOPZ.FOREACH.INDEX'];
    [int]$skipped = 0;
    [boolean]$broken = $false;
    [boolean]$trigger = $PassThru.ContainsKey('LOOPZ.FOREACH.TRIGGER');

    if ($manageIndex) {
      $Header.Invoke($PassThru);
    }
  }

  process {
    [boolean]$itemIsDirectory = ($pipelineItem.Attributes -band
      [System.IO.FileAttributes]::Directory) -eq [System.IO.FileAttributes]::Directory;

    [boolean]$acceptAll = -not($File.ToBool()) -and -not($Directory.ToBool());

    if (-not($broken)) {
      if ( $acceptAll -or ($Directory.ToBool() -and $itemIsDirectory) -or
        ($File.ToBool() -and -not($itemIsDirectory)) ) {
        if ($Condition.Invoke($pipelineItem)) {
          $result = $null;

          if ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
            $positional = @($pipelineItem, $index, $PassThru, $trigger);

            if ($BlockParams.Length -gt 0) {
              $BlockParams | ForEach-Object {
                $positional += $_;
              }
            }

            $result = Invoke-Command -ScriptBlock $Block -ArgumentList $positional;
          }
          elseif ('InvokeFunction' -eq $PSCmdlet.ParameterSetName) {
            [System.Collections.Hashtable]$parameters = $FuncteeParams.Clone();

            $parameters['Underscore'] = $pipelineItem;
            $parameters['Index'] = $index;
            $parameters['PassThru'] = $PassThru;
            $parameters['Trigger'] = $trigger;

            $result = & $Functee @parameters;
          }

          if ($manageIndex) {
            $index++;
          }
          else {
            $index = $PassThru['LOOPZ.FOREACH.INDEX'];
          }

          if ($result) {
            if ($result.psobject.properties.match('Trigger') -and $result.Trigger) {
              $PassThru['LOOPZ.FOREACH.TRIGGER'] = $true;
              $trigger = $true;
            }

            if ($result.psobject.properties.match('Break') -and $result.Break) {
              $broken = $true;
            }

            if ($result.psobject.properties.match('Product') -and $result.Product) {
              $result.Product;
            }
          }
        }
        else {
          # IDEA! We could allow the user to provide an extra script block which we
          # invoke for skipped items and set a string containing the reason why it was
          # skipped.
          $null = $skipped++;
        }
      }
      else {
        $null = $skipped++;
      }
    }
    else {
      $null = $skipped++;
    }
  }

  end {
    $PassThru['LOOPZ.FOREACH.TRIGGER'] = $trigger;
    $PassThru['LOOPZ.FOREACH.COUNT'] = $manageIndex ? $index : $PassThru['LOOPZ.FOREACH.INDEX'];
    if ($manageIndex) {
      $Summary.Invoke($index, $skipped, $trigger, $PassThru);
    }
  }
} # Invoke-ForeachFsItem
function Invoke-MirrorDirectoryTree {
  <#
  .NAME
    Invoke-MirrorDirectoryTree
 
  .SYNOPSIS
    Mirrors a directory tree to a new location, invoking a custom defined scriptblock
  or function as it goes.
 
  .DESCRIPTION
    Copies a source directory tree to a new location applying custom functionality for each
  directory. 2 parameters set are defined, one for invoking a named function (InvokeFunction) and
  the other (InvokeScriptBlock, the default) for invoking a scriptblock. An optional
  Summary script block can be specified which will be invoked at the end of the mirroring
  batch.
 
  .PARAMETER Path
    The source Path denoting the root of the directory tree to be mirrored.
 
  .PARAMETER DestinationPath
    The destination Path denoting the root of the directory tree where the source tree
  will be mirrored to.
 
  .PARAMETER DirectoryIncludes
    An array containing a list of filters, each must contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be ignored. If the directory
  matches any of the filters in the list, it will be mirrored in the destination tree.
  If DirectoryIncludes contains just a single element which is the empty string, this means
  that nothing is included (rather than everything being included).
 
  .PARAMETER DirectoryExcludes
    An array containing a list of filters, each must contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be ignored. If the directory
  matches any of the filters in the list, it will NOT be mirrored in the destination tree.
  Any match in the DirectoryExcludes overrides a match in DirectoryIncludes, so a directory
  that is matched in Include, can be excluded by the Exclude.
 
  .PARAMETER FileIncludes
    An array containing a list of filters, each may contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be treated as a file suffix.
  If the file in the source tree matches any of the filters in the list, it will be mirrored
  in the destination tree. If FileIncludes contains just a single element which is the empty
  string, this means that nothing is included (rather than everything being included).
 
  .PARAMETER FileExcludes
    An array containing a list of filters, each may contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be treated as a file suffix.
  If the file in the source tree matches any of the filters in the list, it will NOT be
  mirrored in the destination tree. Any match in the FileExcludes overrides a match in
  FileIncludes, so a file that is matched in Include, can be excluded by the Exclude.
 
  .PARAMETER PassThru
    A hash table containing miscellaneous information gathered internally
  throughout the pipeline batch. This can be of use to the user, because it is the way
  the user can perform bi-directional communication between the invoked custom script block
  and client side logic.
 
  .PARAMETER Block
    The script block to be invoked. The script block is invoked for each directory in the
  source directory tree that satisfy the specified Directory Include/Exclude filters with
  the following positional parameters:
    * underscore: the DirectoryInfo object representing the directory in the source tree
    * index: the 0 based index representing current directory in the source tree
    * PassThru object: a hash table containing miscellaneous information gathered internally
    throughout the mirroring batch. This can be of use to the user, because it is the way
    the user can perform bi-directional communication between the invoked custom script block
    and client side logic.
    * trigger: a boolean value, useful for state changing idempotent operations. At the end
    of the batch, the state of the trigger indicates whether any of the items were actioned.
    When the script block is invoked, the trigger should indicate if the trigger was pulled for
    any of the items so far processed in the batch. This is the responsibility of the
    client's script-block/function implementation.
   
  In addition to these fixed positional parameters, if the invoked scriptblock is defined
  with additional parameters, then these will also be passed in. In order to achieve this,
  the client has to provide excess parameters in BlockParams and these parameters must be
  defined as the same type and in the same order as the additional parameters in the
  script-block.
 
  The destination DirectoryInfo object can be accessed via the PassThru denoted by
  the 'LOOPZ.MIRROR.DESTINATION' entry.
 
  .PARAMETER BlockParams
    Optional array containing the excess parameters to pass into the script-block/function.
 
  .PARAMETER Functee
    String defining the function to be invoked. Works in a similar way to the Block parameter
  for script-blocks. The Function's base signature is as follows:
    "Underscore": (See underscore described above)
    "Index": (See index described above)
    "PassThru": (See PathThru described above)
    "Trigger": (See trigger described above)
 
  The destination DirectoryInfo object can be accessed via the PassThru denoted by
  the 'LOOPZ.MIRROR.DESTINATION' entry.
 
  .PARAMETER FuncteeParams
    Optional hash-table containing the named parameters which are splatted into the Functee
  function invoke. As it's a hash table, order is not significant.
 
  .PARAMETER CreateDirs
    Switch parameter indicates that directories should be created in the destination tree. If
  not set, then Invoke-MirrorDirectoryTree turns into a function that traverses the source
  directory invoking the function/script-block for matching directories.
 
  .PARAMETER CopyFiles
    Switch parameter that indicates that files matching the specified filters should be copied
 
  .PARAMETER Hoist
    Switch parameter. Without Hoist being specified, the filters can prove to be too restrictive
  on matching against directories. If a directory does not match the filters then none of its
  descendants will be considered to be mirrored in the destination tree. When Hoist is specified
  then a descendant directory that does match the filters will be mirrored even though any of
  its ancestors may not match the filters.
 
  .PARAMETER Header
    A script-block that is invoked at the start of the mirroring batch. The script-block is
  invoked with the following positional parameters:
    * PassThru: (see PassThru previously described)
 
    The Header can be customised with the following PassThru entries:
    - 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use
    - 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header
    - 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '
    - 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed
    - 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are
    predefined lines available to use in $LoopzUI, or a custom one can be used instead)
 
  .PARAMETER Summary
    A script-block that is invoked at the end of the mirroring batch. The script-block is
  invoked with the following positional parameters:
    * count: the number of items processed in the mirroring batch.
    * skipped: the number of items skipped in the mirroring batch. An item is skipped if
    it fails the defined condition or is not of the correct type (eg if its a directory
    but we have specified the -File flag).
    * trigger: Flag set by the script-block/function, but should typically be used to
    indicate whether any of the items processed were actively updated/written in this batch.
    This helps in written idempotent operations that can be re-run without adverse
    consequences.
    * PassThru: (see PassThru previously described)
 
  .EXAMPLE 1
    Invoke a named function for every directory in the source tree and mirror every
  directory in the destination tree. The invoked function has an extra parameter in it's
  signature, so the extra parameters must be passed in via FuncteeParams (the standard
  signature being the first 4 parameters shown.)
   
  function Test-Mirror {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger,
      [string]$Format
    )
    ...
  }
 
  [System.Collections.Hashtable]$parameters = @{
    'Format' = '---- {0} ----';
  }
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' `
    -DestinationPath './Tests/Data/mirror' -CreateDirs `
    -Functee 'Test-Mirror' -FuncteeParams $parameters;
 
  .EXAMPLE 2
  Invoke a script-block for every directory in the source tree and copy all files
 
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' `
    -DestinationPath './Tests/Data/mirror' -CreateDirs -CopyFiles -block {
      param(
        [System.IO.DirectoryInfo]$Underscore,
        [int]$Index,
        [System.Collections.Hashtable]$PassThru,
        [boolean]$Trigger
      )
      ...
    };
 
  .EXAMPLE 3
  Mirror a directory tree, including only directories beginning with A (filter A*)
 
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' `
    -DirectoryIncludes @('A*')
 
  Note the possible issue with this example is that any descendants named A... which are located
  under an ancestor which is not named A..., will not be mirrored;
 
  eg './Tests/Data/fefsi/Audio/mp3/A/Amorphous Androgynous', even though "Audio", "A" and
  "Amorphous Androgynous" clearly match the A* filter, they will not be mirrored because
  the "mp3" directory, would be filtered out.
  See the following example for a resolution.
 
  .EXAMPLE 4
  Mirror a directory tree, including only directories beginning with A (filter A*) regardless of
  the matching of intermediate ancestors (specifying -Hoist flag resolves the possible
  issue in the previous example)
 
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' `
    -DirectoryIncludes @('A*') -CreateDirs -CopyFiles -Hoist
 
  Note that the directory filter must include a wild-card, otherwise it will be ignored. So a
  directory include of @('A'), is problematic, because A is not a valid directory filter so its
  ignored and there are no remaining filters that are able to include any directory, so no
  directory passes the filter.
 
  .EXAMPLE 5
  Mirror a directory tree, including files with either .flac or .wav suffix
 
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' `
    -FileIncludes @('flac', '*.wav') -CreateDirs -CopyFiles -Hoist
 
  Note that for files, a filter may or may not contain a wild-card. If the wild-card is missing
  then it is automatically treated as a file suffix; so 'flac' means '*.flac'.
 
  .EXAMPLE 6
  Mirror a directory tree copying over just flac files
 
  [scriptblock]$summary = {
    param(
      [int]$_count,
      [int]$_skipped,
      [boolean]$_triggered,
      [System.Collections.Hashtable]$_passThru
    )
    ...
  }
 
  Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' `
    -FileIncludes @('flac') -CopyFiles -Hoist -Summary $summary
 
  Note that -CreateDirs is missing which means directories will not be mirrored by default. They
  are only mirrored as part of the process of copying over flac files, so in the end the
  resultant mirror directory tree will contain directories that include flac files.
  #>

  [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'InvokeScriptBlock')]
  [Alias('imdt', 'Mirror-Directory')]
  param
  (
    [Parameter(Mandatory, ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(Mandatory, ParameterSetName = 'InvokeFunction')]
    [ValidateScript( { Test-path -Path $_; })]
    [String]$Path,

    [Parameter(Mandatory, ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(Mandatory, ParameterSetName = 'InvokeFunction')]
    [String]$DestinationPath,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [String[]]$DirectoryIncludes = @('*'),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [String[]]$DirectoryExcludes = @(),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [String[]]$FileIncludes = @('*'),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [String[]]$FileExcludes = @(),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$PassThru = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [scriptblock]$Block = ( {
        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
        param(
          [System.IO.DirectoryInfo]$underscore,
          [int]$index,
          [System.Collections.Hashtable]$passThru,
          [boolean]$trigger
        )
      } ),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [ValidateScript( { $_ -is [Array] })]
    $BlockParams = @(),

    [Parameter(ParameterSetName = 'InvokeFunction', Mandatory)]
    [ValidateScript( { -not([string]::IsNullOrEmpty($_)); })]
    [string]$Functee,

    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$FuncteeParams = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [switch]$CreateDirs,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [switch]$CopyFiles,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [switch]$Hoist,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Header = ( {
        param(
          [System.Collections.Hashtable]$_passThru
        )
      }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Summary = ( {
        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
        param(
          [int]$_index,
          [int]$_skipped,
          [boolean]$_trigger,
          [System.Collections.Hashtable]$_passThru
        )
      })
  ) # param

  # ================================================================== [doMirrorBlock] ===
  #
  [scriptblock]$doMirrorBlock = {
    param(
      [Parameter(Mandatory)]
      [System.IO.DirectoryInfo]$_underscore,

      [Parameter(Mandatory)]
      [int]$_index,

      [Parameter(Mandatory)]
      [System.Collections.Hashtable]$_passThru,

      [Parameter(Mandatory)]
      [boolean]$_trigger
    )

    # Write-Host "[+] >>> doMirrorBlock: $($_underscore.Name)";

    [string]$rootSource = $_passThru['LOOPZ.MIRROR.ROOT-SOURCE'];
    [string]$rootDestination = $_passThru['LOOPZ.MIRROR.ROOT-DESTINATION'];

    $sourceDirectoryFullName = $_underscore.FullName;

    # sourceDirectoryFullName must end with directory separator
    #
    if (-not($sourceDirectoryFullName.EndsWith([System.IO.Path]::DirectorySeparatorChar))) {
      $sourceDirectoryFullName += [System.IO.Path]::DirectorySeparatorChar;
    }

    $destinationBranch = edit-RemoveSingleSubString -Target $sourceDirectoryFullName -Subtract $rootSource;

    $destinationDirectory = Join-Path -Path $rootDestination -ChildPath $destinationBranch;
    $_passThru['LOOPZ.MIRROR.BRANCH-DESTINATION'] = $destinationBranch;

    [boolean]$whatIf = $_passThru.ContainsKey('WHAT-IF') -and ($_passThru['WHAT-IF']);
    Write-Debug "[+] >>> doMirrorBlock: destinationDirectory: '$destinationDirectory'";

    if ($CreateDirs.ToBool()) {
      Write-Debug " [-] Creating destination branch directory: '$destinationBranch'";

      $destinationInfo = (Test-Path -Path $destinationDirectory) `
        ? (Get-Item -Path $destinationDirectory) `
        : (New-Item -ItemType 'Directory' -Path $destinationDirectory);
    }
    else {
      Write-Debug " [-] Creating destination branch directory INFO obj: '$destinationBranch'";
      $destinationInfo = New-Object -TypeName System.IO.DirectoryInfo ($destinationDirectory);
    }

    if ($CopyFiles.ToBool()) {
      Write-Debug " [-] Creating files for branch directory: '$destinationBranch'";

      # To use the include/exclude parameters on Copy-Item, the Path specified
      # must end in /*. We only need to add the star though because we added the /
      # previously.
      #
      [string]$sourceDirectoryWithWildCard = $sourceDirectoryFullName + '*';

      [string[]]$adjustedFileIncludes = $FileIncludes | ForEach-Object {
        $_.Contains('*') ? $_ : "*.$_".Replace('..', '.');
      }

      [string[]]$adjustedFileExcludes = $FileExcludes | ForEach-Object {
        $_.Contains('*') ? $_ : "*.$_".Replace('..', '.');
      }

      # Ensure that the destination directory exists, but only if there are
      # files to copy over which pass the include/exclude filters. This is
      # required in the case where CreateDirs has not been specified.
      #
      if (Get-ChildItem $sourceDirectoryWithWildCard `
          -Include $adjustedFileIncludes -Exclude $adjustedFileExcludes) {
        if (-not(Test-Path -Path $destinationDirectory)) {
          New-Item -ItemType 'Directory' -Path $destinationDirectory;
        }
      }

      Copy-Item -Path $sourceDirectoryWithWildCard `
        -Include $adjustedFileIncludes -Exclude $adjustedFileExcludes `
        -Destination $destinationDirectory -WhatIf:$whatIf;
    }

    # To be consistent with Invoke-ForeachFsItem, the user function/block is invoked
    # with the source directory info. The destination for this mirror operation is
    # returned via 'LOOPZ.MIRROR.DESTINATION' within the PassThru.
    #
    $_passThru['LOOPZ.MIRROR.DESTINATION'] = $destinationInfo;

    $invokee = $_passThru['LOOPZ.MIRROR.INVOKEE'];

    if ($invokee -is [scriptblock]) {
      $positional = @($_underscore, $_index, $_passThru, $_trigger);

      if ($_passThru.ContainsKey('LOOPZ.MIRROR.INVOKEE.PARAMS')) {
        $_passThru['LOOPZ.MIRROR.INVOKEE.PARAMS'] | ForEach-Object {
          $positional += $_;
        }
      }

      $invokee.Invoke($positional);
    }
    elseif ($invokee -is [string]) {
      [System.Collections.Hashtable]$parameters = $_passThru.ContainsKey('LOOPZ.MIRROR.INVOKEE.PARAMS') `
        ? $_passThru['LOOPZ.MIRROR.INVOKEE.PARAMS'] : @{};
      $parameters['Underscore'] = $_underscore;
      $parameters['Index'] = $_index;
      $parameters['PassThru'] = $_passThru;
      $parameters['Trigger'] = $_trigger;

      & $invokee @parameters;
    }
    else {
      Write-Warning "User defined function/block not valid, not invoking.";
    }


    @{ Product = $destinationInfo }
  } #doMirrorBlock

  # ===================================================== [Invoke-MirrorDirectoryTree] ===

  [string]$resolvedSourcePath = Convert-Path $Path;
  [string]$resolvedDestinationPath = Convert-Path $DestinationPath;

  $PassThru['LOOPZ.MIRROR.ROOT-SOURCE'] = $resolvedSourcePath;
  $PassThru['LOOPZ.MIRROR.ROOT-DESTINATION'] = $resolvedDestinationPath;

  if ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
    $PassThru['LOOPZ.MIRROR.INVOKEE'] = $Block;

    if ($BlockParams.Count -gt 0) {
      $PassThru['LOOPZ.MIRROR.INVOKEE.PARAMS'] = $BlockParams;
    }
  }
  else {
    $PassThru['LOOPZ.MIRROR.INVOKEE'] = $Functee;

    if ($FuncteeParams.Count -gt 0) {
      $PassThru['LOOPZ.MIRROR.INVOKEE.PARAMS'] = $FuncteeParams.Clone();
    }
  }

  if ($PSBoundParameters.ContainsKey('WhatIf') -and ($true -eq $PSBoundParameters['WhatIf'])) {
    $PassThru['WHAT-IF'] = $true;
  }

  [scriptblock]$filterDirectories = {
    [OutputType([boolean])]
    param(
      [System.IO.DirectoryInfo]$directoryInfo
    )
    Select-FsItem -Name $directoryInfo.Name `
      -Includes $DirectoryIncludes -Excludes $DirectoryExcludes;
  }

  $null = Invoke-TraverseDirectory -Path $resolvedSourcePath `
    -Block $doMirrorBlock -PassThru $PassThru -Header $Header -Summary $Summary `
    -Condition $filterDirectories -Hoist:$Hoist;

  $PassThru['LOOPZ.MIRROR.COUNT'] = $PassThru['LOOPZ.TRAVERSE.COUNT'];
} # Invoke-MirrorDirectoryTree

function Invoke-TraverseDirectory {
  <#
  .NAME
    Invoke-TraverseDirectory
 
  .SYNOPSIS
    Traverses a directory tree invoking a custom defined script-block or named function
  as it goes.
 
  .DESCRIPTION
    Navigates a directory tree applying custom functionality for each directory. A Condition
  script-block can be applied for conditional functionality. 2 parameters set are defined, one
  for invoking a named function (InvokeFunction) and the other (InvokeScriptBlock, the default)
  for invoking a scriptblock. An optional Summary script block can be specified which will be
  invoked at the end of the traversal batch.
 
  .PARAMETER Path
    The source Path denoting the root of the directory tree to be traversed.
 
  .PARAMETER Condition
    This is a predicate scriptblock, which is invoked with a DirectoryInfo object presented
  as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined
  by the user to define which directories are selected for function/scriptblock invocation.
 
  .PARAMETER PassThru
    A hash table containing miscellaneous information gathered internally throughout the
  traversal batch. This can be of use to the user, because it is the way the user can perform
  bi-directional communication between the invoked custom script block and client side logic.
 
  .PARAMETER Block
    The script block to be invoked. The script block is invoked for each directory in the
  source directory tree that satisfy the specified Condition predicate with
  the following positional parameters:
    * underscore: the DirectoryInfo object representing the directory in the source tree
    * index: the 0 based index representing current directory in the source tree
    * PassThru object: a hash table containing miscellaneous information gathered internally
    throughout the mirroring batch. This can be of use to the user, because it is the way
    the user can perform bi-directional communication between the invoked custom script block
    and client side logic.
    * trigger: a boolean value, useful for state changing idempotent operations. At the end
    of the batch, the state of the trigger indicates whether any of the items were actioned.
    When the script block is invoked, the trigger should indicate if the trigger was pulled for
    any of the items so far processed in the batch. This is the responsibility of the
    client's script-block/function implementation.
   
  In addition to these fixed positional parameters, if the invoked scriptblock is defined
  with additional parameters, then these will also be passed in. In order to achieve this,
  the client has to provide excess parameters in BlockParams and these parameters must be
  defined as the same type and in the same order as the additional parameters in the
  script-block.
 
  .PARAMETER BlockParams
    Optional array containing the excess parameters to pass into the script-block.
 
  .PARAMETER Functee
    String defining the function to be invoked. Works in a similar way to the Block parameter
  for script-blocks. The Function's base signature is as follows:
    "Underscore": (See underscore described above)
    "Index": (See index described above)
    "PassThru": (See PathThru described above)
    "Trigger": (See trigger described above)
 
  The destination DirectoryInfo object can be accessed via the PassThru denoted by
  the 'LOOPZ.MIRROR.DESTINATION' entry.
 
  .PARAMETER FuncteeParams
    Optional hash-table containing the named parameters which are splatted into the Functee
  function invoke. As it's a hash table, order is not significant.
 
  .PARAMETER Header
    A script-block that is invoked at the start of the mirroring batch. The script-block is
  invoked with the following positional parameters:
    * PassThru: (see PassThru previously described)
 
    The Header can be customised with the following PassThru entries:
    - 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use
    - 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header
    - 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '
    - 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed
    - 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are
    predefined lines available to use in $LoopzUI, or a custom one can be used instead)
 
  .PARAMETER Summary
    A script-block that is invoked at the end of the traversal batch. The script-block is
  invoked with the following positional parameters:
    * count: the number of items processed in the mirroring batch.
    * skipped: the number of items skipped in the mirroring batch. An item is skipped if
    it fails the defined condition or is not of the correct type (eg if its a directory
    but we have specified the -File flag).
    * trigger: Flag set by the script-block/function, but should typically be used to
    indicate whether any of the items processed were actively updated/written in this batch.
    This helps in written idempotent operations that can be re-run without adverse
    consequences.
    * PassThru: (see PassThru previously described)
 
  .PARAMETER Hoist
    Switch parameter. Without Hoist being specified, the Condition can prove to be too restrictive
  on matching against directories. If a directory does not match the Condition then none of its
  descendants will be considered to be traversed. When Hoist is specified then a descendant directory
  that does match the Condition will be traversed even though any of its ancestors may not match the
  same Condition.
 
  .EXAMPLE 1
    Invoke a script-block for every directory in the source tree.
 
    [scriptblock]$block = {
      param(
        $underscore,
        [int]$index,
        [System.Collections.Hashtable]$passThru,
        [boolean]$trigger
      )
      ...
    }
 
  Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Block $block
 
  .EXAMPLE 2
    Invoke a named function with extra parameters for every directory in the source tree.
 
  function Test-Traverse {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger,
      [string]$Format
    )
    ...
  }
  [System.Collections.Hashtable]$parameters = @{
    'Format' = "=== {0} ===";
  }
 
  Invoke-TraverseDirectory -Path './Tests/Data/fefsi' `
    -Functee 'Test-Traverse' -FuncteeParams $parameters;
 
  .EXAMPLE 3
  Invoke a named function, including only directories beginning with A (filter A*)
 
  function Test-Traverse {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger
    )
    ...
  }
 
  [scriptblock]$filterDirectories = {
    [OutputType([boolean])]
    param(
      [System.IO.DirectoryInfo]$directoryInfo
    )
 
    Select-FsItem -Name $directoryInfo.Name -Includes @('A*');
  }
 
  Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Functee 'Test-Traverse' `
    -Condition $filterDirectories;
 
  Note the possible issue with this example is that any descendants named A... which are located
  under an ancestor which is not named A..., will not be processed by the provided function
 
  .EXAMPLE 4
  Mirror a directory tree, including only directories beginning with A (filter A*) regardless of
  the matching of intermediate ancestors (specifying -Hoist flag resolves the possible
  issue in the previous example)
 
  function Test-Traverse {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger
    )
    ...
  }
 
  [scriptblock]$filterDirectories = {
    [OutputType([boolean])]
    param(
      [System.IO.DirectoryInfo]$directoryInfo
    )
 
    Select-FsItem -Name $directoryInfo.Name -Includes @('A*');
  }
 
  Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Functee 'Test-Traverse' `
    -Condition $filterDirectories -Hoist;
 
  Note that the directory filter must include a wild-card, otherwise it will be ignored. So a
  directory include of @('A'), is problematic, because A is not a valid directory filter so its
  ignored and there are no remaining filters that are able to include any directory, so no
  directory passes the filter.
 
  #>
  [CmdletBinding(DefaultParameterSetName = 'InvokeScriptBlock')]
  [Alias('itd', 'Traverse-Directory')]
  param
  (
    [Parameter(ParameterSetName = 'InvokeScriptBlock', Mandatory)]
    [Parameter(ParameterSetName = 'InvokeFunction', Mandatory)]
    [ValidateScript( { Test-path -Path $_ })]
    [String]$Path,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [ValidateScript( { -not($_ -eq $null) })]
    [scriptblock]$Condition = (
      {
        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
        param([System.IO.DirectoryInfo]$directoryInfo)
        return $true;
      }
    ),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$PassThru = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [ValidateScript( { -not($_ -eq $null) })]
    [scriptblock]$Block,

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [ValidateScript( { $_ -is [Array] })]
    $BlockParams = @(),

    [Parameter(ParameterSetName = 'InvokeFunction', Mandatory)]
    [ValidateScript( { -not([string]::IsNullOrEmpty($_)); })]
    [string]$Functee,

    [Parameter(ParameterSetName = 'InvokeFunction')]
    [System.Collections.Hashtable]$FuncteeParams = @{},

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Header = ( {
        param(
          [System.Collections.Hashtable]$_passThru
        )
      }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [scriptblock]$Summary = ( {
        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
        param(
          [int]$_count,
          [int]$_skipped,
          [boolean]$_triggered,
          [System.Collections.Hashtable]$_passThru
        )
      }),

    [Parameter(ParameterSetName = 'InvokeScriptBlock')]
    [Parameter(ParameterSetName = 'InvokeFunction')]
    [switch]$Hoist
  ) # param

  # ======================================================= [recurseTraverseDirectory] ===
  #
  [scriptblock]$recurseTraverseDirectory = { # Invoked by adapter
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
    param(
      [Parameter(Position = 0, Mandatory)]
      [System.IO.DirectoryInfo]$directoryInfo,

      [Parameter(Position = 1)]
      [ValidateScript( { -not($_ -eq $null) })]
      [scriptblock]$condition,

      [Parameter(Position = 2, Mandatory)]
      [ValidateScript( { -not($_ -eq $null) })]
      [System.Collections.Hashtable]$passThru,

      [Parameter(Position = 3)]
      [ValidateScript( { ($_ -is [scriptblock]) -or ($_ -is [string]) })]
      $invokee, # (scriptblock or function name; hence un-typed parameter)

      [Parameter(Position = 4)]
      [boolean]$trigger
    )

    $result = $null;
    $index = $passThru['LOOPZ.FOREACH.INDEX'];

    # This is the invoke, for the current directory
    #
    if ($invokee -is [scriptblock]) {
      $positional = @($directoryInfo, $index, $passThru, $trigger);

      if ($passThru.ContainsKey('LOOPZ.TRAVERSE.INVOKEE.PARAMS') -and
        ($passThru['LOOPZ.TRAVERSE.INVOKEE.PARAMS'].Count -gt 0)) {
        $passThru['LOOPZ.TRAVERSE.INVOKEE.PARAMS'] | ForEach-Object {
          $positional += $_;
        }
      }
      $result = $invokee.Invoke($positional);
    }
    else {
      [System.Collections.Hashtable]$parameters = $passThru.ContainsKey('LOOPZ.TRAVERSE.INVOKEE.PARAMS') `
        ? $passThru['LOOPZ.TRAVERSE.INVOKEE.PARAMS'] : @{};

      # These are directory specific overwrites. The custom parameters
      # will still be present
      #
      $parameters['Underscore'] = $directoryInfo;
      $parameters['Index'] = $index;
      $parameters['PassThru'] = $passThru;
      $parameters['Trigger'] = $trigger;

      $result = & $invokee @parameters;
    }

    $passThru['LOOPZ.FOREACH.INDEX']++;

    [string]$fullName = $directoryInfo.FullName;
    [System.IO.DirectoryInfo[]]$directoryInfos = Get-ChildItem -Path $fullName `
      -Directory | Where-Object { $condition.Invoke($_) };

    [scriptblock]$adapter = $PassThru['LOOPZ.TRAVERSE.ADAPTOR'];

    if ($directoryInfos) {
      # adapter is always a script block, this has nothing to do with the invokee,
      # which may be a script block or a named function(functee)
      #
      $directoryInfos | Invoke-ForeachFsItem -Directory -Block $adapter `
        -PassThru $PassThru -Condition $condition -Summary $Summary;
    }

    return $result;
  } # recurseTraverseDirectory

  # ======================================================================== [adapter] ===
  #
  [scriptblock]$adapter = {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
    param(
      [Parameter(Mandatory)]
      [System.IO.DirectoryInfo]$_underscore,

      [Parameter(Mandatory)]
      [int]$_index,

      [Parameter(Mandatory)]
      [System.Collections.Hashtable]$_passThru,

      [Parameter(Mandatory)]
      [boolean]$_trigger
    )

    [scriptblock]$adapted = $_passThru['LOOPZ.TRAVERSE.ADAPTED'];

    try {
      $adapted.Invoke(
        $_underscore,
        $_passThru['LOOPZ.TRAVERSE.CONDITION'],
        $_passThru,
        $PassThru['LOOPZ.TRAVERSE.INVOKEE'],
        $_trigger
      );
    } catch [System.Management.Automation.MethodInvocationException] {
      # This is a mystery exception, that has no effect on processing the batch:
      #
      # Exception calling ".ctor" with "2" argument(s): "Count cannot be less than zero.
      #
      # Resolve-Error
      # Write-Error "Problem with: '$_underscore'" -ErrorAction Stop;
    } catch {
      Write-Error "[!] Error: $($_.Exception.Message)" -ErrorAction Continue;
    }
  } # adapter

  # ======================================================= [Invoke-TraverseDirectory] ===

  # Handle top level directory, before recursing through child directories
  #

  [System.IO.DirectoryInfo]$directory = Get-Item -Path $Path;

  [boolean]$itemIsDirectory = ($directory.Attributes -band
    [System.IO.FileAttributes]::Directory) -eq [System.IO.FileAttributes]::Directory;

  if ($itemIsDirectory) {
    [boolean]$trigger = $PassThru.ContainsKey('LOOPZ.FOREACH.TRIGGER');
    [boolean]$broken = $false;

    # The index of the top level directory is always 0
    #
    [int]$index = 0;

    if ('InvokeFunction' -eq $PSCmdlet.ParameterSetName) {
      # set-up custom parameters
      #
      [System.Collections.Hashtable]$parameters = $FuncteeParams.Clone();
      $parameters['Underscore'] = $directory;
      $parameters['Index'] = $index;
      $parameters['PassThru'] = $PassThru;
      $parameters['Trigger'] = $trigger;
      $PassThru['LOOPZ.TRAVERSE.INVOKEE.PARAMS'] = $parameters;
    }
    elseif ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
      $positional = @($directory, $index, $PassThru, $trigger);

      if ($BlockParams.Count -gt 0) {
        $BlockParams | Foreach-Object {
          $positional += $_;
        }
      }

      # Note, for the positional parameters, we can only pass in the additional
      # custom parameters provided by the client here via the PassThru otherwise
      # we could accidentally build up the array of positional parameters with
      # duplicated entries. This is in contrast to splatted arguments for function
      # invokes where parameter names are paired with parameter values in a
      # hashtable and naturally prevent duplicated entries. This is why we set
      # 'LOOPZ.TRAVERSE.INVOKEE.PARAMS' to $BlockParams and not $positional.
      #
      $PassThru['LOOPZ.TRAVERSE.INVOKEE.PARAMS'] = $BlockParams;
    }

    if (-not($Hoist.ToBool())) {
      # We only want to manage the index via $PassThru when we are recursing
      # and tells invoke-ForeachFsItem further down the line not to manage the
      # index and not to invoke the Header and Summary.
      #
      $PassThru['LOOPZ.FOREACH.INDEX'] = $index;
      $Header.Invoke($PassThru);
    }
    $result = $null;

    # This is the top level invoke
    #
    if ($Condition.Invoke($directory)) {
      if ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
        $result = $Block.Invoke($positional);
      }
      elseif ('InvokeFunction' -eq $PSCmdlet.ParameterSetName) {
        $result = & $Functee @parameters;
      }

      if ($Hoist.ToBool()) {
        $index++;
      }
      else {
        $PassThru['LOOPZ.FOREACH.INDEX']++;
        $index = $PassThru['LOOPZ.FOREACH.INDEX'];
      }

      if ($result) {
        if ($result.psobject.properties.match('Trigger') -and $result.Trigger) {
          $PassThru['LOOPZ.FOREACH.TRIGGER'] = $true;
          $trigger = $true;
        }

        if ($result.psobject.properties.match('Break') -and $result.Break) {
          $broken = $true;
        }
      } else {
        Write-Debug "Received null invoke result for directory: '$($directory.FullName)'";
      }
    }

    # --- end of top level invoke ----------------------------------------------------------

    if ($Hoist.ToBool()) {
      # Perform non-recursive retrieval of descendant directories
      #
      [System.IO.DirectoryInfo[]]$directoryInfos = Get-ChildItem -Path $Path `
        -Directory -Recurse | Where-Object { $Condition.Invoke($_) }

      if ($directoryInfos) {
        # No need to manage the index, let Invoke-ForeachFsItem do this for us,
        # except we do need to inform Invoke-ForeachFsItem to start the index at
        # +1, because 0 is for the top level directory which has already been
        # handled.
        #
        [System.Collections.Hashtable]$parametersFeFsItem = @{
          'Directory'  = $true;
          'PassThru'   = $PassThru;
          'StartIndex' = $index;
          'Summary'    = $Summary;
        }

        if ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
          $parametersFeFsItem['Block'] = $Block;
          $parametersFeFsItem['BlockParams'] = $BlockParams;
        }
        else {
          $parametersFeFsItem['Functee'] = $Functee;
          $parametersFeFsItem['FuncteeParams'] = $FuncteeParams;
        }

        $directoryInfos | & 'Invoke-ForeachFsItem' @parametersFeFsItem;
      }
    }
    else {
      # Set up the adapter. (NB, can't use splatting because we're invoking a script block
      # as opposed to a named function.)
      #
      $PassThru['LOOPZ.TRAVERSE.CONDITION'] = $Condition;
      $PassThru['LOOPZ.TRAVERSE.ADAPTED'] = $recurseTraverseDirectory;
      $PassThru['LOOPZ.TRAVERSE.ADAPTOR'] = $adapter;

      if ('InvokeScriptBlock' -eq $PSCmdlet.ParameterSetName) {
        $PassThru['LOOPZ.TRAVERSE.INVOKEE'] = $Block;
      }
      elseif ('InvokeFunction' -eq $PSCmdlet.ParameterSetName) {
        $PassThru['LOOPZ.TRAVERSE.INVOKEE'] = $Functee;
      }

      # Now perform start of recursive traversal
      #
      [System.IO.DirectoryInfo[]]$directoryInfos = Get-ChildItem -Path $Path `
        -Directory | Where-Object { $Condition.Invoke($_) }

      if ($directoryInfos) {
        $directoryInfos | Invoke-ForeachFsItem -Directory -Block $adapter `
          -StartIndex $index -PassThru $PassThru -Condition $Condition -Summary $Summary;
      }

      [int]$skipped = 0;
      $index = $PassThru['LOOPZ.FOREACH.INDEX'];
      $trigger = $PassThru['LOOPZ.FOREACH.TRIGGER'];
      $Summary.Invoke($index, $skipped, $trigger, $PassThru);
    }

    $PassThru['LOOPZ.TRAVERSE.COUNT'] = $PassThru['LOOPZ.FOREACH.COUNT'];
  }
  else {
    Write-Error "Path specified '$($Path)' is not a directory";
  }
} # Invoke-TraverseDirectory

function Select-FsItem {
  <#
  .NAME
    Select-FsItem
 
  .SYNOPSIS
    A predicate function that indicates whether an item identified by the Name matches
  the include/exclude filters specified.
 
  .DESCRIPTION
    Use this utility function to help specify a Condition for Invoke-TraverseDirectory.
  This function is partly required because the Include/Exclude parameters on functions
  such as Get-ChildItems/Copy-Item/Get-Item etc only work on files not directories.
 
  .PARAMETER Name
    A string to be matched against the filters.
 
  .PARAMETER Includes
      An array containing a list of filters, each must contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be ignored. If Name matches
  any of the filters in Includes, and are not Excluded, the result will be true.
 
  .PARAMETER Excludes
    An array containing a list of filters, each must contain a wild-card ('*'). If a
  particular filter does not contain a wild-card, then it will be ignored. If the Name
  matches any of the filters in the list, will cause the end result to be false.
  Any match in the Excludes overrides a match in Includes, so an item
  that is matched in Include, can be excluded by the Exclude.
 
  .PARAMETER Case
    Switch parameter which controls case sensitivity of inclusion/exclusion. By default
  filtering is case insensitive. When The Case switch is specified, filtering is case
  sensitive.
 
  .EXAMPLE 1
    Define a Condition that allows only directories beginning with A, but also excludes
    any directory containing '_' or '-'.
 
    [scriptblock]$filterDirectories = {
      [OutputType([boolean])]
      param(
        [System.IO.DirectoryInfo]$directoryInfo
      )
      [string[]]$directoryIncludes = @('A*');
      [string[]]$directoryExcludes = @('*_*', '*-*');
 
      Select-FsItem -Name $directoryInfo.Name `
        -Includes $directoryIncludes -Excludes $directoryExcludes;
 
      Invoke-TraverseDirectory -Path <path> -Block <block> -Condition $filterDirectories;
    }
  #>

  [OutputType([boolean])]
  param(
    [Parameter(Mandatory)]
    [string]$Name,

    [Parameter()]
    [string[]]$Includes = @(),

    [Parameter()]
    [string[]]$Excludes = @(),

    [Parameter()]
    [switch]$Case
  )

  # Note we wrap the result inside @() array designator just in-case the where-object
  # returns just a single item in which case the array would be flattened out into
  # an individual scalar value which is what we don't want, damn you powershell for
  # doing this and making life just so much more difficult. Actually, on further
  # investigation, we don't need to wrap inside @(), because we've explicitly defined
  # the type of the includes variables to be arrays, which would preserve the type
  # even in the face of powershell annoyingly flattening the single item array. @()
  # being left in for clarity and show of intent.
  #
  [string[]]$validIncludes = @($Includes | Where-Object { $_.Contains('*') })
  [string[]]$validExcludes = @($Excludes | Where-Object { $_.Contains('*') })

  [boolean]$resolvedInclude = $validIncludes `
    ? (select-ResolvedFsItem -FsItem $Name -Filter $Includes -Case:$Case) `
    : $false;

  [boolean]$resolvedExclude = $validExcludes `
    ? (select-ResolvedFsItem -FsItem $Name -Filter $Excludes -Case:$Case) `
    : $false;

  ($resolvedInclude) -and -not($resolvedExclude)
} # Select-FsItem
function Write-HostFeItemDecorator {
  <#
  .NAME
    Write-HostFeItemDecorator
 
  .SYNOPSIS
    Wraps a function or scriptblock as a decorator writing appropriate user interface
    info to the host for each entry in the pipeline.
 
  .DESCRIPTION
      The script-block/function (invokee) being decorated may or may not Support ShouldProcess. If it does,
    then the client should add 'WHAT-IF' to the pass through, set to the current
    value of WhatIf; or more accurately the existence of 'WhatIf' in PSBoundParameters. Or another
    way of putting it is, the presence of WHAT-IF indicates SupportsShouldProcess, and the value of
    'WHAT-IF' dictates the value of WhatIf. This way, we only need a single
    value in the PassThru, rather than having to represent SupportShouldProcess explicitly with
    another value.
      The PastThru must contain either a 'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' entry meaning
    a named function is being decorated or 'LOOPZ.WH-FOREACH-DECORATOR.BLOCK' meaning a script
    block is being decorated, but not both.
      By default, Write-HostFeItemDecorator will display an item no for each object in the pipeline
    and a property representing the Product. The Product is a property that the invokee can set on the
    PSCustomObject it returns. However, additional properties can be displayed. This can be achieved by
    the invokee populating another property Pairs, which is an array of string based key/value pairs. All
    properties found in Pairs will be written out by Write-HostFeItemDecorator.
      By default, to render the value displayed (ie the 'Product' property item on the PSCustomObject
    returned by the invokee), ToString() is called. However, the 'Product' property may not have a
    ToString() method, in this case (you will see an error indicating ToString method not being
    available), the user should provide a custom script-block to determine how the value is
    constructed. This can be done by assigning a custom script-block to the
    'LOOPZ.WH-FOREACH-DECORATOR.GET-RESULT' entry in PassThru. eg:
 
      [scriptblock]$customGetResult = {
        param($result)
        $result.SomeCustomPropertyOfRelevanceThatIsAString;
      }
      $PassThru['LOOPZ.WH-FOREACH-DECORATOR.GET-RESULT'] = $customGetResult;
      ...
 
      Note also, the user can provide a custom 'GET-RESULT' in order to control what is displayed
    by Write-HostFeItemDecorator.
 
      This function is designed to be used with Invoke-ForeachFsItem and as such, it's signature
    needs to match that required by Invoke-ForeachFsItem. Any additional parameters can be
    passed in via the PassThru.
      The rationale behind Write-HostFeItemDecorator is to maintain separation of concerns
    that allows development of functions that could be used with Invoke-ForeachFsItem which do
    not contain any UI related code. This strategy also helps for the development of different
    commands that produce output to the terminal in a consistent manner.
 
  .PARAMETER $Underscore
    The current pipeline object.
 
  .PARAMETER $Index
    The 0 based index representing current item in the pipeline.
 
  .PARAMETER $PassThru
    A hash table containing miscellaneous information gathered internally
    throughout the iteration batch. This can be of use to the user, because it is the way
    the user can perform bi-directional communication between the invoked custom script block
    and client side logic.
 
  .PARAMETER $Trigger
      A boolean value, useful for state changing idempotent operations. At the end
    of the batch, the state of the trigger indicates whether any of the items were actioned.
    When the script block is invoked, the trigger should indicate if the trigger was pulled for
    any of the items so far processed in the batch. This is the responsibility of the
    client's block implementation.
 
  .RETURNS
    The result of invoking the decorated script-block.
 
  .EXAMPLE 1
 
  function Test-FN {
    param(
      [System.IO.DirectoryInfo]$Underscore,
      [int]$Index,
      [System.Collections.Hashtable]$PassThru,
      [boolean]$Trigger,
    )
 
    $format = $PassThru['CLIENT.FORMAT'];
    @{ Product = $format -f $Underscore.Name, $Underscore.Exists }
    ...
  }
 
  [Systems.Collection.Hashtable]$passThru = @{
    'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' = 'Test-FN';
    'CLIENT.FORMAT' = '=== [{0}] -- [{1}] ==='
  }
 
  Get-ChildItem ... | Invoke-ForeachFsItem -Path <path> -PassThru $passThru
    -Functee 'Write-HostFeItemDecorator'
 
    So, Test-FN is not concerned about writing any output to the console, it simply does
  what it does silently and Write-HostFeItemDecorator handles generation of output. It
  invokes the function defined in 'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' and generates
  corresponding output. It happens to use the console colouring facility provided by a
  a dependency Elizium.Krayola to create colourful output in a predefined format via the
  Krayola Theme.
 
  Note, Write-HostFeItemDecorator does not forward additional parameters to the decorated
  function (Test-FN), but this can be circumvented via the PassThru as illustrated by
  the 'CLIENT.FORMAT' parameter in this example.
 
  #>

  [OutputType([PSCustomObject])]
  [CmdletBinding()]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "")]
  [Alias('wife', 'Decorate-Foreach')]
  param (
    [Parameter(
      Mandatory = $true
    )]
    $Underscore,

    [Parameter(
      Mandatory = $true
    )]
    [int]$Index,

    [Parameter(
      Mandatory = $true
    )]
    [ValidateScript( {
        return ($_.ContainsKey('LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME') -xor
          $_.ContainsKey('LOOPZ.WH-FOREACH-DECORATOR.BLOCK'))
      })]
    [System.Collections.Hashtable]
    $PassThru,

    [Parameter()]
    [boolean]$Trigger
  )

  [scriptblock]$defaultGetResult = {
    param($result)
    $result.ToString();
  }

  [scriptblock]$decorator = {
    param ($_underscore, $_index, $_passthru, $_trigger)

    if ($_passthru.Contains('LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME')) {
      [string]$functee = $_passthru['LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME'];

      [System.Collections.Hashtable]$parameters = @{
        'Underscore' = $_underscore;
        'Index'      = $_index;
        'PassThru'   = $_passthru;
        'Trigger'    = $_trigger;
      }
      if ($_passthru.Contains('WHAT-IF')) {
        $parameters['WhatIf'] = $_passthru['WHAT-IF'];
      }

      return & $functee @parameters;
    }
    elseif ($_passthru.Contains('LOOPZ.WH-FOREACH-DECORATOR.BLOCK')) {
      [scriptblock]$block = $_passthru['LOOPZ.WH-FOREACH-DECORATOR.BLOCK'];

      return $block.Invoke($_underscore, $_index, $_passthru, $_trigger);
    }
  }

  $invokeResult = $decorator.Invoke($Underscore, $Index, $PassThru, $Trigger);

  [string]$message = $PassThru['LOOPZ.WH-FOREACH-DECORATOR.MESSAGE'];
  [string]$productValue = [string]::Empty;
  [boolean]$ifTriggered = $PassThru.ContainsKey('LOOPZ.WH-FOREACH-DECORATOR.IF-TRIGGERED');
  [boolean]$resultIsTriggered = $invokeResult.psobject.properties.match('Trigger') -and $invokeResult.Trigger;

  # Suppress the write if client has set IF-TRIGGERED and the result is not triggered.
  # This makes re-runs of a state changing operation less verbose if that's required.
  #
  if (-not($ifTriggered) -or ($resultIsTriggered)) {
    $getResult = $PassThru.Contains('LOOPZ.WH-FOREACH-DECORATOR.GET-RESULT') `
      ? $PassThru['LOOPZ.WH-FOREACH-DECORATOR.GET-RESULT'] : $defaultGetResult;

    [string[][]]$themedPairs = @(, @('No', $("{0,3}" -f ($Index + 1))));

    # Get Product if it exists
    #
    [string]$productLabel = [string]::Empty;
    if ($invokeResult -and $invokeResult.psobject.properties.match('Product') -and $invokeResult.Product) {
      [boolean]$affirm = $invokeResult.psobject.properties.match('Affirm') -and $invokeResult.Affirm;
      $productValue = $getResult.Invoke($invokeResult.Product);
      $productLabel = $PassThru.ContainsKey('LOOPZ.WH-FOREACH-DECORATOR.PRODUCT-LABEL') `
        ? $PassThru['LOOPZ.WH-FOREACH-DECORATOR.PRODUCT-LABEL'] : 'Product';

      if (-not([string]::IsNullOrWhiteSpace($productLabel))) {
        $themedPairs += , @($productLabel, $productValue, $affirm);
      }
    }

    # Get Key/Value Pairs
    #
    if ($invokeResult -and $invokeResult.psobject.properties.match('Pairs') -and
      $invokeResult.Pairs -and ($invokeResult.Pairs -is [Array]) -and ($invokeResult.Pairs.Count -gt 0)) {
      $themedPairs += $invokeResult.Pairs;
    }

    # Write with a Krayola Theme
    #
    [System.Collections.Hashtable]$krayolaTheme = `
      $PassThru.ContainsKey('LOOPZ.KRAYOLA-THEME') `
      ? $PassThru['LOOPZ.KRAYOLA-THEME'] : (Get-KrayolaTheme);

    [System.Collections.Hashtable]$parameters = @{}
    $parameters['Pairs'] = $themedPairs;
    $parameters['Theme'] = $krayolaTheme;

    [string]$writerFn = 'Write-ThemedPairsInColour';

    if (-not([string]::IsNullOrWhiteSpace($message))) {
      $parameters['Message'] = $message;
    }

    if (-not([string]::IsNullOrWhiteSpace($writerFn))) {
      & $writerFn @parameters;
    }
  }

  return $invokeResult;
} # Write-HostFeItemDecorator

function edit-RemoveSingleSubString {
  <#
.NAME
  edit-RemoveSingleSubString
 
.SYNOPSIS
  Removes a sub-string from the target string provided.
 
.DESCRIPTION
  Either the first or the last occurrence of a single can be removed depending on
  whether the Last flag has been set.
 
.PARAMETER Target
  The string from which the subtraction is to occur.
 
.PARAMETER Subtract
  The sub string to subtract from the Target.
 
.PARAMETER Insensitive
  Flag to indicate if the search is case sensitive or not. By default, search is case
  sensitive.
 
.PARAMETER Last
  Flag to indicate whether the last occurrence of a sub string is to be removed from the
  Target.
#>
  [CmdletBinding(DefaultParameterSetName = 'Single')]
  [OutputType([string])]
  param
  (
    [Parameter(ParameterSetName = 'Single')]
    [String]$Target,

    [Parameter(ParameterSetName = 'Single')]
    [String]$Subtract,

    [Parameter(ParameterSetName = 'Single')]
    [switch]$Insensitive,

    [Parameter(ParameterSetName = 'Single')]
    [Parameter(ParameterSetName = 'LastOnly')]
    [switch]$Last
  )

  [StringComparison]$comparison = $Insensitive.ToBool() ? `
    [StringComparison]::OrdinalIgnoreCase : [StringComparison]::Ordinal;

  $result = $Target;

  # https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings
  #
  if (($Subtract.Length -gt 0) -and ($Target.Contains($Subtract, $comparison))) {
    $slen = $Subtract.Length;

    $foundAt = $Last.ToBool() ? $Target.LastIndexOf($Subtract, $comparison) : `
      $Target.IndexOf($Subtract, $comparison);

    if ($foundAt -eq 0) {
      $result = $Target.Substring($slen);
    }
    elseif ($foundAt -gt 0) {
      $result = $Target.Substring(0, $foundAt);
      $result += $Target.Substring($foundAt + $slen);
    }
  }

  $result;
}

function Resolve-Error ($ErrorRecord = $Error[0]) {
  $ErrorRecord | Format-List * -Force
  $ErrorRecord.InvocationInfo | Format-List *
  $Exception = $ErrorRecord.Exception
  for ($i = 0; $Exception; $i++, ($Exception = $Exception.InnerException)) {
    "$i" * 80
    $Exception | Format-List * -Force
  }
}
  function select-ResolvedFsItem {
    [OutputType([boolean])]
    param(
      [Parameter(Mandatory)]
      [string]$FsItem,

      [Parameter(Mandatory)]
      [AllowEmptyCollection()]
      [string[]]$Filter,

      [Parameter()]
      [switch]$Case
    )

    [boolean]$liked = $false;
    [int]$counter = 0;

    do {
      $liked = $Case.ToBool() `
        ? $FsItem -CLike $Filter[$counter] `
        : $FsItem -Like $Filter[$counter];
      $counter++;
    } while (-not($liked) -and ($counter -lt $Filter.Count));

    $liked;
  }

function show-DefaultHeaderBlock {
  param(
    [System.Collections.Hashtable]$PassThru
  )

  [System.Collections.Hashtable]$krayolaTheme = $PassThru.ContainsKey(
    'LOOPZ.KRAYOLA-THEME') `
    ? $PassThru['LOOPZ.KRAYOLA-THEME'] : $(Get-KrayolaTheme);

  $metaColours = $krayolaTheme['META-COLOURS'];

  [string]$message = $PassThru.ContainsKey(
    'LOOPZ.HEADER-BLOCK.MESSAGE') ? $PassThru['LOOPZ.HEADER-BLOCK.MESSAGE'] : [string]::Empty;

  [string]$crumb = $PassThru.ContainsKey(
    'LOOPZ.HEADER-BLOCK.CRUMB') ? $PassThru['LOOPZ.HEADER-BLOCK.CRUMB'] : '[+] ';

  [string[][]]$properties = $PassThru.ContainsKey(
    'LOOPZ.HEADER.PROPERTIES') ? $PassThru['LOOPZ.HEADER.PROPERTIES'] : @();

  [string]$line = $PassThru.ContainsKey('LOOPZ.HEADER-BLOCK.LINE') `
    ? $PassThru['LOOPZ.HEADER-BLOCK.LINE'] : (New-Object String("_", $_LineLength));

  $colouredLine = @($line) + $metaColours;

  if ($properties.Length -gt 0) {
    # First line
    #
    if ($PassThru.ContainsKey('LOOPZ.HEADER-BLOCK.LINE')) {
      $line = $PassThru['LOOPZ.HEADER-BLOCK.LINE'];
      $colouredLine = @($line) + $metaColours;

      Write-InColour -TextSnippets @(, $colouredLine);
    }

    # Inner detail
    #
    [System.Collections.Hashtable]$parameters = @{
      'Theme' = $krayolaTheme;
      'Pairs' = $properties;
    }

    if (-not([string]::IsNullOrEmpty($message))) {
      $parameters['Message'] = $message;
    }

    & 'Write-ThemedPairsInColour' @parameters;

    # Second line
    #
    if ($colouredLine) {
      Write-InColour -TextSnippets @(, $colouredLine);
    }
  }
  else {
    # Alternative line
    #
    $open = $krayolaTheme['OPEN'];
    $close = $krayolaTheme['CLOSE'];
    $char = (-not($line[0] -eq ' ')) ? $line[0] : $line[1]; # Todo: Index check

    if ([string]::IsNullOrEmpty($message)) {
      $colouredLine = @($line) + $metaColours;
      Write-InColour -TextSnippets @(, $colouredLine);
    }
    else {
      $extra = 4 + $crumb.Length; # extra chars in formats
      $tailLength = 3;
      $messageColours = $krayolaTheme['MESSAGE-COLOURS'];
      $leadFormat = "{0}{1} {2} ";
      $tailFormat = " {0} {1}";
 
      if ($message.Length -gt ($line.Length - $open.Length - $close.Length - $extra)) {
        $lead = (New-Object String($char, $tailLength))
        $tail = (New-Object String($char, $tailLength));
      }
      else {
        $deductions = $extra + $tailLength;
        $leadLength = $line.Length - $deductions - $open.Length - $message.Length - $close.Length;
        $lead = (New-Object String($char, $leadLength));
        $tail = (New-Object String($char, $tailLength));
      }

      $colouredLine = @(
        @(@($leadFormat -f $crumb, $lead, $open) + $metaColours),
        @(@($message) + $messageColours),
        @(@($tailFormat -f $close, $tail) + $metaColours)
      );
      Write-InColour -TextSnippets $colouredLine;
    }
  }
} # show-DefaultHeaderBlock

function show-SimpleSummaryBlock {
  param(
    [int]$Count,
    [int]$Skipped,
    [boolean]$Triggered,
    [System.Collections.Hashtable]$PassThru = @{}
  )

  [System.Collections.Hashtable]$krayolaTheme = $PassThru.ContainsKey(
    'LOOPZ.KRAYOLA-THEME') `
    ? $PassThru['LOOPZ.KRAYOLA-THEME'] : $(Get-KrayolaTheme);

  $metaColours = $krayolaTheme['META-COLOURS'];

  # First line
  #
  $line = $colouredLine = $null;
  if ($PassThru.ContainsKey('LOOPZ.SUMMARY-BLOCK.LINE')) {
    $line = $PassThru['LOOPZ.SUMMARY-BLOCK.LINE'];
    $colouredLine = @($line) + $metaColours;

    Write-InColour -TextSnippets @(, $colouredLine);
  }

  # Inner detail
  #
  [string[][]]$properties = @(
    @('Count', $Count),
    @('Skipped', $Skipped),
    @('Triggered', $Triggered)
  )

  [string[][]]$summaryProperties = $PassThru.ContainsKey(
    'LOOPZ.SUMMARY-BLOCK.PROPERTIES') ? $PassThru['LOOPZ.SUMMARY-BLOCK.PROPERTIES'] : @();

  if ($summaryProperties.Length -gt 0) {
    $properties += $summaryProperties;
  }

  [string]$message = $PassThru.ContainsKey('LOOPZ.SUMMARY-BLOCK.MESSAGE') `
    ? $PassThru['LOOPZ.SUMMARY-BLOCK.MESSAGE'] : 'Summary';

  Write-ThemedPairsInColour -Pairs $properties -Theme $krayolaTheme -Message $message;

  # Wide items
  #
  if ($PassThru.ContainsKey('LOOPZ.SUMMARY-BLOCK.WIDE-ITEMS')) {
    [string[][]]$wideItems = $PassThru['LOOPZ.SUMMARY-BLOCK.WIDE-ITEMS'];
    $keyColours = $krayolaTheme['KEY-COLOURS'];
    $valueColours = $krayolaTheme['VALUE-COLOURS'];

    foreach ($item in $wideItems) {
      Write-InColour -TextSnippets @(
        @(@(, $item[0]) + $keyColours),
        @(@(, ': ') + $metaColours),
        @(@(, $item[1]) + $valueColours)
      )
    }
  }

  # Second line
  #
  if ($colouredLine) {
    Write-InColour -TextSnippets @(, $colouredLine);
  }
} # show-SimpleSummaryBlock

function get-AffirmedProduct {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '')]
  param(
    [Alias('Underscore')]
    [System.IO.FileInfo]$FileInfo,
    [int]$Index,
    [System.Collections.Hashtable]$PassThru,
    [boolean]$Trigger
  )

  [PSCustomObject]@{ Product = $FileInfo; Affirm = $true}
}
function get-AnswerAdvancedFn {

  # This function is only required because the tests using the invoke operator
  # on a string can not correctly pick up the local function name (ie defined as part
  # of the test fixture) and see its definition to be invoked.
  #
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '')]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  [CmdletBinding(SupportsShouldProcess)]
  param(
    [Parameter(Mandatory)]
    $Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger
  )

  [PSCustomObject]@{ Product = "{0}: {1}" -f $Underscore, $PassThru['ANSWER'] }
}
function get-AnswerAdvancedFnWithTrigger {

  # This function is only required because the tests using the invoke operator
  # on a string can not correctly pick up the local function name (ie defined as part
  # of the test fixture) and see its definition to be invoked.
  #
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '')]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  [CmdletBinding(SupportsShouldProcess)]
  param(
    [Parameter(Mandatory)]
    $Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger
  )

  [PSCustomObject]@{ Product = ("{0}: {1}" -f $Underscore, $PassThru['ANSWER']);
    Trigger = $true }
}

# WTF, this should be a helper file in Tests/Helpers, but putting this function there and trying to
# dynamically invoke the function with the & operator from invoke-ForachFile doesnt find the
# function definition, regardless of wether its sourced inside BeforeEach, or defined inline or
# any other work-around. The only temporary shit solution, is to include the test helper function
# inside the module implementation, which fucks me off to high fucking heaven.
#
function invoke-Dummy {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '')]
  param(
    [Alias('Underscore')]
    [System.IO.FileInfo]$FileInfo,
    [int]$Index,
    [System.Collections.Hashtable]$PassThru,
    [boolean]$Trigger
  )
  Write-Warning "These aren't the droids you're looking for, ..., move along, move along!";

  [PSCustomObject]@{ Product = $FileInfo; }
}

function Test-FileResult {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  param(
    [Parameter(Mandatory)]
    [System.IO.FileInfo]$Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger,

    [Parameter(Mandatory)]
    [string]$Format
  )

  [string]$result = $Format -f ($Underscore.Name);
  Write-Debug "Custom function; Test-FileResult: '$result'";
  @{ Product = $Underscore }
}

function Test-FireEXBreak {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  param(
    [Parameter(Mandatory)]
    [System.IO.DirectoryInfo]$Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger
  )
  $break = ('EX' -eq $Underscore.Name);
  Write-Host " [-] Test-FireEXBreak(index: $Index): directory: $($Underscore.Name)";
  @{ Product = $Underscore; Break = $break }
}

function Test-FireEXTrigger {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  param(
    [Parameter(Mandatory)]
    [System.IO.DirectoryInfo]$Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger
  )
  $localTrigger = ('EX' -eq $Underscore.Name);
  Write-Host " [-] Test-FireEXTrigger(index: $Index, local trigger: $localTrigger, Trigger: $Trigger): directory: $($Underscore.Name)";
  @{ Product = $Underscore; Trigger = $localTrigger }
}

function Test-HoistResult {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  param(
    [Parameter(Mandatory)]
    [System.IO.DirectoryInfo]$Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger,

    [Parameter(Mandatory = $false)]
    [string]$Format = "These aren't the droids you're looking for, ..., move along, move along!:___{0}___"
  )

  [string]$result = $Format -f ($Underscore.Name);
  Write-Debug "Custom function; Test-HoistResult: '$result'";
  @{ Product = $Underscore }
}

function Test-ShowMirror {
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
  param(
    [Parameter(Mandatory)]
    [System.IO.DirectoryInfo]$Underscore,

    [Parameter(Mandatory)]
    [int]$Index,

    [Parameter(Mandatory)]
    [System.Collections.Hashtable]$PassThru,

    [Parameter(Mandatory)]
    [boolean]$Trigger,

    [Parameter(Mandatory)]
    [string]$Format
  )

  [string]$result = $Format -f ($Underscore.Name);
  Write-Debug "Custom function; Show-Mirror: '$result'";
  @{ Product = $Underscore }
}
Export-ModuleMember -Variable LoopzHelpers, LoopzUI

Export-ModuleMember -Function Invoke-ForeachFsItem, Invoke-MirrorDirectoryTree, Invoke-TraverseDirectory, Select-FsItem, Write-HostFeItemDecorator