Functions and Scripts

# 'function' gives a block of code a name so you can reuse it.
# Naming convention is Verb-Noun, the same as built-in cmdlets (Get-Date).
function Get-Greeting {
    # param() lists the inputs. [string] is the TYPE; = "World" is a DEFAULT.
    param([string]$Name = "World")

    # Any value you leave "hanging" (not assigned to a variable) is OUTPUT.
    "Hello, $Name!"
}

# Call it. PowerShell args are SPACE-separated and named with a leading dash:
Get-Greeting                 # uses the default -> Hello, World!
Get-Greeting -Name "Alice"   # passes a value   -> Hello, Alice!
Get-Greeting Bob             # positional (no -Name) also works -> Hello, Bob!

Hello, World!
Hello, Alice!
Hello, Bob!

# 🎯 YOUR TURN — replace each ___ , then run it.
function Get-Area {
    param(
        # 1) Give -Width a type of [int] and a default of 1
        [___]$Width = ___,    # 👉 type is [int], default is 1

        # 2) Give -Height a type of [int] and a default of 1
        [int]$Height = ___    # 👉 default is 1
    )

    # 3) Output the area. Wrap maths in $(...) so it calculates inside the text
    "Area is $(___)"          # 👉 $Width * $Height
}

Get-Area -Width 4 -Height 3
Get-Area                       # both default to 1

# ✅ Expected output:
#    Area is 12
#    Area is 1

Area is 12
Area is 1

# [Parameter(Mandatory)] forces the caller to supply a value.
# [CmdletBinding()] turns this into an "advanced function" — it now gets
# free common parameters like -Verbose and -ErrorAction, just like a real cmdlet.
function New-Password {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]    # if you omit -Length, PowerShell PROMPTS for it
        [int]$Length,

        [string]$Prefix = "pw"     # optional, has a default
    )

    # Write-Verbose only prints when the caller passes -Verbose. It does NOT
    # pollute the function's real output — handy for progress messages.
    Write-Verbose "Building a password of length $Length"

    $chars = -join ((1..$Length) | ForEach-Object { 'x' })
    "$Prefix-$chars"
}

New-Password -Length 5
New-Password -Length 3 -Prefix "key"

pw-xxxxx
key-xxx

# Make a function accept PIPELINE input with two pieces:
#   [Parameter(ValueFromPipeline)]  -> "values can arrive from the pipeline"
#   a process {} block              -> runs ONCE PER item that comes down the pipe
function ConvertTo-Upper {
    param(
        [Parameter(ValueFromPipeline)]
        [string]$Text
    )
    process {
        # Inside process{}, $Text is the CURRENT item. $_ also refers to it.
        $Text.ToUpper()
    }
}

# Send three strings down the pipeline — process{} fires three times.
"hello", "world", "powershell" | ConvertTo-Upper

# It still works as a normal parameter too:
ConvertTo-Upper -Text "direct"

HELLO
WORLD
POWERSHELL
DIRECT

# 🎯 YOUR TURN — make Get-Square accept pipeline input and a required label.
function Get-Square {
    [CmdletBinding()]
    param(
        # 1) Mark -Number so values can arrive FROM the pipeline
        [Parameter(___)]            # 👉 ValueFromPipeline
        [int]$Number,

        # 2) Make -Label required
        [Parameter(___)]            # 👉 Mandatory
        [string]$Label
    )
    # 3) This must run once per piped item — name the block correctly
    ___ {                          # 👉 process
        "$Label $Number = $($Number * $Number)"
    }
}

1, 2, 3 | Get-Square -Label "sq"

# ✅ Expected output:
#    sq 1 = 1
#    sq 2 = 4
#    sq 3 = 9

sq 1 = 1
sq 2 = 4
sq 3 = 9

# THE BIG RULE: everything a function emits becomes its output.
# 'return' does NOT mean "this is the result" — it just STOPS the function and
# hands back whatever you put after it (which is also added to the output).
function Get-Total {
    param([int[]]$Numbers)

    "Starting..."                      # ⚠️ this string is ALSO output (a leak!)
    $sum = ($Numbers | Measure-Object -Sum).Sum   # assigned -> NOT output
    return $sum                        # stops here and emits $sum
}

# Because "Starting..." was emitted, the caller gets TWO objects back:
$result = Get-Total -Numbers 1, 2, 3
"Captured: $result"

# Fix: don't emit stray values. Use Write-Host/Write-Verbose for messages,
# which are NOT part of the data output.
function Get-CleanTotal {
    param([int[]]$Numbers)
    Write-Host "Starting..."           # message channel, not the output channel
    ($Numbers | Measure-Object -Sum).Sum
}
$clean = Get-CleanTotal -Numbers 1, 2, 3
"Clean: $clean"

Captured: Starting... 6
Starting...
Clean: 6