Allow --reorder-code to optionally preserve code regions, even if it breaks the official style guide

[Rhxydos]

gdscript-formatter 0.14.0

Expected behavior: running the formatter with the --reorder-code flag should not add or remove code from a region.

Actual behavior: running the formatter with the --reorder-code flag can remove code from a region.

[NathanLovato]

Actually this is normal and it's not a case that you can fully solve because here what this means is that your region does not follow the official gdscript style guide code order.

The formatter needs to either occasionally break regions to order code following the official style guide or preserve regions and break the style guide.

The purpose of this formatter is to follow the official style guide so we do the former in the reorder command and leave it to people to then adjust their regions (the reorder command is meant to be used occasionally and manually - it does some heavy lifting and then if you want your own code order you can adjust to your taste).

I completely get that someone would like maybe more flexibility to adapt to their taste or use cases and I'm not against it. But if someone wants to make the formatter more configurable for their use case then I would need them/someone to contribute that. I'll leave this up as a feature request.

[torves]

I found the reordering behavior very frustrating. I thought it was a bug before finding this issue.

Expected behavior: Reorder command preserves code regions which follow the official gdscript style guide.
Actual behavior: Reorder command only preserves the first method in the region and moves other methods outside.

Example:

Original Code

#region Godot Hooks
func _ready() -> void:
	pass

func _physics_process(delta: float) -> void:
	pass

func _input(event: InputEvent) -> void:
	pass
#endregion

Reordered Code

#region Godot Hooks
func _ready() -> void:
	pass
#endregion

func _physics_process(delta: float) -> void:
	pass

func _input(event: InputEvent) -> void:
	pass

[NathanLovato]

In that case it's definitely a bug. When I have some free time I'll try to come up with a better solution than what we have now.

Do you have all the cases where reordering regions is problematic? Don't hesitate to share multiple code samples of what you get and what you'd ideally like to have.

[NathanLovato]

I patched your specific case at least @torves as that's a bug.

[torves]

First off, thanks for working so hard on making this awesome plugin! Really appreciate all the hard work everyone does here to improve Godot.

That was the only issue I've noticed - the reordering moving region blocks to only contain the first function within.
It also occurs with custom functions I have at the bottom of the script, but I believe this is the same underlying issue since the result is the same; just with custom methods instead of the Godot overrides.

My expected result when reordering code would be to preserve all code within region blocks to remain within the region block and move together - given the code within the region should be grouped together according to the official style guide.

Original Code

#region Interact Interface
func interact(player: Player) -> void:
	enter_ship(player)

func enter_interact(trigger: Area3D) -> void:
	trigger.show()

func exit_interact(trigger: Area3D) -> void:
	trigger.hide()
#endregion

#region Godot Hooks
# Code omitted...
#endregion

# More custom methods...

Reordered Code

#region Godot Hooks
# Code omitted...
#endregion

#region Interact Interface
func interact(player: Player) -> void:
	enter_ship(player)
#endregion

func enter_interact(trigger: Area3D) -> void:
	trigger.show()

func exit_interact(trigger: Area3D) -> void:
	trigger.hide()

# More custom methods...

Expected Result

#region Godot Hooks
# Code omitted...
#endregion

#region Interact Interface
func interact(player: Player) -> void:
	enter_ship(player)

func enter_interact(trigger: Area3D) -> void:
	trigger.show()

func exit_interact(trigger: Area3D) -> void:
	trigger.hide()
#endregion

# More custom methods...

[NathanLovato]

Could you please help me work out exactly how you would expect the regions formatting to work?

The official style guide does not cover this, so we have to define a superset of the style guide when it comes to reordering code regions procedurally.

The root issue is that code regions can contain any arbitrary code and be located anywhere in a script: you can mix built-in virtual methods, your own methods, properties, signals, and whatever want in a code region.

So then the question is, where and how should code regions be placed and how should they be reordered? Should they be moved and reordered following some rules or considered "frozen" in the file? Should the code inside a code region be reordered within the region's bounds, or should it be left entirely untouched?

I need to know in great detail what would feel most intuitive to users and how/why you use code regions, knowing that there's not really a definitive right answer there, but you have to make decisions.

I suppose that if you use code regions, it's sort of to break out of the style guide's code ordering rules and to make your own grouping of related code that you don't want to be reordered and scattered across the file. I.e. it would serve as "don't reorder this" fences.

Is that what you'd expect? How about positioning of the whole region within a much bigger file? Say you have a region in the middle of a file, and a bunch of code before and after the region that needs reordering. The region's place in the code will necessarily change as things move around it (for example, a lone _ready() method at the end of the file would move to the top and push the region down). Where would you expect the regions to end up? Top of the file, bottom, inserted between specific rule groups (e.g. after built-in virtual methods, before the rest of methods and inner classes)?

If you could share examples or scripts of a good size with where you'd expect the regions to end up after reordering that'd be particularly useful.