gperl(1) | User Commands | gperl(1) |
gperl - execute Perl commands in groff documents
gperl |
[file ...] |
gperl |
-h |
gperl |
--help |
gperl |
-v |
gperl |
--version |
This is a preprocessor for groff(1). It allows the use of perl(7) code in groff(7) files. The result of a Perl part can be stored in groff strings or numerical registers based on the arguments at a final line of a Perl part.
If no operands are given, or if file is “-”, gperl reads the standard input stream. A double-dash argument (“--”) causes all subsequent arguments to be interpreted as file operands, even if their names start with a dash. -h and --help display a usage message, whereas -v and --version display version information; all exit afterward.
Perl parts in groff files are enclosed by two .Perl requests with different arguments, a starting and an ending command.
The starting Perl request can either be without arguments, or by a request that has the term start as its only argument.
A .Perl command line with an argument different from start finishes a running Perl part. Of course, it would be reasonable to add the argument stop; that's possible, but not necessary.
A useful feature of gperl is to store one or more results from the Perl mode.
The output of a Perl part can be got with backticks `...`.
This program collects all printing to STDOUT (normal standard output) by the Perl print program. This pseudo-printing output can have several lines, due to printed line breaks with \n. By that, the output of a Perl run should be stored into a Perl array, with a single line for each array member.
This Perl array output can be stored by gperl in either
The storage modes can be determined by arguments of a final
stopping .Perl command. Each argument .ds changes the mode
into groff string and .nr changes the mode into groff
register for all following output parts.
By default, all output is saved as strings, so .ds is not really needed before the first .nr command. That suits to groff(7), because every output can be saved as groff string, but the registers can be very restrictive.
In string mode, gperl generates a groff string storage line
.ds var_name content
.nr var_name content
We present argument collections in the following. You can add as first argument for all stop. We omit this additional element.
.ds var_name output
.Perl .ds var_name1 var_name2
.Perl .ds var_name1 .ds var_name2
.nr var_name1 output_line1 .nr var_name2 output_line2
.nr var_name1 output_line1 .ds var_name2 output_line2
A possible Perl part in a roff file could look like that:
before .Perl start my $result = 'some data'; print $result; .Perl stop .ds string_var after
This stores the result ”some data” into the roff string called string_var, such that the following line is printed:
.ds string_var some data
A Perl part with several outputs is:
.Perl start print ”first\n”; print ”second line\n”; print ”3\n”; .Perl var1 var2 .nr var3
.ds var1 first .ds var2 second line .nr var3 3
gperl was written by Bernd Warken.
Man pages related to groff are groff(1), groff(7), and grog(1).
Documents related to Perl are perl(1), perl(7).
2 July 2023 | groff 1.23.0 |