.TH gperl 1 "2026-03-15" "groff 1.24.1"
.SH "نام (NAME)"
gperl \- اجرای دستورات Perl در اسناد groff
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright 2014-2020 Free Software Foundation, Inc.
.\"
.\" This file is part of gperl.
.\"
.\" gperl is distributed with groff, the GNU roff typesetting system.
.\"
.\" groff 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 of the License, or
.\" (at your option) any later version.
.\"
.\" groff 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 this program.  If not, see
.\" <https://www.gnu.org/licenses>.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_gperl_1_man_C \n[.cp]
.cp 0
.
.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.nr do-fallback 0
.if !\n(.f           .nr do-fallback 1 \" mandoc
.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
.if \n[do-fallback]  \{\
.  de MR
.    ie \\n(.$=1 \
.      I \%\\$1
.    el \
.      IR \%\\$1 (\\$2)\\$3
.  .
.\}
.rr do-fallback
.
.
.\" ====================================================================
.SH "خلاصه دستور (SYNOPSIS)"
.\" ====================================================================
.
.SY gperl
.RI [ file\~ .\|.\|.]
.YS
.
.
.P
.SY gperl
.B \-h
.YS
.
.SY gperl
.B \-\-help
.YS
.
.
.P
.SY gperl
.B \-v
.YS
.
.SY gperl
.B \%\-\-version
.YS
.
.
.\" ====================================================================
.SH "توضیحات (DESCRIPTION)"
.\" ====================================================================
.
این برنامه یک پیش‌پردازنده برای
.MR groff 1
است.
.
این ابزار امکان استفاده از کدهای
.MR perl 7
را در فایل‌های
.MR groff 7
فراهم می‌کند.
.
نتیجه یک
.I بخش Perl
می‌تواند بر اساس آرگومان‌های خط پایانی آن
.IR "بخش Perl" ،
در
.I رشته‌ها
یا
.I ثبات‌های عددی
groff ذخیره شود.
.
.
.P
اگر هیچ عملوندی داده نشود، یا اگر
.I file
برابر با
.RB \[lq] \- \[rq]
باشد،
.I gperl
جریان ورودی استاندارد را می‌خواند.
.
یک آرگومان دوخط‌تیره
.RB (\[lq] \-\- \[rq])
باعث می‌شود تمامی آرگومان‌های پس از آن، حتی اگر نام آن‌ها با خط تیره آغاز شود، به عنوان عملوندهای
.I file
تفسیر شوند.
.
گزینه‌های
.B \-h
و
.B \-\-help
پیام نحوه استفاده را نمایش می‌دهند، در حالی که
.B \-v
و
.B \%\-\-version
اطلاعات نسخه را نمایش داده و همگی پس از آن خارج می‌شوند.
.
.
.\" ====================================================================
.SH "ناحیه‌های پرل (Perl regions)"
.\" ====================================================================
.
بخش‌های
.I Perl
در فایل‌های
.I groff
میان دو درخواست
.B .Perl
با آرگومان‌های متفاوت محصور می‌شوند: یک دستور
.I شروع‌کننده
و یک دستور
.IR پایان‌بخش .
.
.
.\" ====================================================================
.SS "شروع حالت Perl"
.\" ====================================================================
.
درخواست شروع
.I Perl
می‌تواند بدون آرگومان باشد، یا درخواستی باشد که عبارت
.B start
تنها آرگومان آن است.
.RS
.IP \(bu
.B .Perl
.IP \(bu
.B .Perl start
.RE
.
.
.\" ====================================================================
.SS "پایان دادن به حالت Perl بدون ذخیره‌سازی"
.\" ====================================================================
.
یک خط دستور
.B .Perl
با آرگومانی غیر از
.B start
به یک
.I بخش Perl
در حال اجرا پایان می‌دهد.
.
البته افزودن آرگومان
.B stop
منطقی خواهد بود؛ این کار امکان‌پذیر است، اما الزامی نیست.
.
.RS
.IP \(bu
.B .Perl stop
.IP \(bu
.BI .Perl " other_than_start"
.RE
.
آرگومان
.I other_than_start
می‌تواند علاوه بر این به عنوان نام متغیر رشته‌ای
.I groff
برای ذخیره‌سازی استفاده شود \(em بخش بعدی را ببینید.
.
.
.\" ====================================================================
.SS "پایان دادن به حالت Perl همراه با ذخیره‌سازی"
.\" ====================================================================
.
یک ویژگی مفید
.I gperl
ذخیره‌سازی یک یا چند نتیجه حاصل از
.I حالت Perl
است.
.
.
.P
خروجی یک
.I بخش Perl
را می‌توان با استفاده از بکتیک‌های
.B \[ga]...\[ga]
دریافت کرد.
.
.
.P
این برنامه تمام موارد چاپ‌شده در STDOUT (خروجی استاندارد معمول) توسط دستور
.B print
پرل را جمع‌آوری می‌کند.
.
این خروجی شبه‌چاپی به دلیل شکست‌های خط چاپ‌شده با
.BR \(rsn ،
می‌تواند شامل چند خط باشد.
.
بدین ترتیب، خروجی حاصل از اجرای Perl باید در یک آرایه Perl ذخیره شود، با یک خط مجزا برای هر عضو آرایه.
.
.
.P
این خروجی آرایه Perl می‌تواند توسط
.I gperl
در یکی از موارد زیر ذخیره شود:
.TP
.I رشته‌های groff
با ایجاد دستور groff به صورت
.B .ds
.
.TP
.I ثبات‌های groff
با ایجاد دستور groff به صورت
.B .nr
.
.
.P
حالت‌های ذخیره‌سازی را می‌توان با آرگومان‌های دستور پایانی
.B .Perl
تعیین کرد.
.
هر آرگومان
.B .ds
حالت را به
.I رشته groff
و هر آرگومان
.B .nr
حالت را به
.I ثبات groff
برای تمامی بخش‌های خروجی پس از آن تغییر می‌دهد.
.
.
.br
.ne 2v
.P
به‌طور پیش‌فرض، تمامی خروجی‌ها به صورت رشته ذخیره می‌شوند، بنابراین
.B .ds
پیش از نخستین دستور
.B .nr
واقعاً مورد نیاز نیست.
.
این امر با
.MR groff 7
سازگار است، چرا که هر خروجی می‌تواند به عنوان یک رشته
.I groff
ذخیره شود، در حالی که ثبات‌ها می‌توانند بسیار محدودکننده باشند.
.
.
.P
در
.IR "حالت رشته" ،
برنامه
.I gperl
یک خط ذخیره‌سازی رشته
.I groff
تولید می‌کند:
.RS
.EX
.BI .ds " var_name content"
.EE
.RE
.
در
.I حالت ثبات
دستور groff زیر تولید می‌شود:
.RS
.EX
.BI .nr " var_name content"
.EE
.RE
.
.
.P
در ادامه مجموعه‌های مختلف آرگومان‌ها را ارائه می‌دهیم.
.
می‌توانید برای همگی،
.B stop
را به عنوان نخستین آرگومان اضافه کنید.
.
ما این عنصر اضافی را حذف می‌کنیم.
.
.
.P
.TP
.BI ".Perl .ds " var_name
این دستور ۱ خط خروجی را با استفاده از دستورِ خودکار ایجادشده، در رشته groff با نام
.I var_name
ذخیره می‌کند:
.RS
.RS
.EX
.BI .ds " var_name output"
.EE
.RE
.RE
.
.
.TP
.BI .Perl " var_name"
اگر
.I var_name
مقداری غیر از
.B start
داشته باشد، معادل دستور قبلی است، چرا که حالت رشته‌ای با دستور
.B .ds
پیش‌فرض است.
.
.
.TP
.BI .Perl " var_name1 var_name2"
این دستور ۲ خط خروجی را در نام‌های رشته groff به صورت
.I var_name1
و
.I var_name2
ذخیره می‌کند، زیرا حالت پیش‌فرض
.B .ds
فعال است، به طوری که به هیچ آرگومان
.B .ds
نیازی نیست.
.
البته این معادل است با:
.RS
.RS
.EX
.BI ".Perl .ds " "var_name1 var_name2"
.EE
.RE
و
.RS
.EX
.BI ".Perl .ds " "var_name1 " ".ds" " var_name2"
.EE
.RE
.RE
.
.
.TP
.BI ".Perl .nr" " var_name1 varname2"
هر دو متغیر را به عنوان متغیرهای ثبات ذخیره می‌کند.
.
.I gperl
دستورات زیر را تولید می‌کند:
.RS
.EX
.BI .nr " var_name1 output_line1"
.BI .nr " var_name2 output_line2"
.EE
.RE
.
.
.TP
.BI ".Perl .nr " var_name1 " .ds " var_name2
آرگومان اول را به عنوان
.I ثبات
و آرگومان دوم را به عنوان
.I رشته
با دستورات زیر ذخیره می‌کند:
.RS
.EX
.BI .nr " var_name1 output_line1"
.BI .ds " var_name2 output_line2"
.EE
.RE
.
.
.\" ====================================================================
.SH "مثال‌ها (EXAMPLES)"
.\" ====================================================================
.
یک
.I بخش Perl
احتمالی در یک
.I فایل roff
می‌تواند به این صورت باشد:
.RS
.EX
before
\&.Perl start
my $result = \[aq]some data\[aq];
print $result;
\&.Perl stop .ds string_var
after
.EE
.RE
.
.
.P
این دستور نتیجه
.B \(rqsome data\(rq
را در
.I رشته roff
به نام
.B string_var
ذخیره می‌کند، به طوری که خط زیر توسط
.I gperl
چاپ می‌شود:
.RS
.EX
\&.ds string_var some data
.EE
.RE
تا به عنوان ورودی برای اجرای بعدی
.I groff
مورد استفاده قرار گیرد.
.
.
.P
یک
.I بخش Perl
با چند خروجی به شکل زیر است:
.RS
.EX
\&.Perl start
print \(rqfirst\(rsn\(rq;
print \(rqsecond line\(rsn\(rq;
print \(rq3\(rsn\(rq;
\&.Perl var1 var2 .nr var3
.EE
.RE
.
این کار ۳ خط چاپ‌شده را در ۳ متغیر
.I groff
شامل
.BR var1 ،
.B var2
و
.B var3
ذخیره می‌کند.
.
بنابراین خطوط دستور
.I groff
زیر ایجاد می‌شوند:
.RS
.EX
\&.ds var1 first
\&.ds var2 second line
\&.nr var3 3
.EE
.RE
.
.
.\" ====================================================================
.SH "نویسندگان (AUTHORS)"
.\" ====================================================================
.
.I gperl
توسط
.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.ME
نوشته شده است.
.
.
.\" ====================================================================
.SH "همچنین ببینید (SEE ALSO)"
.\" ====================================================================
.
.P
صفحات راهنمای مرتبط با
.I groff
عبارتند از:
.MR groff 1 ,
.MR groff 7
و
.MR grog 1 .
.
.
.P
اسناد مرتبط با
.I Perl
عبارتند از:
.MR perl 1
و
.MR perl 7 .
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_gperl_1_man_C]
.do rr *groff_gperl_1_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: