New formatting preset: OTBS with `else` on a new line

[o-l-a-v]

Edit: Blocked, see #2045 (comment).

Summary of the new feature

From the "There is no One True Brace Style" discussion it seems a lot of people, including me, likes OTBS with else on a new line.

• There is no One True Brace Style PoshCode/PowerShellPracticeAndStyle#177 (comment)
• There is no One True Brace Style PoshCode/PowerShellPracticeAndStyle#177 (comment)

In vscode-powershell one can't use a preset and override a setting it defines. Thus getting this code style in VSCode currently, one have to use:

{
  "powershell.codeFormatting.preset": "Custom"
}

then define all settings one by one.

• Code formatting preset - Add ability to override settings set by preset vscode-powershell#5109

Proposed technical implementation details (optional)

Add a new formatting preset for OTBS with else on a new line.

What is the latest version of PSScriptAnalyzer at the point of writing

v1.23.0

[bergmeister]

Isn't it Allman that you are looking for or is there something else in OTBS that you want to keep
The settings are defined here: https://github.com/PowerShell/PSScriptAnalyzer/tree/main/Engine/Settings
We could consider a second variation of OTBS

[o-l-a-v]

No, Allman opens curly braces and parantheses on new line:

• There is no One True Brace Style PoshCode/PowerShellPracticeAndStyle#177 (comment)

[o-l-a-v]

So far I've only come up with a name: OTPS.

• To mock the idea of One True PowerShell Style (even though there are none).
• We do ONE change from OTBS (else on new line), also in the name (change B with P).

[o-l-a-v]

I've learned that this is currently not possible. In fact, PSScriptAnalyzer can't actually fully format the presets that already exists, which this simple test shows:

PS > $Allman = @'
enum Color
{
    Black,
    White
}

function Test-Code
{
    [CmdletBinding()]
    param
    (
        [int] $ParameterOne
    )
    end
    {
        if (10 -gt $ParameterOne)
        {
            "Greater"
        }
        else
        {
            "Lesser"
        }
    }
}
'@

PS > Invoke-Formatter -ScriptDefinition $Allman -Settings 'CodeFormattingStroustrup'
enum Color {
    Black,
    White
}

function Test-Code {
    [CmdletBinding()]
    param
    (
        [int] $ParameterOne
    )
    end {
        if (10 -gt $ParameterOne) {
            "Greater"
        }
        else {
            "Lesser"
        }
    }
}

Vs. the expected output PoshCode/PowerShellPracticeAndStyle#177 (comment):

1. The opening curly bracket after function definition is not on a new line.
2. Opening paranthese after param should be on the same line.

The bracket rules are context unaware (does not differentiate on function {} and if () {} else {}. And PSScriptAnalyzer does not touch param().

This issue is blocked until the PSScriptAnalyzer formatting engine gets more formatting features.

• 2020-05-06: Write new formatting engine #1480
• 2020-16-16: PSSA 2.0 Roadmap #1528
• 2020-07-22: New formatting API #1550
• 2025-04-15: Formatting misses certain keywords (unary operators, 'until') #2095

[bergmeister]

I've learned that this is currently not possible. In fact, PSScriptAnalyzer can't actually fully format the presets that already exists, which this simple test shows:

PS > $Allman = @'
enum Color
{
Black,
White
}

function Test-Code
{
[CmdletBinding()]
param
(
[int] $ParameterOne
)
end
{
if (10 -gt $ParameterOne)
{
"Greater"
}
else
{
"Lesser"
}
}
}
'@

PS > Invoke-Formatter -ScriptDefinition $Allman -Settings 'CodeFormattingStroustrup'
enum Color {
Black,
White
}

function Test-Code {
[CmdletBinding()]
param
(
[int] $ParameterOne
)
end {
if (10 -gt $ParameterOne) {
"Greater"
}
else {
"Lesser"
}
}
}
Vs the expected output PoshCode/PowerShellPracticeAndStyle#177 (comment):

1. The opening curly bracket after function definition is not on a new line.
2. Opening paranthese after param should be on the same line.

The bracket rules are context unaware (does not differentiate on function {} and if () {} else {}. And PSScriptAnalyzer does not touch param().

This issue is blocked until the PSScriptAnalyzer formatting engine gets more formatting features.

• 2020-05-06: Write new formatting engine #1480
• 2020-16-16: PSSA 2.0 Roadmap #1528
• 2020-07-22: New formatting API #1550
• 2025-04-15: Formatting misses certain keywords (unary operators, 'until') #2095

There are certainly limitations, my high level understanding from when I last looked at formatting rules is that they just format code from scriptblocks, hence why the wrapped function brace and Param parenthesis itself are not part of formatting (at least I think so, this is just from memory and could be wrong). The way the formatting rules work (token based and not AST) has always made them susceptible to not being to capture 100% of cases. There is no capacity from team for a big rewrite so my approach (and also with the help of other contrubutors) is to fix more and more of the not or wrongly covered cases or fix where it formats things wrong. Essentially, most of the logic is brace counting and when I implemented the multi-pipeline formatting rule I just got a small idea of how complex generic PowerShell can be and the cases presenting themselves for a watertight solution.

My suggestion is to try to tackle the things that block your rule from working and first have your rule/config working just for simple scenario (one level of nesting/indentation) and from then refine logic further. It's going to be hard and you might have to touch existing logic to tweak it, I'd prefer if we didn't as we've seen some regression but if you can explain in detail why it's better to change logic and cover with test cases and cover it with feature flag (so we can always revert to old mode as issues often only arises post-release), then happy to let you have a go.

EDIT: Just seen this so something big might be coming... PowerShell/vscode-powershell#5410