Public/Write-ssConsoleTitle.ps1
|
function Write-ssConsoleTitle { <# .SYNOPSIS Writes a formatted console title block with configurable padding and colour. .DESCRIPTION Write-ssConsoleTitle outputs a visually distinct title section to the host console, intended for use in structured, phase-driven, or enterprise-grade PowerShell scripts and modules. The function renders: - A top border line - A centred message line enclosed with delimiters - A bottom border line The output is colourised using the specified ConsoleColor and can optionally suppress the trailing newline to allow tighter layout control when composing structured console output. This function is host-dependent and writes directly to the console using Write-Host. It is intended for operational visibility scenarios such as: - Deployment scripts - DevOps pipeline diagnostics - Validation and execution phase markers - Interactive tooling The function follows a structured execution model: 1. Discovery – Calculates message length and layout requirements. 2. Validation – Ensures formatting safety (e.g., minimum padding). 3. Logic – Builds border and formatted title line. 4. Execution – Writes formatted output to the console. .PARAMETER Message The text to display inside the formatted title block. This parameter is mandatory and represents the core visual header that will be emphasised in the console output. .PARAMETER ForegroundColor Specifies the console foreground colour used for the title block. Accepts values from the System.ConsoleColor enumeration. Default value: Cyan .PARAMETER Padding Specifies the number of spaces surrounding the message inside the title delimiters. Minimum effective value: 1 Default value: 2 If a value less than 1 is provided, it is automatically normalised to prevent formatting collapse. .PARAMETER NoTrailingLine When specified, suppresses the automatic newline after the closing border line. This allows advanced layout control when chaining multiple formatted console elements together. .EXAMPLE Write-ssConsoleTitle -Message "Validation Phase" Writes a cyan formatted title block for the text "Validation Phase" with default padding. .EXAMPLE Write-ssConsoleTitle -Message "Deployment Complete" -ForegroundColor Green Writes the title block in green to indicate a successful operation. .EXAMPLE Write-ssConsoleTitle -Message "Processing" -Padding 4 Writes the title block with increased spacing around the message. .EXAMPLE Write-ssConsoleTitle -Message "Next Section" -NoTrailingLine Writes the title block without appending a newline after the closing border, allowing immediate continuation of output. .OUTPUTS None. This function writes directly to the host and does not emit objects to the pipeline. .NOTES Author: owen.heaume Version: 1.0.0 - Initial release Design Considerations: - Host-dependent output (Write-Host). - Safe padding normalisation. - Suitable for enterprise script structuring patterns. - No external dependencies. Recommended Usage: Use as a structural marker within larger automation workflows to clearly separate discovery, validation, logic, and execution phases. #> [CmdletBinding()] param( [Parameter(Mandatory = $true, Position = 0)] [string]$Message, [Parameter(Mandatory = $false)] [System.ConsoleColor]$ForegroundColor = 'Cyan', [Parameter(Mandatory = $false)] [int]$Padding = 2, [Parameter(Mandatory = $false)] [switch]$NoTrailingLine ) process { # 1. Discovery / Device Context $context = [PSCustomObject]@{ MessageLength = $Message.Length TotalWidth = $Message.Length + ($Padding * 2) + 4 SuppressLine = $NoTrailingLine.IsPresent } # 2. Validation # Ensure padding is at least 1 to prevent formatting collapse if ($Padding -lt 1) { $Padding = 1 } # 3. Logic $border = New-Object -TypeName System.String -ArgumentList '-', $context.TotalWidth $titleLine = "-- $( ' ' * ($Padding - 1) )$Message$( ' ' * ($Padding - 1) ) --" # Determine if we append a newline character (`n) or an empty string $suffix = if ($context.SuppressLine) { '' } else { "`n" } # 4. Execution Write-Host $border -ForegroundColor $ForegroundColor Write-Host $titleLine -ForegroundColor $ForegroundColor Write-Host "$border$suffix" -ForegroundColor $ForegroundColor } } |