Add Support for 4bit ANSI Color codes

[0-0-1-0-1-0-1-0]

I was hoping to maybe add a feature that can come in handy with regards to using Write-Color within azure pipelines.

The TTY output console in Azure Pipelines supports 4 bit ANSI color coding of the output. Making this useful for others to use in Azure Pipelines powershell scripts.

Works on PoSH5 and 7

I modified the script to account for this manually and it has worked well for us. Basically i added a swtich for ANSI, probably could add a 4bit and 8bit switch, but 4bit is all I needed.

It then uses the ANSI codes for output. Figured I throw this your way and see if it could be merged with the package and have the nuget/PoSH gallery updated to support as others might find this useful.

function Write-Color {
    <#
    .SYNOPSIS
    Write-Color is a wrapper around Write-Host delivering a lot of additional features for easier color options.

    .DESCRIPTION
    Write-Color is a wrapper around Write-Host delivering a lot of additional features for easier color options.

    It provides:
    - Easy manipulation of colors,
    - Logging output to file (log)
    - Nice formatting options out of the box.
    - Ability to use aliases for parameters

    .PARAMETER Text
    Text to display on screen and write to log file if specified.
    Accepts an array of strings.

    .PARAMETER Color
    Color of the text. Accepts an array of colors. If more than one color is specified it will loop through colors for each string.
    If there are more strings than colors it will start from the beginning.
    Available colors are: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White

    .PARAMETER BackGroundColor
    Color of the background. Accepts an array of colors. If more than one color is specified it will loop through colors for each string.
    If there are more strings than colors it will start from the beginning.
    Available colors are: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White

    .PARAMETER StartTab
    Number of tabs to add before text. Default is 0.

    .PARAMETER LinesBefore
    Number of empty lines before text. Default is 0.

    .PARAMETER LinesAfter
    Number of empty lines after text. Default is 0.

    .PARAMETER StartSpaces
    Number of spaces to add before text. Default is 0.

    .PARAMETER LogFile
    Path to log file. If not specified no log file will be created.

    .PARAMETER DateTimeFormat
    Custom date and time format string. Default is yyyy-MM-dd HH:mm:ss

    .PARAMETER LogTime
    If set to $true it will add time to log file. Default is $true.

    .PARAMETER LogRetry
    Number of retries to write to log file, in case it can't write to it for some reason, before skipping. Default is 2.

    .PARAMETER Encoding
    Encoding of the log file. Default is Unicode.

    .PARAMETER ShowTime
    Switch to add time to console output. Default is not set.

    .PARAMETER NoNewLine
    Switch to not add new line at the end of the output. Default is not set.

    .PARAMETER NoConsoleOutput
    Switch to not output to console. Default all output goes to console.

    .EXAMPLE
    Write-Color -Text "Red ", "Green ", "Yellow " -Color Red,Green,Yellow

    .EXAMPLE
    Write-Color -Text "This is text in Green ",
                      "followed by red ",
                      "and then we have Magenta... ",
                      "isn't it fun? ",
                      "Here goes DarkCyan" -Color Green,Red,Magenta,White,DarkCyan

    .EXAMPLE
    Write-Color -Text "This is text in Green ",
                      "followed by red ",
                      "and then we have Magenta... ",
                      "isn't it fun? ",
                      "Here goes DarkCyan" -Color Green,Red,Magenta,White,DarkCyan -StartTab 3 -LinesBefore 1 -LinesAfter 1

    .EXAMPLE
    Write-Color "1. ", "Option 1" -Color Yellow, Green
    Write-Color "2. ", "Option 2" -Color Yellow, Green
    Write-Color "3. ", "Option 3" -Color Yellow, Green
    Write-Color "4. ", "Option 4" -Color Yellow, Green
    Write-Color "9. ", "Press 9 to exit" -Color Yellow, Gray -LinesBefore 1

    .EXAMPLE
    Write-Color -LinesBefore 2 -Text "This little ","message is ", "written to log ", "file as well." `
                -Color Yellow, White, Green, Red, Red -LogFile "C:\testing.txt" -TimeFormat "yyyy-MM-dd HH:mm:ss"
    Write-Color -Text "This can get ","handy if ", "want to display things, and log actions to file ", "at the same time." `
                -Color Yellow, White, Green, Red, Red -LogFile "C:\testing.txt"

    .EXAMPLE
    Write-Color -T "My text", " is ", "all colorful" -C Yellow, Red, Green -B Green, Green, Yellow
    Write-Color -t "my text" -c yellow -b green
    Write-Color -text "my text" -c red

    .EXAMPLE
    Write-Color -Text "Testuję czy się ładnie zapisze, czy będą problemy" -Encoding unicode -LogFile 'C:\temp\testinggg.txt' -Color Red -NoConsoleOutput

    .NOTES
    Understanding Custom date and time format strings: https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings
    Project support: https://github.com/EvotecIT/PSWriteColor
    Original idea: Josh (https://stackoverflow.com/users/81769/josh)

    #>
    [alias('Write-Colour')]
    [CmdletBinding()]
    param (
        [alias ('T')] [String[]]$Text,
        [alias ('C', 'ForegroundColor', 'FGC')] [ConsoleColor[]]$Color = [ConsoleColor]::White,
        [alias ('B', 'BGC')] [ConsoleColor[]]$BackGroundColor = $null,
        [alias ('Indent')][int] $StartTab = 0,
        [int] $LinesBefore = 0,
        [int] $LinesAfter = 0,
        [int] $StartSpaces = 0,
        [alias ('L')] [string] $LogFile = '',
        [Alias('DateFormat', 'TimeFormat')][string] $DateTimeFormat = 'yyyy-MM-dd HH:mm:ss',
        [alias ('LogTimeStamp')][bool] $LogTime = $true,
        [int] $LogRetry = 2,
        [ValidateSet('unknown', 'string', 'unicode', 'bigendianunicode', 'utf8', 'utf7', 'utf32', 'ascii', 'default', 'oem')][string]$Encoding = 'Unicode',
        [switch] $ShowTime,
        [switch] $NoNewLine,
        [alias('HideConsole')][switch] $NoConsoleOutput,
        [switch] $ANSI
    )
    if (-not $NoConsoleOutput) {
        $DefaultColor = $Color[0]
        if ($null -ne $BackGroundColor -and $BackGroundColor.Count -ne $Color.Count) {
            Write-Error "Colors, BackGroundColors parameters count doesn't match. Terminated."
            return
        }
        if ($LinesBefore -ne 0) { for ($i = 0; $i -lt $LinesBefore; $i++) { Write-Host -Object "`n" -NoNewline } } # Add empty line before
        if ($StartTab -ne 0) { for ($i = 0; $i -lt $StartTab; $i++) { Write-Host -Object "`t" -NoNewline } }  # Add TABS before text
        if ($StartSpaces -ne 0) { for ($i = 0; $i -lt $StartSpaces; $i++) { Write-Host -Object ' ' -NoNewline } }  # Add SPACES before text
        if ($ShowTime) { Write-Host -Object "[$([datetime]::Now.ToString($DateTimeFormat))] " -NoNewline } # Add Time before output

        if ($ANSI) {
            $ANSIColors = @{
                Black = "$([char]0x1b)[30m"; Blue = "$([char]0x1b)[34m"; Green = "$([char]0x1b)[32m"; Cyan = "$([char]0x1b)[36m";
                Red = "$([char]0x1b)[31m"; Magenta = "$([char]0x1b)[35m"; Yellow = "$([char]0x1b)[33m"; White = "$([char]0x1b)[37m";
                DarkGray = "$([char]0x1b)[90m"; DarkBlue = "$([char]0x1b)[94m"; DarkGreen = "$([char]0x1b)[92m"; DarkCyan = "$([char]0x1b)[96m";
                DarkRed = "$([char]0x1b)[91m"; DarkMagenta = "$([char]0x1b)[95m"; DarkYellow = "$([char]0x1b)[93m"; Gray = "$([char]0x1b)[97m"
            }
            $ANSIBackgroundColors = @{
                Black = "$([char]0x1b)[40m"; Blue = "$([char]0x1b)[44m"; Green = "$([char]0x1b)[42m"; Cyan = "$([char]0x1b)[46m";
                Red = "$([char]0x1b)[41m"; Magenta = "$([char]0x1b)[45m"; Yellow = "$([char]0x1b)[43m"; White = "$([char]0x1b)[47m";
                DarkGray = "$([char]0x1b)[100m"; DarkBlue = "$([char]0x1b)[104m"; DarkGreen = "$([char]0x1b)[102m"; DarkCyan = "$([char]0x1b)[106m";
                DarkRed = "$([char]0x1b)[101m"; DarkMagenta = "$([char]0x1b)[105m"; DarkYellow = "$([char]0x1b)[103m"; Gray = "$([char]0x1b)[107m"
            }
            $ANSIReset = "$([char]0x1b)[0m"
            for ($i = 0; $i -lt $Text.Length; $i++) {
                $colorCode = $ANSIColors[$Color[$i].ToString()]
                $bgColorCode = if ($BackGroundColor) { $ANSIBackgroundColors[$BackGroundColor[$i].ToString()] } else { "" }
                [string]$newString = $Text[$i].Replace("`n", "`n${colorCode}${bgColorCode}")
                $outputText = "${colorCode}${bgColorCode}${newString}${ANSIReset}"
                Write-Host -Object $outputText -NoNewline
            }
        } else {
            if ($Text.Count -ne 0) {
                if ($Color.Count -ge $Text.Count) {
                    # the real deal coloring
                    if ($null -eq $BackGroundColor) {
                        for ($i = 0; $i -lt $Text.Length; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $Color[$i] -NoNewline
                        }
                    } else {
                        for ($i = 0; $i -lt $Text.Length; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $Color[$i] -BackgroundColor $BackGroundColor[$i] -NoNewline
                        }
                    }
                } else {
                    if ($null -eq $BackGroundColor) {
                        for ($i = 0; $i -lt $Color.Length ; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $Color[$i] -NoNewline
                        }
                        for ($i = $Color.Length; $i -lt $Text.Length; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $DefaultColor -NoNewline
                        }
                    } else {
                        for ($i = 0; $i -lt $Color.Length ; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $Color[$i] -BackgroundColor $BackGroundColor[$i] -NoNewline
                        }
                        for ($i = $Color.Length; $i -lt $Text.Length; $i++) {
                            Write-Host -Object $Text[$i] -ForegroundColor $DefaultColor -BackgroundColor $BackGroundColor[0] -NoNewline
                        }
                    }
                }
            }
        }
        if ($NoNewLine -eq $true) {
            Write-Host -NoNewline
        } else {
            Write-Host
        }
        if ($LinesAfter -ne 0) { for ($i = 0; $i -lt $LinesAfter; $i++) { Write-Host -Object "`n" -NoNewline } }  # Add empty line after
    }
    if ($Text.Count -and $LogFile) {
        # Save to file
        $TextToFile = ""
        for ($i = 0; $i -lt $Text.Length; $i++) {
            $TextToFile += $Text[$i]
        }
        $Saved = $false
        $Retry = 0
        Do {
            $Retry++
            try {
                if ($LogTime) {
                    "[$([datetime]::Now.ToString($DateTimeFormat))] $TextToFile" | Out-File -FilePath $LogFile -Encoding $Encoding -Append -ErrorAction Stop -WhatIf:$false
                } else {
                    "$TextToFile" | Out-File -FilePath $LogFile -Encoding $Encoding -Append -ErrorAction Stop -WhatIf:$false
                }
                $Saved = $true
            } catch {
                if ($Saved -eq $false -and $Retry -eq $LogRetry) {
                    Write-Warning "Write-Color - Couldn't write to log file $($_.Exception.Message). Tried ($Retry/$LogRetry))"
                } else {
                    Write-Warning "Write-Color - Couldn't write to log file $($_.Exception.Message). Retrying... ($Retry/$LogRetry)"
                }
            }
        } Until ($Saved -eq $true -or $Retry -ge $LogRetry)
    }
}

[PrzemyslawKlys]

This is great and something I was hoping to do one day. What I am wondering is - I assume the colors in 4bit or 8bit are much much more than what the default console provides? Maybe this should be expanded in a different way where people could choose ANSIColors separate to standard ones. I mean what you propose is ok, but maybe there should be "another" mode... or am I wrong with other colors? I never really dived into it?

[0-0-1-0-1-0-1-0]

This is great and something I was hoping to do one day. What I am wondering is - I assume the colors in 4bit or 8bit are much much more than what the default console provides? Maybe this should be expanded in a different way where people could choose ANSIColors separate to standard ones. I mean what you propose is ok, but maybe there should be "another" mode... or am I wrong with other colors? I never really dived into it?

There are more colors in 8bit mode than 4bit mode.

8bit list: https://gist.github.com/JBlond/2fea43a3049b38287e5e9cefc87b2124

4bit list: https://ss64.com/nt/syntax-ansi.html

You could in theory add all the possible colors into the ANSI colors variable, probably add an 8bit and 4bit flag (default to 4bit) and add 8bit codes into another variable.

The goal on my end was to try to match the colors to the existing Write-Host -Foreground/Background color names, that way your syntax stays the same just add -ANSI to the command to make it work in Azure Pipelines TTY output.

Your module is extremely helpful in making writing colors easy and I needed to solve the lack of color in our output logs in Azure DevOps Pipelines console.

NOTE: I shared this change with the ADO github project regarding color output so others can possibly take advantage of this in their CI/CD work.

microsoft/azure-pipelines-tasks#15473

[PrzemyslawKlys]

I was thinking that one could create 8 bit list of colors and apply them to foreground and background colors. It will be like 20+ colors. Then create hashtable that based on color choice + "type" => console, 4bit,8bit it would dumb it down.

So if there's Purple in 8bit, and then 4bit has no purple but bright magenta, and console has DarkRed it would basically choose respectively. so for every 8bit color, would match the same color 4 times in 4gbit and like 16 times in console..

Or maybe just different color sets altogether. ColorAnsi4, ColorAnsi8 or something

[0-0-1-0-1-0-1-0]

I was thinking that one could create 8 bit list of colors and apply them to foreground and background colors. It will be like 20+ colors. Then create hashtable that based on color choice + "type" => console, 4bit,8bit it would dumb it down.

So if there's Purple in 8bit, and then 4bit has no purple but bright magenta, and console has DarkRed it would basically choose respectively. so for every 8bit color, would match the same color 4 times in 4gbit and like 16 times in console..

Or maybe just different color sets altogether. ColorAnsi4, ColorAnsi8 or something

That would work honestly, as long as there was existing matching.

This would help the ADO Pipelines guys out a lot. I solved my immediate problem and finally have color for my what if analysis and PowerShell scripts to help our junior team identify key data in the build logs.

I hacked this together in order to allow us to simply modify all our ADO templates to add -ANSI at the end of the all the write-color statements and bam instant color logs.

I like your idea, this would work to provide 8bit and 4bit functionality, i would argue simply leaving the -ANSI switch and then working out the logic in the condition to cross match the hashtable. But you would still need a possible second switch to force use the 4bit colors even if a matching 8bit color name is found.

One thing to consider is the output logs might contain the ANSI codes with the escape characters, making them harder to parse.