Add support for GAP (www.gap-system.org)

[ChrisJefferson]

This adds support for the "GAP" programming language.

I'm going to try using this over the next few days, so may improve it, but thought I would put it here for any initial comments.

One thing I wasn't completely sure on is how many (and how much it matters?) newlines I need before + after the delims.

[ChrisJefferson]

If you are curious, GAP can be used as part of Sagemath (and also as a Julia library too!) but is also frequently used as a seperate project.

Known issues: GAP has automatic line wrapping. I made lines 9999 characters long so this doesn't interact with codebraid's output commands.

[gpoore]

I've looked over this and have some comments now. I'll go over it again a final time in more detail to double-check everything once you are ready to merge.

• This looks very thorough, with updates to code plus documentation and examples. That will make this much easier to merge. Thanks!

• In run_template, you have LogTo("/home/caj/out.txt");;. I'm guessing this is intended for debugging but not the final version?

• For the delims printed in chunk_wrapper and elsewhere, you need exactly one leading newline and one trailing newline. These guarantee that delims are on lines by themselves, even if whatever preceded them didn't end with a newline. This helps in identifying errors that are triggered by invalid user code just before/after the delims are printed.

• In chunk_wrapper, there's ();; # This should do nothing, but ensures parser errors in code do not stop the 'Print' below. My guess is that this isn't necessary, but depending on how GAP works it may be needed. If you've encountered particular situations where it helps, can you provide an example? Codebraid parses code execution output under the assumption that errors may prevent some or all delimiters from being printed, so usually there shouldn't need to be any special attempts to ensure that delimiters get printed. If a missing delimiter causes issues, that may indicate a bug in Codebraid. I suppose one exception would be if code is expected to keep running after errors occur...Codebraid isn't designed to handle that case, but with the right template design it could work.

• I've just redesigned the built-in code execution system with version 0.6 and introduced the pair of start/end delims that you're using, instead of just having delims at the start of each chunk. I still need to write up the details about the new system and work on converting the README into a proper website that covers some of these details. I am probably going to recommend in the general case that stdout and stderr be flushed twice per code chunk, immediately after the start delims and immediately after the end delims. That has some advantages for Codebraid parsing output in the general case. For a language like GAP, it may be fine to flush once, but that would need to be after the start delims to give best results.

• Based on https://www.gap-system.org/Manuals/doc/ref/chap4.html, you may want to expand error_patterns to ['Error,', 'error:']. If error messages ever contain line numbers, a pattern for those can also be specified.

• Based on the example output in Markdown format, it looks like your Pandoc installation is at least a little behind the latest version...Pandoc has changed a few details about the output layout. If it's convenient, I'd suggest upgrading to the latest version. I usually have to update all example HTML and Markdown a few times a year to keep up with Pandoc changes, as opposed to any changes within Codebraid itself.

Two final remarks that aren't directly related to this code:

• The built-in code execution system is currently focused on executing source files or scripts. However, I am working toward adding what might be called "REPL emulation", where you enter code and it is executed in such a way that you get the same output you would from using an interactive terminal, including things like prompts. This currently works (experimentally, undocumented) for .python_repl. When this is more developed, would you be interested in this for GAP?

• If you use VS Code, I've just released an extension for previewing documents: https://marketplace.visualstudio.com/items?itemName=gpoore.codebraid-preview.

[ChrisJefferson]

Hi, I'll go through your comments, thanks! I'll just mention a few (as they might be generally useful).

GAP doesn't have any explicit 'flush' function. (If you go searching you might find IO_flush, but that isn't useful in this situation). So far codebraid seems to be working fine without it. If flushing really is required, I could investigate adding it to GAP (I could also use the IO library to do output, so then I could use IO_flush, but that raises other issues).

Unfortunately, at the moment we don't get error locations. By default when an error occurs GAP enters a debugger straight away (which hangs codebraid, as you have to type into it). I disable that debugger, but it's the debugger that does most work of printing error locations.

The ();; is because else GAP's parser gets confused, particularly by missing semi-colons, so the output ends up including Codebraid statements. This isn't "broken", but a little unpleasent, like:

 Error, no method found! For debugging hints type ?Recovery from NoMethodFound Error, no 1st choice method found for `+' on 2 arguments Syntax error: ; expected in source.gap:[6] Print("\n #Codebraid(output=stdout, delim=end, chunk=0, output_chunk=0, hash=90eab37110bf9e59cc9614251bd51036172efe075e3bad05bad6e73276915f21,)\n");

I will have a look at the python_repl. It might be interesting to use that when people want to interact with the debugger (which I mentioned earlier is built-in, as soon as you enter an error in interactive mode, the prompt changes to brk>).

[gpoore]

For flushing output: All the existing templates for languages flush stdout and stderr, but that's because there's an assumption that these typically won't be line buffered. If GAP automatically flushes at the end of each line, then this isn't necessary. Actually, the main impacts of not flushing are (1) --live-output might be delayed and (2) some output might be lost due to errors that cause a program to exit before stdout and/or stderr are flushed (which may not be possible or an issue with GAP).

For error locations: It might be possible to modify Codebraid so that it detects the debugger starting by looking for brk>, and then writes something to the program's stdin. I don't know if that would be helpful in getting better output when there are errors.

[ChrisJefferson]

Sorry, dropped this PR on the floor (although I have been using this myself for generating some small documents).

I had a rebase and cleaned up some minor issues. While I'm sure it could continue to be improved, I think it's OK for now.

Random thing I observed while looking over this -- the sage integration seems to have broken, I think it's just not been updated?

[gpoore]

Sorry for the delay...I've been focused on updating the Codebraid VS Code extension recently, and am now back to working on Codebraid itself. This looks good, so I've merged it. It will probably be a few days before a new release incorporating GAP is out. Also, I'll check Sage support and see if something needs to be fixed.