capture -- evaluate Macaulay2 code and capture the output

Synopsis

Usage:

(err, output) := capture str
Inputs:
- str, a net, a list, or a string, the Macaulay2 code to be evaluated
Optional inputs:
- UserMode => a Boolean value, default value true, indicates whether currently loaded packages and exported symbols should be accessible while str is being evaluated.
- PackageExports => a list, default value null, of packages to be loaded before evaluating str. The current package, as given by Macaulay2Doc, will be included.
Outputs:
- err, a Boolean value, whether the evaluation was interrupted because of an error
- output, a string, the result of the evaluation

Description

This function evaluates the given Macaulay2 code within the same process in order to speed up tasks such as generating example results or checking the package tests.

i1 : (err, output) = capture examples(resolution, Ideal) 

o1 = (false,                                                                
             i1 : -- examples for tag: resolution(Ideal)
                  -- /usr/local/share/Macaulay2/
                  R = ZZ[a..d]

             o1 = R

             o1 : PolynomialRing

             i2 : I = ideal(a,b,c,d)

             o2 = ideal (a, b, c, d)

             o2 : Ideal of R

             i3 : C = res I

                   1      4      6      4      1
             o3 = R  <-- R  <-- R  <-- R  <-- R  <-- 0
                                                      
                  0      1      2      3      4      5

             o3 : ChainComplex

             i4 : C_2

                   6
             o4 = R

             o4 : R-module, free, degrees {6:2}

             i5 : C.dd_2

             o5 = {1} | -b 0  -c 0  0  -d |
                  {1} | a  -c 0  0  -d 0  |
                  {1} | 0  b  a  -d 0  0  |
                  {1} | 0  0  0  c  b  a  |

                          4      6
             o5 : Matrix R  <-- R

             i6 : 
     ------------------------------------------------------------------------
                                )

     Macaulay2Doc/doc10.m2:256:0

o1 : Sequence

i2 : assert not err

If UserMode => false given, the dictionaries available to the user will not be affected by the evaluation and collectGarbage is called afterwards.

Errors occurred while evaluating str do not cause an error outside of capture.

i3 : (err, output) = capture /// stderr << "Checking a false statement:" << endl; 1/0 ///

o3 = (true,                                                            )
            i1 :  stderr << "Checking a false statement:" << endl; 1/0 
            Checking a false statement:
            currentString:1:51:(3):[3]: error: division by zero


o3 : Sequence

i4 : assert err

Certain examples or tests might not be compatible with capture. In such cases, use the string -* no-capture-flag *- somewhere within str so that the code is run in a separate Macaulay2 subprocess instead.

Ways to use capture:

capture(List)
capture(Net)
capture(String)
capture(TestInput) (missing documentation)

For the programmer

The object capture is a method function with options.

capture -- evaluate Macaulay2 code and capture the output

Synopsis

Description

See also

Ways to use capture:

For the programmer