NAME

gp-inline -- run Pari/GP code inline in a document

SYNOPSIS

 gp-inline [--options] filename...

DESCRIPTION

gp-inline extracts and executes Pari/GP code which from comments inline in a document such as TeX or POD. It can be used to include checks of calculations or formulas in the text. For example a TeX document

    From which it is seen that $1+1 = 2$.
    % Test-Pari  1+1 == 2

is checked by

    gp-inline foo.tex

A Test-Pari line should be evaluate to a non-zero value. Usually it's some sort of comparison or boolean. The evaluation is like a line of gp input, so semicolons can separate multiple expressions and the last is the final result.

    % Test-Pari  my(n=5); 2*n^2 + n == 55

New gp functions or globals can be defined with lines like

    % Test-Pari-DEFINE  my_func(n) = 2*n + 3;
    % Test-Pari-DEFINE  my_vector = [ 1, 2, 3, 5 ];

These lines are arbitrary code passed directly to gp. Multi-line functions or expressions are given by backslashing or braces in usual gp style.

    % Test-Pari-DEFINE  long_func(n) =   \
    % Test-Pari-DEFINE    some + long    \
    % Test-Pari-DEFINE    + func + expression;

    % Test-Pari-DEFINE  my_matrix = {
    % Test-Pari-DEFINE    [ 1, 2;
    % Test-Pari-DEFINE      2, 1 ];
    % Test-Pari-DEFINE  }

External gp code modules etc can be included with the usual read(). Normally this will be in a Test-Pari-DEFINE.

    % Test-Pari-DEFINE  read("my-library.gp");

Tests are run with gp -f so the user's ~/.gprc file is not evaluated. This is designed to give consistent testing, without personal preferences only wanted for gp interactively etc.

Syntax errors and type errors in tests or defines are generally fatal. A location string is included in the test form so the backtrace is something like

    *** at top-level: ...inline("foo.tex:153",(()->bar())())
    ...

which means foo.tex line 153 was the offending Test-Pari.

Errors in Test-Pari-DEFINE statements don't have this location in the backtrace (since they're a "top-level" evaluation). If the offending part is not obvious then run gp-inline --verbose to see a \e trace of each expression. It includes some "foo.tex:150" etc strings which are the source locations. (Is there a good way to insert a print before an error backtrace? An iferr trap loses the backtrace.)

OPTIONS

The command line options are

--stdin

Read a document from standard input.

--run

Run the inline tests in each given file. This is the default action.

--extract

Extract the inline gp code from each file and print to standard output. The output is ready to run with gp -f or similar.

Usually this will be just one input file, otherwise the tests of each are one after the other and globals left by the first might upset subsequent tests.

--defines

Extract just the definition lines from the given files and print to standard output. The output is ready to run with gp.

This is good for extracting definitions so they can be used separately in further calculations or experiments. It's also possible to go the other way, have definitions in a separate file which the document loads with read(). Usually it avoids mistakes to keep a definition with the formula etc in the document. But generic or very large code could be kept separate.

--help

Print a brief help message.

--version

Print the program version number and exit.

BUGS

There's no support for a multi-file document where defines would be carried over from one part to the next.

SEE ALSO

gp(1)

HOME PAGE

http://user42.tuxfamily.org/gp-inline/index.html

LICENSE

Copyright 2015 Kevin Ryde

gp-inline is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

gp-inline is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gp-inline. If not, see <http://www.gnu.org/licenses/>.

cpanm Math::PlanePath

perl -MCPAN -e shell
install Math::PlanePath