Document and unify the order in which GAP evaluates function arguments and options

[fingolfin]

Previously, this was what the immediate interpreter did, but not
what the executor did; the latter always evaluated options first.

Fixes #4631

[wilfwilson]

The kernel changes seem to be doing what you want, from what I can tell.

I'm a bit worried that the (thankfully now consistent) order of things happening is not documented. As far as I can tell, the closest documentation that address this behaviour is 4.11-2 Function Call With Options https://www.gap-system.org/Manuals/doc/ref/chap4.html#X867D54987EF86D1D which includes:

The following example shows a call to Size (30.4-6) passing the options hard (with the value true) and tcselection (with the string "external" as value).

gap> Size( fpgrp : hard, tcselection := "external" );

Options supplied with function calls in this way are passed down using the global options stack described in chapter 8, so that the call above is exactly equivalent to

gap> PushOptions( rec( hard := true, tcselection := "external") );
gap> Size( fpgrp );
gap> PopOptions( );

This example doesn't address the topic at issue here, but a sentence could be added, and this example modified (perhaps by constructing fpgrp in the one-liner too), to show the order in which arguments are evaluated versus options set.

[fingolfin]

That chapter of the reference manual also says this about evaluation order:

However, GAP does not make any guarantee about the order in which the arguments are evaluated. They might be evaluated left to right, right to left, or in any other order, but each argument is evaluated once

Based on this, one may argue that the "bug" this issue "fixes" isn't a bug at all -- it's a legitimate variation in otherwise undefined behavior.

However, I am not a fan of this, or of that sentence. GAP performs things in a fixed order (and typically that order is left-to-right, depth first), and it can be beneficial to users to be able to rely on that. Yes, we might in theory want to implement some kind of optimizations where it might be useful to be able to reorder these evaluations.... but does it seem likely we'll ever do this? I personally don't think so (but perhaps @ChrisJefferson disagrees?)

[ChrisJefferson]

I don't think any optimisations would be worth the subtle bugs which would be introduced -- I think that both for GAP, and other programming languages, but GAP is the one where we can fix the order ourselves :)

[fingolfin]

Good! I'll augment the documentation

[fingolfin]

I've added a commit updating the documentation, please check it.

Editing this code made me realize that our documentation for variable length argument lists could be better, so I'll work on that next.

[fingolfin]

Note that this conflicts with PR #4547 -- it'd be much easier for me if that PR was merged first, then I could easily update the PR here to match

[wilfwilson]

Thank you for the documentation changes, and I'm happy to also approve the code codes.

I'll review #4547 now and see about approving/merging that before this one 🙂

[wilfwilson]

#4547 is merged so it's time to rebase this when you have a chance.