functions/string/Set-PSUString.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
function Set-PSUString
{
<#
    .SYNOPSIS
        Replaces a part of the input string with another.
     
    .DESCRIPTION
        Replaces a part of the input string with another.
        Supports both regex replace as well as regular .replace().
     
    .PARAMETER InputString
        The stringgs on which replacement will be performed.
     
    .PARAMETER What
        What should be replace?
     
    .PARAMETER With
        With what should it be replaced?
     
    .PARAMETER Simple
        By default, this function uses regex replace. Sometimes this may not be desirable.
        This switch enforces simple replacement, not considering any regular expression functionality.
     
    .PARAMETER Options
        Default: IgnoreCase
        When using regex replace, it may become desirable to specify options to the system.
     
    .PARAMETER EnableException
        Replaces user friendly yellow warnings with bloody red exceptions of doom!
        Use this if you want the function to throw terminating errors you want to catch.
     
    .EXAMPLE
        "abc ABC" | replace b d
     
        Returns "adc AdC".
     
    .EXAMPLE
        "abc ABC" | replace b d -Options None
     
        Returns "adc ABC"
     
    .EXAMPLE
        "abc \def" | replace "\de" "&ed" -s
     
        Returns "abc &edf"
#>

    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [OutputType([System.String])]
    [CmdletBinding(DefaultParameterSetName = "regex")]
    Param (
        [Parameter(ValueFromPipeline = $true)]
        [string[]]
        $InputString,
        
        [Parameter(Position = 0, Mandatory = $true)]
        [string]
        $What,
        
        [Parameter(Position = 1, Mandatory = $true)]
        [AllowEmptyString()]
        [object]
        $With,
        
        [Parameter(ParameterSetName = "Simple")]
        [Alias('s')]
        [switch]
        $Simple,
        
        [Parameter(ParameterSetName = "Regex")]
        [System.Text.RegularExpressions.RegexOptions]
        $Options = [System.Text.RegularExpressions.RegexOptions]::IgnoreCase,
        
        [switch]
        $EnableException
    )
    
    begin
    {
        if ($With -isnot [System.Management.Automation.ScriptBlock])
        {
            $With = "$With"
        }
        elseif ($Simple)
        {
            Stop-PSFFunction -Message "Cannot do a lambda replace with a simple string replacement. Please specify a string or remove the simple parameter." -EnableException $EnableException -Category InvalidArgument -Tag 'fail','validate'
            return
        }
    }
    process
    {
        if (Test-PSFFunctionInterrupt) { return }
        
        foreach ($line in $InputString)
        {
            try
            {
                if ($Simple) { $line.Replace($What, $With) }
                else { [regex]::Replace($line, $What, $With, $Options) }
            }
            catch
            {
                Stop-PSFFunction -Message "Failed to replace line" -EnableException $EnableException -ErrorRecord $_ -Tag 'Fail', 'record' -Continue
            }
        }
    }
}
Import-PSUAlias -Name replace -Command Set-PSUString