A framework for option priority

[micheleCTDE]

Hi devs (and apologies for the long post),
I have being toying with uncrustify for about 9 months, on and off. At the beginning I spent a good couple of weeks studying all the various options and test them out and later I have being trying to get uncrustify to behave as we need it on our project.
One of the problems I have run into, is that sometimes different options affect the same part of the source code and conflicts among the options arise. For example I would like to use option A and option B, but option B has priority over option A while instead I would like option A to have priority over B. Sometimes the priority is clearly mentioned in the option description (defaults.cfg file), but others it seems to be hidden in the code.
I have been tinkering with how we could introduce option priority in uncrustify and here is a proposal for an option priority framework, to be progressively implemented in the code.

Key design principles that I have consider are:

1. do not alter default behavior if priority is not specified/implemented
2. allow for incremental development of the framework, starting with zero options supported and progressively add and extend the functionality.

Basic concept

The basic idea is to assign to each option a priority integer value. By default this will be zero.
The user can increase (positive value) or decrease (negative value) the priority of an option.
A function "bool options::check_priority()" will be used to check the option priority and return "true" if this is the option with the highest priority among options affecting the same part of the code.
The various functions used in the code to check whether a specific option is set (true or != IARF_IGNORE) will need to call the above function to also check if the option has not been masked by another option with higher priotity. For example, in the function "options::option_A()" we will add a call to "options::check_priority(option_A)" and its result will be combined with the value of the option: basically if "options::check_priority(option_A)" returns "false", the value of "options::option_A()" will be either "false" or "IARF_IGNORE".
The various functions used in the code to check whether a specific option is set (true or != IARF_IGNORE) will need to be combined with the above function to also check if the option has not been masked by another option with higher priotity, where there is overlapping between options. For example there could be two partially overlapping options (A and B):

• where only option A or only option B is applicable, there is no need for checking the priority
• where both options are applicable, a call to "options::check_priority()" is required. In case two options have the same priority value, the current (already coded and implicit) priority will define the option order.

Incremental implementation

I will explain this with a progressive example.

1. Start.
   "options::check_priority()" is pretty much a dummy function and it is not called in any place in the code. The structure will be an empty "switch()" statement with only a "default" case where it returns "true". No options has any priority assigned yet.
2. Add code stub for priority for option A (Note: at this stage the user still can't specify a priority for this option).
   Since this is the first option with assigned priority, this is a very simple task. In the "switch()" inside "options::check_priority()" we will add a "case" for "option A" and this will simply return "true".
   In the function "options::option_A()" we add a call to "options::check_priority(option_A)" and combine its result with the value of the option.
3. Add code stub for priority for option B, where option B does not work on the same part of the source code of option A.
   Since option A and B are independent and don't interfere with each other, this is also easy and basically the same process of item 2.
4. Repeat point 3. for more options as long as they are all independent of each other.
   Again, at this stage there are no changes from a user perspective, it has all been only preparation work
5. Add priority for option C, which overlaps with option A.
   Option A and C influence the same part of the source code to format, so we need to provide the user a way to specify a priority if he wishes to do so.
   We need to introduce two new parameters called respectively "option_A_priority" and "option_C_priority" in "defaults.cfg". By default, their value is 0. In "defaults.cfg" we will also need to indicate which options overlaps, so we will mention that option_A and option_C acts on the same part of the code and that their priority can be changed by using the new "priority" parameters.
   In "options::check_priority()", in the "switch case" for "option_A" we need to compare the priority of option_A and option_C and return "true/false" based on their value. Same goes for option_C, which will have its "case" as well. For example, if in the current uncrustify code option A has already higher implicit priority than option C, we will have something like this:

• for option_A: return "true" if priority(A) >= priority(C), "false" if priority(A) < priority(C)
• for option_C: return "false" if priority(A) >= priority(C), "true" if priority(A) < priority(C)

6. Repeat the process for other options as long as they don't influence option_A not option_C
7. If another option_D influence option_A/C, we will need to follow the above steps but in addition to that we will need to revisit the "switch case" of option_A and option_C to incorporate the comparison with option_D as well.

The process continues as more and more options are taken into consideration.
When a new option is added to uncrustify's functionality, we will need to see if it overlaps with other options and eventually follow the steps above to manage its priority.

Ok, that's it. It was a long post, but I will be happy to hear what you think about this proposal and discuss further about it.

[guy-maurel]

I wish a real example

[micheleCTDE]

Will prepare a proof-of-concept at some point. Thanks for supporting the idea.

[micheleCTDE]

I have thought more about this and I now think the result may not be worth the effort.
Only a subset of options conflict with each others, so when that is the case it is probably much simpler and quicker to add a new option to uncrustify to decouple the conflicting options and control the behavior where they previously overlap themself.
For example, if option A and B overlap, it would be easier to add option C for the overlapping part, while option A and B would continue to control their respective unoverlapped parts.
What do you think?