# gperl

## Name



           gperl - execute Perl commands in _groff_ documents
    


## Synopsis



           **gperl**[_file_ ...]
    
           **gperl -h**
    
           **gperl --help**
    
           **gperl -v**
    
           **gperl --version**
    


## Description



           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 regions



           _Perl_ parts in _groff files_ are enclosed by two **.Perl** requests with
           different arguments, a _starting_ and an _ending_ command.
    
       **Starting Perl mode**
           The starting _Perl request_ can either be without arguments, or by a
           request that has the term **start** as its only argument.
    
                  •      **.Perl**
    
                  •      **.Perl start**
    
       **Ending Perl mode without storage**
           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.
    
                  •      **.Perl stop**
    
                  •      **.Perl** _other_than_start_
           The argument _other_than_start_ can additionally be used as a _groff_
           string variable name for storage — see next section.
    
       **Ending Perl mode with storage**
           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
    
           _groff strings_
                  by creating a groff command **.ds**
    
           _groff register_
                  by creating a groff command **.rn**
    
           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_
           In _register mode_ the following groff command is generated
                  **.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.
    
           **.Perl .ds** _var_name_
                  This will store 1 output line into the groff string named
                  _var_name_ by the automatically created command
                         **.ds** _var_name output_
    
           **.Perl** _var_name_
                  If _var_name_ is different from **start** this is equivalent to
                  the former command, because the string mode is string with
                  **.ds** command.  default.
    
           **.Perl** _var_name1 var_name2_
                  This will store 2 output lines into groff string names
                  _var_name1_ and _var_name2_ , because the default mode **.ds** is
                  active, such that no **.ds** argument is needed.  Of course,
                  this is equivalent to
                         **.Perl .ds** _var_name1 var_name2_
                  and
                         **.Perl .ds** _var_name1_ **.ds** _var_name2_
    
           **.Perl .nr** _var_name1 varname2_
                  stores both variables as register variables.  _gperl_
                  generates
                  **.nr** _var_name1 output_line1_
                  **.nr** _var_name2 output_line2_
    
           **.Perl .nr** _var_name1_ **.ds** _var_name2_
                  stores the 1st argument as _register_ and the second as
                  _string_ by
                  **.nr** _var_name1 output_line1_
                  **.ds** _var_name2 output_line2_
    


## Example



           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
           by _gperl_ as food for the coming _groff_ run.
    
           A _Perl part_ with several outputs is:
                  .Perl start
                  print ”first\n”;
                  print ”second line\n”;
                  print ”3\n”;
                  .Perl var1 var2 .nr var3
           This stores 3 printed lines into 3 _groff_ strings.  **var1** ,**var2** ,**var3**.
           So the following _groff_ command lines are created:
                  .ds var1 first
                  .ds var2 second line
                  .nr var3 3
    


## Authors



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


## See also



           Man pages related to _groff_ are _groff_(1), _groff_(7), and _grog_(1).
    
           Documents related to _Perl_ are _perl_(1), _perl_(7).
    


* * *