# man > gperl(1) [_gperl_(1)](https://www.chedong.com/phpMan.php/man/gperl/1/markdown) General Commands Manual [_gperl_(1)](https://www.chedong.com/phpMan.php/man/gperl/1/markdown) ## 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 ]8;;man:[groff(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)\[_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)]8;;\. It allows the use of ]8;;man:[perl(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown)\[_perl_(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown)]8;;\ code in ]8;;man:[groff(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)\[_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)]8;;\ 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 dou‐ ble-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 **pro‐ gram. 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 ar‐ gument **.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 ]8;;man:[groff(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)\[_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)]8;;\, 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 automati‐ cally 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_, be‐ cause 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 fol‐ lowing 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 ]8;;mailto:\Bernd Warken]8;;\. **See also** Man pages related to _groff_ are ]8;;man:[groff(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)\[_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)]8;;\, ]8;;man:[groff(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)\[_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)]8;;\, and ]8;;man:[grog(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown)\[_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown)]8;;\. Documents related to _Perl_ are ]8;;man:[perl(1)](https://www.chedong.com/phpMan.php/man/perl/1/markdown)\[_perl_(1)](https://www.chedong.com/phpMan.php/man/perl/1/markdown)]8;;\, ]8;;man:[perl(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown)\[_perl_(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown)]8;;\. groff 1.23.0 31 March 2024 [_gperl_(1)](https://www.chedong.com/phpMan.php/man/gperl/1/markdown)