Merge pull request #51 from ChrisJefferson/gap-language

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

README.md

@@ -11,7 +11,7 @@ for editor support.
 
 Codebraid provides two options for executing code.  It includes a built-in
 code execution system that currently supports **Python 3.7+**, **Julia**,
-**Rust**, **R**, **Bash**, **JavaScript**, and **SageMath**.  Code can also be
+**Rust**, **R**, **Bash**, **JavaScript**, **GAP** and **SageMath**.  Code can also be
 executed using **Jupyter kernels**, with support for rich output like plots.
 
 **Development:**  https://github.com/gpoore/codebraid
@@ -44,6 +44,9 @@ and Rust examples demonstrate more advanced features at the end):
   * [JavaScript example](https://htmlpreview.github.io/?https://github.com/gpoore/codebraid/blob/master/examples/javascript.html)
     [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/javascript.cbmd)]
     [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/javascript.html)]
+  * [GAP example](https://htmlpreview.github.io/?https://github.com/gpoore/codebraid/blob/master/examples/gap.html)
+    [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/gap.cbmd)]
+    [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/gap.html)]
 
 
 ## Simple example

codebraid/languages/gap.bespon

@@ -0,0 +1,40 @@
+|=== gap
+extension = 'gap'
+
+executable = 'gap'
+
+run_command = '{executable} -x 9999 -A --quiet --nointeract {source}'
+run_encoding = 'utf8'
+
+run_template =
+    |```
+    LoadPackage("io",false);; # for 'IO_Flush'
+    {code}
+    |```/
+
+chunk_wrapper =
+    |```
+    Print("\n{stdout_start_delim}\n");
+    PrintTo("*errout*","\n{stderr_start_delim}\n");
+    {code}
+    ();; # This ensures parser errors in code do not stop the 'Print' below
+    Print("\n{stdout_end_delim}\n");
+    PrintTo("*errout*","\n{stderr_end_delim}\n");
+    IO_Flush(IO_WrapFD(1,false,false));
+    IO_Flush(IO_WrapFD(2,false,false));
+    |```/
+
+inline_expression_formatter =
+    |```
+    _codebraid_temp_{temp_suffix} := ({code});
+    Print("\n{expr_start_delim}\n");
+    PrintTo("*errout*","\n{expr_start_delim}\n");
+    Print(_codebraid_temp_{temp_suffix});
+    Print("\n{expr_end_delim}\n");
+    PrintTo("*errout*","\n{expr_end_delim}\n");
+    IO_Flush(IO_WrapFD(1,false,false));
+    IO_Flush(IO_WrapFD(2,false,false));
+    |```/
+
+error_patterns = ['Error,', 'error:']
+line_number_patterns = ':{number}'

codebraid/languages/index.bespon

@@ -93,3 +93,4 @@ R = "R.bespon"
 rust = "rust.bespon"
 javascript = "javascript.bespon"
 js = $~.javascript
+gap = "gap.bespon"

examples/build_gap.sh

@@ -0,0 +1,2 @@
+codebraid pandoc -f markdown -t html --overwrite --standalone --self-contained --css example.css -o gap.html gap.cbmd
+codebraid pandoc -f markdown -t markdown --overwrite --standalone -o gap_output.md gap.cbmd

examples/gap.cbmd

@@ -0,0 +1,207 @@
+---
+title: "Codebraid with GAP (Groups, Algorithms, Programming - a System for Computational Discrete Algebra)"
+---
+
+
+## Inline code
+
+
+### Run
+
+Inline code with `.cb-run` gives raw stdout.
+
+`Print(1 + 2);`{.gap .cb-run session=firsttest example=true}
+
+
+### Expression and inline notebook
+
+Inline code with `.cb-expr` evaluates an expression and then inserts the raw
+output into the document, where it is interpreted as Markdown.  Inline code
+with `.cb-nb` (`nb` is short for `notebook`) is similar, except output is
+shown verbatim.  Notice that since these are expressions, a trailing semicolon
+must not be used. 
+
+`StringFormatted("*{}*", Sum([1..10]))`{.gap .cb-expr example=true}
+
+`StringFormatted("*{}*", Sum([1..10]))`{.gap .cb-nb example=true}
+
+
+### Stderr
+
+In the event of an error, inline code automatically shows stderr by default.
+This code is executed in its own session, `inline_error`, so that it does
+not impact other examples.
+
+`1 + "a"`{.gap .cb-run session=inline_error example=true}
+
+
+### Source errors
+
+A message is also displayed for errors in the Markdown source.  This usually
+includes the name of the document source and the approximate line number.
+
+`Print(1 + 2);`{.gp .cb-run session=inline_source_error example=true}
+
+
+### Code
+
+Inline code with `.cb-code` simply displays the code.  Nothing is executed.
+
+`Print("Hello from GAP!");`{.gap .cb-code example=true}
+
+The output is identical to that of
+```
+`Print("Hello from GAP!");`{.gap}
+```
+so `.cb-code` is only really useful when it is combined with other Codebraid
+features.  For example, it is possible to give code with `.cb-code` a `name`,
+and then copy it by `name` into a separate location where it is executed.  See
+[Copying code and output](#copying).
+
+
+
+## Block code
+
+
+### Run
+
+Code blocks with `.cb-run` give raw stdout.  There is continuity between code
+blocks so long as they are in the same session; variables persist.
+
+```{.gap .cb-run session=hello example=true}
+x := "Hello from *GAP!*";
+```
+
+```{.gap .cb-run session=hello example=true}
+Print(x);
+```
+
+
+### Stderr
+
+Code blocks show stderr automatically by default.
+
+```{.gap .cb-nb session=block_error example=true}
+x := 12;
+y := x + "x";
+```
+
+
+### Source errors
+
+A message is also displayed for errors in the Markdown source.  This usually
+includes the name of the document source and the approximate line number.
+
+```{.gap .cb-ruuun session=block_source_error example=true}
+print(1 + 2);
+```
+
+
+### Code
+
+Code blocks with `.cb-code` simply display the code.  Nothing is executed.
+
+```{.gap .cb-code example=true}
+Print("Hello from GAP!");
+```
+
+The output is essentially identical to that of a normal code block; the only
+differences are some default display options, like line numbering.  Thus
+`.cb-code` is primarily useful when it is combined with other Codebraid
+features.  For example, it is possible to give code with `.cb-code` a `name`,
+and then copy it by `name` into a separate location where it is executed.  See
+[Copying code and output](#copying).
+
+
+
+## Other options
+
+By default, stdout and stderr are only shown if they are non-empty.  In some
+situations, it may be useful to represent empty output visually as
+confirmation that there indeed was none.
+
+```{.gap .cb-run show=code+stdout+stderr:verbatim_or_empty example=true}
+x := 1 + 2;;
+```
+
+It is also possible to selectively hide output from a code chunk.
+
+```{.gap .cb-nb hide=stdout example=true}
+Print(x);
+```
+
+`hide` takes any combination of `code`, `stderr`, and `stdout`, or simply
+`all`.
+
+
+
+## Advanced features {#advanced}
+
+### Copying code and output {#copying}
+
+Code chunks can be named using the `name` keyword, which takes an
+identifier-style name.  Then the `copy` keyword can be used in other code
+chunks to copy a named chunk or a combination of named chunks.  When `copy` is
+used with `cb-run`, `cb-expr`, or `cb-nb`, the code is copied and then
+executed as if it had been entered directly.  When `copy` is used with
+`cb-code`, the code is copied and displayed, but nothing is executed.  When
+`copy` is used with the special command `cb-paste`, both the code and output
+are copied but nothing is executed.  This is useful in executing code and then
+showing snippets of the code and/or output in different parts of a document.
+
+`copy` works with named code chunks anywhere in a document; a named code chunk
+does not have to appear in a document before the location where it is copied.
+A code chunk that copies another code chunk can itself have a `name`, and then
+itself be copied.
+
+The next two code chunks are named.
+
+```{.gap .cb-run name=part1 session=copy_source example=true}
+rnums := List([1..10], x -> Random([1..x]));;
+```
+
+```{.gap .cb-run name=part2 session=copy_source example=true}
+PrintFormatted("Random numbers: {}", rnums);
+```
+
+Now the code and output of the previous two code chunks are copied and
+combined.  Because the content for this code block is copied from other code
+chunks, the code block itself should be empty, or may alternately contain a
+space or underscore as a placeholder.
+
+```{.gap .cb-paste copy=part1+part2 show=code+stdout example=true}
+```
+
+It would also be possible to copy and re-execute the code.
+
+```{.gap .cb-run copy=part1+part2 session=copied show=code+stdout:raw example=true}
+```
+
+Another option is to display code, and then copy and execute it later.
+
+```{.gap .cb-code name=hello example=true}
+Print("Hello from GAP!");
+```
+
+```{.gap .cb-nb copy=hello example=true}
+```
+
+
+### Including external files
+
+External files can be included for display or execution using `include_file`.
+The default encoding is UTF-8; other encodings can be selected with
+`include_encoding`.  Instead of including the entire file, it is possible to
+include only a selected range of lines with `include_lines`.  It is also
+possible to include part of a file that matches a regular expression with
+`include_regex`, as shown in the example.  Other options for controlling what
+is included based on starting or ending literal strings or regular expressions
+can be found in the documentation.
+
+```{.html .cb-code include_file=gap.html include_regex="<header.*?/header>" example=true}
+```
+
+When `include_file` is used with `cb-code`, the included code is simply
+displayed.  When `include_file` is used with `cb-run` or another command that
+executes code, the included code is executed just as if it had been entered
+directly.