Rename composite rules

[henriquemoody]

Related to the discussion in #1578 (comment)

[alganet]

Regarding the new names (continuing the discussion here).

If we could use just v::and, v::or, v::xor, etc it would be better, but there is a reserved word issue here:

https://www.php.net/manual/en/reserved.keywords.php

The previous names allof and oneof that I have chosen previously came from RDF terminology:

https://www.w3.org/2004/12/q/doc/rdf-rulesets.html

They also are present in JSON Schema. I'm actually fond of them, but the conflict with the All rule is an issue for that naming convention.

Since we drifted a lot from RDF since 0.9/1.0, I'm willing to part with AllOf/OneOf, but I think we should still latch to an existing estabilished convention (even if it's not an official standard). The "Logic" prefix comes from that, since lots of codebases use it (especially parsers who need to circumvent and and or being reserved words):

https://github.com/search?q=logicand+logicor&type=code

The names groupedAnd and groupedOr make sense, and there is a precedence:

https://github.com/search?q=groupedand+groupedor&type=code

However, it seems way less common than the Logic prefix.

Another option is using the op prefix, for "operator": opAnd, opOr and so on. These are also very common:

https://github.com/search?q=opand+opor&type=code
https://github.com/search?q=op_and+op_or&type=code

[henriquemoody]

We could use v::and, v::or, v::xor, as method names, but not as rule names. We could solve that by introducing an Alias transformer that we already had. The issue is the inconsistency.

My concern with the logic* is that it doesn't express that there's a group of rules to be accounted for. Form the links your sent, the logic* ones didn't seem linked to groups.

I'm not against the logic*, though.

[alganet]

The examples searches I linked to, as I mentioned, are mostly from parsers that have to circumvent reserved words. Those parsers would like to use raw and and or, but those are reserved, so they used LogicAnd and LogicOr. The convention in that case is how to circumvent reserved words, not how to group things.

If I do v::a()->logicAnd()->b(), someone might be inclined to believe that I'm saying A && B, but I'm actually saying A && () && B, so yes, there is a world in which this can cause confusion.

In my original design, the v:: chained DSL was almost inert, no name transformations. This is not true anymore, we do a lot of naming inference there, so the alias is now a valid option as well. It does introduce an inconsistency though, but that's fine, there is a lof of v::somethingFooBar viable methods that does not have a Validators\SomethingFooBar concrete class.

If you feel strongly about groupedAnd and groupedOr, go with it! We could also consider suffixes "andGroup", "orGroup".

[henriquemoody]

I don't feel strongly about the "grouped*" name, in fact I think they're all fine. Which one would you go for?

[alganet]

I would go for the Logic prefix:

• AllOf -> LogicAnd
• Circuit -> LogicOr
• OneOf -> LogicXor
• NoneOf -> LogicNor
• When -> LogicCond
• AnyOf -> [remove]

I noticed that Circuit is very similar to AnyOf already. The difference being that Circuit stops instead of mapping to all inner validators. This is more closely related to what foo() || bar() does (it will stop before invoking bar if foo fails).

Actually, original OneOf was very similar to what Circuit is today, iterating on each validator instead of using array_map:

https://github.com/Respect/Validation/blob/0.9.8/library/Rules/OneOf.php

I can't see a reason for us having the current implementation of AnyOf that runs all validators inside but accepts any of them passing. We should really just have the version that stops, like the original OneOf and the current Circuit.

[henriquemoody]

There's quite a difference between how AnyOf and Circuit displays their message, while Circuit has no message, AnyOf will return a result with all failing results. I think it's a different category from the *Of validators.

About the When, how about we just call it Ternary?

[alganet]

I initially thought of When as ternary. However, ternary implies a mandatory else portion, which we don't require, so Cond makes more sense.

It seems that AnyOf is OneOfv0.9 in ->assert() mode, and Circuit is OneOfv0.9 in ->check() mode. So, in a sense, they have the same origin. Before, this choice was at the end of the chain (assert vs check), now it's inside the chain.

I agree it doesn't belong to a Logic prefix. I don't have a good name for it though 😅