[NEW FEATURE] Free flags

[Mqzn]

Free flags

In Imperat, a flag is usually assigned to an index/position as a parameter, making it easier for the
S.U.R to detect and resolve.

A free flag is a flag that can be used in the command syntax ANYWHERE
(not assigned to a certain position).

Current Methodology

Honestly, it's easy to implement, but the tab completion will most probably not tab complete the free flags
unless you're tab completing while exceeding the depth/length of the raw arguments.

The idea I have in my mind is to add a constructor parameter,
with the value boolean representing whether the flag is Free or not.
And for @Flag annotation, we should add a new member free=false/true.

Then when the part of adding parameters to their list comes, we interfere and check if it's a free flag,
if yes we add it to a separate data-structure/collection else we add it normally to the parameters list.
(all of that is happening when creating a new instance of CommandUsage

Possible future issue

Here are some predicted issues that might face us while trying to implement this feature correctly.

Position overlap with normal flags

If a command usage has 2 flags, where one of them is free while the other is not;
and the user uses the free flag at the position of the non-free one.

Solution for correct Tree/Graph context matching

At SAME DEPTH, We check if matching a parameter flag AND the current raw is a flag (by checking if it has the pattern of a flag) ,
IF yes -> then it's not a free flag;
ELSE IF the current raw is a matching flag AND the raw flag used resembles a registered free flag 💯 (Meaning that the current parameter node is not a flag) -> a free flag being used -> we increment the depth and re-traverse/re-visit the SAME CURRENT parameter node.

Solution for correct S.U.R resolving:-

We should check if the current parameter flag is matching the raw, IF not WHILE ALSO HAVING A FLAG BEING USED, then we collect the used free flag AND SHIFT the raw pointer while keeping the parameter pointer.

Solution for Tab-Completion:-

Note: this will need some modification of the current tab-completion algorithm, to have 2 depth pointers instead of only 1 depth pointer; First for the raw input, Second for the parameter node depth.

Since we are not going to autocomplete free-flags directly, let's at-least use them strategically well.
1- We can add them automatically as a part of a default/global suggestion resolver.
2- During collecting node suggestions in CommandTree, we should check :-

• If the previous argument is a free flag, if yes -> then we shift the raw-depth to the right, while keeping the parameter-depth intact.