Consider creating a conceptual help topic for calculated properties

[mklement0]

Calculated properties can be used with many cmdlets (Select-Object, Format-*, Sort-Object, Group-Object, ConvertTo-Html, possibly others, and, since v6.1, Measure-Object).

They're an important concept, yet only mentioned tersely in the context of the -Property parameter description.

I think a dedicated conceptual topic that the cmdlet topics can link to would help, along the lines of about_Calculated_Properties.

Things that should be covered:

• The hashtable keys need not be spelled out, as long as the specified name prefix is unambiguous, so that n can be used in lieu of Name, and e in lieu of Expression.

• You may specify the expression script block directly as an argument (as opposed to specifying it as the Expression entry of an enclosing hashtable), e.g., '1', '10', '2' | Sort-Object { [int] $_ }, which is convenient for cmdlets that do not require (or support) naming a property via the Name key, such as Sort-Object, Group-Object and Measure-Object

  • In fact, Measure-Object, unlike the other cmdlets, doesn't support passing a hashtable at all, and only accepts a script block, because its -Property parameter is psropertyexpression[] typed, not [object[]] typed.
  • Using this technique with cmdlets that do support a Name key for naming the property will automatically use the script block's stringified content as the name.

• Pipeline logic is applied to the output from Expression script blocks, which means that outputting a single-element array will cause that array to be unwrapped.

• Errors inside expression script blocks are quietly ignored.

  • Except in Sort-Object, where statement- and script-terminating errors are output, but they do not terminate the statement.

• Expression script blocks run in child scopes (meaning that the caller's variables cannot be directly modified).

[mklement0]

@matt9ucci, it would help if you clarified your thumbs-down vote; which aspect(s) of the proposal are you objecting to?

• The information detailed in the original post is not currently documented, as far as I'm aware. Do you think it shouldn't be documented? If so, why?

• Are you specifically objecting to creating a dedicated topic for this issue? If so, why, given that the information is clearly a cross-cmdlet concern?

[doctordns]

I teach PowerShell around the globe, and know that hash-table caculated properties are both an important aspect but also quite complex and confusing.

1. Yes Please for a conceptual help file on this topic. the OP has some key contents.
2. PLEASE: any examples should use the full hash key name, not the abbreviation. So NAME= not N=, etc.
3. Please consider having at least one example for every use case.
4. Consider updating about_hashtables to point to this new help text (along the lines of "hash tables can be used to calculate values, see about_.xxx for more information).

[matt9ucci]

@mklement0 The former PowerShell-Docs admin says:

The beauty of being an open sourced community is that everyone can make suggestions; but, most important everyone can make contributions.

I would like you to consider writing real documents and PRs before opening issues. For example, Format-Custom, Format-Table, and Select-Object in PowerShell v3.0 to v6.1. They look similar but have different key sets.

After the PRs are successfully approved, you will be easily able to push the another PR of the conceptual doc and just say "Hey, I wrote a new conceptual doc. It is a copy of Format-Custom and some additional conceptual descriptions."

I think such combination, real documents and progressive changes, is the most effective solution for smooth discussion and document improvement.

[mklement0]

Amen to that, @doctordns.

Re 2:
It's definitely worth recommending that full key names be used in scripts, for readability and longterm stability of the code, similar to how aliases should be avoided in scripts.

But as a part of PowerShell's "elastic syntax" for ad-hoc, command-line use, it's worth documenting the l/n and e shortcuts, not least because they're common and convenient.

That said, it would help the stability problem if the l/n and e were locked in as aliases of label / name and expression, so that even introducing keys later that start with the same letters don't break old code - see PowerShell/PowerShell#8429

[doctordns]

I see two separate issues:

1. Locking in certain key abbreviations as formal aliases. I am not fully convinced this is helpful. So long as key names are unambiguous in a given hash table, I can't see the value of a formal alias.
2. How to document the use of hash tables in calculating values for commands. A conceptual help about_calculated properties would be useful.

Re number 2, such a document would be along the lines of:
a) What, in general, is a calculated property and why use one.
b) how do you create calculated properties (ie using hash tables with pre-defined key names)
c) How to use calculated properties
d) Cmdlet specific valid hashtable key names
e) Examples, examples, examples.

[mklement0]

@matt9ucci:

everyone can make contributions.

Proposing a new topic is a contribution.

I would like you to consider writing real documents and PRs before opening issues.

How is that related to whether this proposal has merit?

They look similar but have different key sets.

I don't understand what point you're trying to make: Because they have different key sets they're not fundamentally the same thing? It's too much wok? See table below.

you will be easily able to push the another PR of the conceptual doc

Again, how is who implements the proposal related to whether it has merit?

progressive changes

Crucial conceptual information missing from the documentation does not call for progressive changes.

---

Overview of which cmdlets support what key sets

Note: The information below comes from inspecting SetEntries() calls in the current source code. It matches the individual help topics, except for Format-List - see #3391
I don't know whether earlier PowerShell versions supported fewer keys.

Cmdlet	Supported Keys	Comment
Select-Object	name / label, expression
Format-Table	name / label, expression, formatstring, width, alignment	alignment must be 'left' or 'center' or 'right', width must be an integer greater than 0.
Format-List	name / label, expression, formatstring	The same set applies to the -GroupBy properties for all Format-* cmdlets.
Format-Wide	expression, formatstring
Format-Custom	expression, depth
Group-Object	expression
Sort-Object	expression, ascending / descending
ConvertTo-Html	label, expression, width, alignment	Note that alias name for label is currently not supported, and width currently has to be a string(!), and specifying an [int] - the same way that Format-Table requires - is not supported. These issues will go away when PowerShell/PowerShell#8426 is published.
Compare-Object	expression	This is unfortunate, because supporting name / label would make sense too, given that the verbatim string content of the expression script block becomes a property name of the output objects - see PowerShell/PowerShell#11607
Measure-Command	none, only direct passing of script block	This is an unfortunate inconsistency. While it's simpler anyway to just pass a script block directly, using a hashtable with key Expression should also be supported, as with Group-Object.

[mklement0]

@doctordns: Fully agreed re 2.

I am not fully convinced this is helpful. So long as key names are unambiguous in a given hash table, I can't see the value of a formal alias.

The problem is longterm code stability: with elastic syntax, making your code work now doesn't mean that it will continue to work in future PowerShell versions, because the introduction of new key names could make a previously unambiguous name prefix ambiguous, causing the command to break.

For instance, say you l for label in your calculated property definitions, which currently works fine.
If a key such as length is introduced in the future, your old code that uses just l breaks, because l now matches two supported keys.

The proposal in PowerShell/PowerShell#8429 would take the keys out of the realm of elastic syntax - which is still useful in the context of parameter names for ad-hoc, one-off use - and guarantee that l will always refer to label, e to expression, ...

[doctordns]

I suspect changes in the hash table keys supported calculated properties are pretty unlikely, but never say never. In the case that such a change was seriously to be suggested, that change would have to allow for the fact that it could be a breaking change and the community could take a view. Of course, those following the recommended best practice continue to be unaffected - the only people affected would be those using short forms typically from the command line.

[mklement0]

@doctordns:

It's not a breaking change, because there is currently no ambiguity: no two keys for a given cmdlet start with the same letter; there is potential for cross-cmdlet ambiguity between alignment / ascending and depth / descending, which is why I proposed asc and desc for the latter two (though the specific names are open to discussion).

The proposed change is fully backward-compatible; its value is in providing official short aliases that can be used in a future-proof manner, whereas the current implementation bears the risk of breaking old code in the future.