Reminder to Self: Using text output as a programming contract is contracting for future failure…

PowerShell Team Blog - Text Output Is Not a Contract

“In PS V1, this is what you get for GET-COMMAND -SYNTAX

PS> Get-Command Get-Process -Syntax
Get-Process [[-Name] <String[]>] [-ComputerName <String[]>] [-Module] [-FileVersionInfo] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]
Get-Process -Id <Int32[]> [-ComputerName <String[]>] [-Module] [-FileVersionInfo] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]
Get-Process [-ComputerName <String[]>] [-Module] [-FileVersionInfo] -InputObject <Process[]> [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]

I look at that and a little bit of vomit comes up into my mouth.  I've been experimenting with my own radically different version but that probably won't ship in V2 and we'd like V2 to be better.  I mentioned that if we just put a newline between the parametersets and got rid of the ubiquitous parameters - we would be TONS ahead.  This is what it would look like:

…

MUCH better right?  As we discussed this, someone pointed out that this change would break any scripts that parsed the text output for the V1 version.  At first I looked at the person as though they had a rat's tail hanging out of their mouth (thinking - Get-Command gives you a structured object - why would you render it to text and then parse it?!!!).  Then I realized that we hadn't actually stated what I think is obvious so now I'll state it:

In PowerShell - TEXT OUTPUT IS NOT A CONTRACT.

In UNIX, text output is effectively a programming contract because that is what the whole system is built upon.  One command outputs text and other programs know what to expect so they parse the text to get the appropriate data elements so that they can code against it. …

…

That is the world of TEXT parsing.  In PowerShell - we provide an object-based world where you don't have to parse the text to get the properties that you want - you just ask for property and you get it - no fuss, no muss.  Given that - in Powershell TEXT OUTPUT IS NOT A CONTRACT.  Said aother way -
We reserve the right to radically change our text rendering to improve our customer experience.
(God knows we have some improvements to make. :-) )

…”

The title and content of this post was one that I wanted to call out and re-empathize. Using text output as a contract is contracting for future failure…