Creating Windows PowerShell -f format operator

My mission on this page is to explain the basics of PowerShell's -f format operator. We use this operator, -f, to set the column widths in the output. Another way of looking at -f is to control the tab alignment. It has to be said that format-Table is the easiest method of controlling the output display; however, there are occasions where only -f can achieve the desired result.

Topics for PowerShell -f Format Operator

Example 1: The Format Problem

I have chosen PowerShell's eventlog command to illustrate the formatting problem. What I would like is for the data in the three fields to align precisely in columns.

In the screenshot below, data is difficult to read (even allowing for it being out of focus). Actually, it could be worse, the only reason there is a space between ACEEventLog and OverwriteOlder is because I added the clumsy command: + " ". See code below.

# Powershell testbed for the -f format command
$EventVwr = get-EventLog -list
foreach ($Log in $EventVwr) {
$Log.log + " " + $Log.OverflowAction + " " + $Log.MaximumKilobytes
}

Example 2: Columns Aligned - Desired Format

# Powershell testbed. Example of the -f format command
$EventVwr = get-EventLog -list
foreach ($Log in $EventVwr) {
"{0,-28} {1,-20} {2,8}" -f `
$Log.log, $Log.OverflowAction, $Log.MaximumKilobytes
}

Guy's Suck-it-and-see Explanation

What I would like to do here is explain how the -f format operator works. I will give you examples to show every nuance, and every punctuation character. However, this is a practical rather than a technical explanation.

Let me begin with a reminder of the context. We are employing the command: get-Eventlog -list, as a vehicle to experiment with the -f format operator. This script uses the standard loop technique, and what we are particularly interested in is the alignment of the three properties:
$Log.log, $Log.OverflowAction, and $Log.MaximumKilobytes

In Example 2 (above), we achieved the regular alignment with this format operator: "{0,-28} {1,-20} {2,8}" -f

Point 1: Each individual element in the output is enclosed by a set of braces {1,-20}. The first number, zero, one or two, refers to the column in the output (first, second or third). If you study example 2, the first item, $Log.log, is referenced by zero in the first set of braces {0,-28}

Following the comma, comes the second number (-20 or 8), this determines the padding. Providing this number is larger than the number of letters in the longest data element, the columns align nicely.

Point 2: Minus, and I emphasise minus, -28 not only pads the element, but also makes sure that the first letters of each element line up vertically. Actually the best way to see what I mean is try the script WITHOUT the minus. The reason that I am hesitating to use the words left and right is because when I read a technical article on the subject, the technical author referred to left and right in the opposite way to my logic.

Point 3: Speech marks. In this example there are three separate elements enclosed in one set of speech marks :"{0,-28} {1,-20} {2,8}".

Point 4: -f this comes at the end of the formatting instruction, and is outside the speech marks. Also be aware of the logic whereby the -f format statement comes before the actual data.

Point 5: Naturally, the number of sets of braces needs to match the number of elements you want to show in the output, three elements, thee sets of braces. Once again, make my day and try an experiment, for example remove the second or third element, try just: "{0,-28}" -f

Point 6: For the last element, {2,8}, I deliberately chose a positive number, the result is that the numbers align under the smallest digit, which makes the numbers easier to compare.

More Challenges:

I found that the best way to understand the -f formatting was to experiment with different settings. To see what I mean, take example 2 as your test-bed and substitute the commands below for "{0,-28} {1,-20} {2,8}" -f `. Before I go any further, the tiny backtick symbol ` tells PowerShell to wrap the command to the next line. I also positioned the backtick to emphasise the split between the formatting commands and the data. Try these:

It almost goes without saying, that while I have used, get-Eventlog -list, to illustrate PowerShell's -f format operator, there innumerable other PowerShell commands that benefit from this control over the display of your data. You could even try this if you don't have another 'vehicle' for testing:

Even more control over -f formatting

While I chose to use only decimal numbers for simple formatting, PowerShell offers even more control, here are examples:

"{0:x}" This is the simplest hex format. If the FIRST data element returned 500, what you would see displayed is:
1f4

Deliberate Mistake: "0x{0:X}" -f "500" If you enclose the 500 in speech marks, it does not produce the desired hex conversion.

Another Deliberate Mistake: "0x{0,X}" -f 500. That comma is incorrect, it should be a colon. My point is that you have to be so careful with each and every punctuation mark.

Summary of –f Format

Appending | format-Table is the standard method of formatting PowerShell’s output, however, there are situations where –f gives you greater control over the display of your data.

Windows PowerShell -f Format Operator

Introduction to Windows PowerShell -f Format