Allow local variables in test files

[ChrisJefferson]

This is an experiment in allowing local variables to be declared in test files.

The current (horrible) notation is to write:

#@local <list of variables to be local> as the first line of the test. If this line is present, any other introduced variables will produce a warning, as if we were in a function.

There are two reasons to do this:

1. You don't pollute the global name space, local names do not exist at the end of the test.

2. (More importantly) you can run the test in two threads simultaniously, as the two local contexts will not interfere.

This will fail, to demonstrate the new warnings being produced.

UPDATEUPDATE:

This PR also now features #@if, #@else, #@endif, which provides an easy way to skip parts of a given test, or give different returns for a given test. This is now used to make the 32-bit, 64-bit and unix tests only run on the correct platforms.

[codecov]

Codecov Report

Merging #1633 into master will increase coverage by 0.02%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #1633      +/-   ##
==========================================
+ Coverage   85.13%   85.15%   +0.02%     
==========================================
  Files         110      110              
  Lines       56964    56964              
==========================================
+ Hits        48494    48506      +12     
+ Misses       8470     8458      -12

Impacted Files	Coverage Δ
src/vars.c	92.69% <100%> (ø)	⬆️
src/streams.c	71.06% <100%> (+0.12%)	⬆️
src/stats.c	95.07% <0%> (-0.21%)	⬇️
src/exprs.c	97.37% <0%> (-0.18%)	⬇️
src/gap.c	83.81% <0%> (-0.1%)	⬇️
src/intrprtr.c	98.88% <0%> (+0.22%)	⬆️
src/read.c	97.01% <0%> (+0.72%)	⬆️
src/iostream.c	63.49% <0%> (+1.14%)	⬆️

[olexandr-konovalov]

@ChrisJefferson you've asked for further suggestions - what about making it possible to specify whether the test file or a separate example should just run without entering a break loop or crashing (so diffs are permitted)?

[ChrisJefferson]

We could certainly do that

[fingolfin]

I wonder if we can also write a tool which automatically generates such a "local" line for an existing .tst file. That would greatly help in converting existing test files.
The idea is that in this mode, instead of reporting undefined locals, we add them to a list (and swallow the warning); then at the end of the .tst file, use that list to generate the comment. Perhaps we can even add them to the LVAR on the fly?

Of course for this won't work perfect, because a few tests may want to define a global (to test it), but those should be rare exceptions.

[ChrisJefferson]

I'm sure we could -- there is a "nice" way of doing that (hooking into the access to undefined variable, and recording when it occurs), and a "nasty" way (just look through the output for the error we know we will see), and either way stick a new local line at the top of the file.

[fingolfin]

Perhaps rebase and squash the fixup commits?

[olexandr-konovalov]

@ChrisJefferson ping?

[ChrisJefferson]

Back from the depths of time, I believe all issues are fixed and this PR is ready to merge.

[ChrisJefferson]

All changes made (I think), except the #@exec -> #@Local, which I'm happy to discuss.

[fingolfin]

When you write #@exec -> #@Local, do you mean #@exec -> #@global? Otherwise, I don't follow...

In case you do mean that: Well, in the end, I can certainly accept either; and I don't want to hold up the PR with bikeshedding; it's just that once a feature is out there, it is difficult to take it back. Since #@global would be much more limited in scope, I think it'd be very easy to document and easy to understand and use correctly; whereas I am afraid that I don't fully understand all potential ramifications of #@exec, and so I worry about abuse... Like, one thing I am concerned about is that apparently all #@exec in the whole .tst file are collected and executed at once before everything else in the script. So I could add #@exec lines at the bottom, and they'd be executed first thing, which I find highly surprising. I guess I'd be less concerned if @#exec was executed in lock step with other commands, i.e., only at the point they appear in the file. Or alternatively, if they were restricted to only appear at the top of the file, before any non-comment non-empty line.

OTOH, the added power of #@exec might very well be a boon in ways I cannot foresee yet...

Would be interesting to know what others thinks, too? E.g. @markuspf @stevelinton @wilfwilson etc.

[ChrisJefferson]

One problem with #@global is that we wouldn't be able to define the value the variable has (we would have to choose a default, 0 perhaps). If we let people write a value (by parsing/splitting #@global x := value for example, then we are back to having to either execute the whole statement, or reading and evaluating value, both of which don't really limit the power.

[ChrisJefferson]

This isn't documented, but both #@Local and #@exec must occur before any gap statements (this wasn't particularly planned, but it is how the code works and seems like a sensible restriction).

[ChrisJefferson]

I've added a brief bit to the docs saying #@Local and #@exec must come before any tests.

[fingolfin]

BTW, is there a reason you keep writing #@Local (with capital L) in comments and commit messages, while it is #@Local in the actual code and tests (and you seem to never capitalize #@exec)

[fingolfin]

Now that you clarified that #@exec can only be used at the top, I am happy enough :-)

[ChrisJefferson]

It's github #@Local #@exec are both lower-case when I write them -- github is linking them to the Local organisation (which is capitalised) and the exec organisation (which isn't)

[wilfwilson]

I've had a little look, I like the new features, and I don't have any objections.

[markuspf]

Could you rebase again so we can merge this?