gperl(1) - f39

1gperl(1)                    General Commands Manual                   gperl(1)
2
3
4

Name

6       gperl - execute Perl commands in groff documents
7

Synopsis

9       gperl [file ...]
10
11       gperl -h
12       gperl --help
13
14       gperl -v
15       gperl --version
16

Description

18       This is a preprocessor for groff(1).  It allows the use of perl(7) code
19       in groff(7) files.  The result of a Perl part can be  stored  in  groff
20       strings  or  numerical registers based on the arguments at a final line
21       of a Perl part.
22
23       If no operands are given, or if file is “-”, gperl reads  the  standard
24       input  stream.  A double-dash argument (“--”) causes all subsequent ar‐
25       guments to be interpreted as file operands, even if their  names  start
26       with  a  dash.   -h  and --help display a usage message, whereas -v and
27       --version display version information; all exit afterward.
28

Perl regions

30       Perl parts in groff files are enclosed by two .Perl requests with  dif‐
31       ferent arguments, a starting and an ending command.
32
33   Starting Perl mode
34       The  starting Perl request can either be without arguments, or by a re‐
35       quest that has the term start as its only argument.
36
37              •      .Perl
38
39              •      .Perl start
40
41   Ending Perl mode without storage
42       A .Perl command line with an argument different from start  finishes  a
43       running  Perl part.  Of course, it would be reasonable to add the argu‐
44       ment stop; that's possible, but not necessary.
45
46              •      .Perl stop
47
48              •      .Perl other_than_start
49       The argument other_than_start can  additionally  be  used  as  a  groff
50       string variable name for storage — see next section.
51
52   Ending Perl mode with storage
53       A useful feature of gperl is to store one or more results from the Perl
54       mode.
55
56       The output of a Perl part can be got with backticks `...`.
57
58       This program collects all printing to STDOUT (normal  standard  output)
59       by  the  Perl print program.  This pseudo-printing output can have sev‐
60       eral lines, due to printed line breaks with \n.  By that, the output of
61       a  Perl  run should be stored into a Perl array, with a single line for
62       each array member.
63
64       This Perl array output can be stored by gperl in either
65
66       groff strings
67              by creating a groff command .ds
68
69       groff register
70              by creating a groff command .rn
71
72       The storage modes can be determined by arguments of  a  final  stopping
73       .Perl  command.   Each  argument .ds changes the mode into groff string
74       and .nr changes the mode into groff register for all  following  output
75       parts.
76
77       By default, all output is saved as strings, so .ds is not really needed
78       before the first .nr command.  That suits to  groff(7),  because  every
79       output  can be saved as groff string, but the registers can be very re‐
80       strictive.
81
82       In string mode, gperl generates a groff string storage line
83              .ds var_name content
84       In register mode the following groff command is generated
85              .nr var_name content
86
87       We present argument collections in the following.  You can add as first
88       argument for all stop.  We omit this additional element.
89
90       .Perl .ds var_name
91              This  will  store  1  output  line  into  the groff string named
92              var_name by the automatically created command
93                     .ds var_name output
94
95       .Perl var_name
96              If var_name is different from start this is  equivalent  to  the
97              former  command, because the string mode is string with .ds com‐
98              mand.  default.
99
100       .Perl var_name1 var_name2
101              This will store 2 output lines into groff string names var_name1
102              and var_name2, because the default mode .ds is active, such that
103              no .ds argument is needed.  Of course, this is equivalent to
104                     .Perl .ds var_name1 var_name2
105              and
106                     .Perl .ds var_name1 .ds var_name2
107
108       .Perl .nr var_name1 varname2
109              stores both variables as register variables.  gperl generates
110              .nr var_name1 output_line1
111              .nr var_name2 output_line2
112
113       .Perl .nr var_name1 .ds var_name2
114              stores the 1st argument as register and the second as string by
115              .nr var_name1 output_line1
116              .ds var_name2 output_line2
117

Example

119       A possible Perl part in a roff file could look like that:
120              before
121              .Perl start
122              my $result = 'some data';
123              print $result;
124              .Perl stop .ds string_var
125              after
126
127       This stores  the  result  ”some  data”  into  the  roff  string  called
128       string_var, such that the following line is printed:
129              .ds string_var some data
130       by gperl as food for the coming groff run.
131
132       A Perl part with several outputs is:
133              .Perl start
134              print ”first\n”;
135              print ”second line\n”;
136              print ”3\n”;
137              .Perl var1 var2 .nr var3
138       This  stores 3 printed lines into 3 groff strings.  var1,var2,var3.  So
139       the following groff command lines are created:
140              .ds var1 first
141              .ds var2 second line
142              .nr var3 3
143

Authors

145       gperl was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
146

Name

Synopsis

Description

Perl regions

Example

Authors

See also