نام (NAME)

gperl - اجرای دستورات Perl در اسناد groff

خلاصه دستور (SYNOPSIS)

gperl [file ...]

gperl -h

gperl --help

gperl -v

gperl --version

توضیحات (DESCRIPTION)

این برنامه یک پیش‌پردازنده برای groff(1) است. این ابزار امکان استفاده از کدهای perl(7) را در فایل‌های groff(7) فراهم می‌کند. نتیجه یک بخش Perl می‌تواند بر اساس آرگومان‌های خط پایانی آن بخش Perl، در رشته‌ها یا ثبات‌های عددی groff ذخیره شود.

اگر هیچ عملوندی داده نشود، یا اگر file برابر با “-” باشد، gperl جریان ورودی استاندارد را می‌خواند. یک آرگومان دوخط‌تیره (“--”) باعث می‌شود تمامی آرگومان‌های پس از آن، حتی اگر نام آن‌ها با خط تیره آغاز شود، به عنوان عملوندهای file تفسیر شوند. گزینه‌های -h و --help پیام نحوه استفاده را نمایش می‌دهند، در حالی که -v و --version اطلاعات نسخه را نمایش داده و همگی پس از آن خارج می‌شوند.

ناحیه‌های پرل (Perl regions)

بخش‌های Perl در فایل‌های groff میان دو درخواست .Perl با آرگومان‌های متفاوت محصور می‌شوند: یک دستور شروع‌کننده و یک دستور پایان‌بخش.

شروع حالت Perl

درخواست شروع Perl می‌تواند بدون آرگومان باشد، یا درخواستی باشد که عبارت start تنها آرگومان آن است.

.Perl
.Perl start

پایان دادن به حالت Perl بدون ذخیره‌سازی

یک خط دستور .Perl با آرگومانی غیر از start به یک بخش Perl در حال اجرا پایان می‌دهد. البته افزودن آرگومان stop منطقی خواهد بود؛ این کار امکان‌پذیر است، اما الزامی نیست.

.Perl stop
.Perl other_than_start

آرگومان other_than_start می‌تواند علاوه بر این به عنوان نام متغیر رشته‌ای groff برای ذخیره‌سازی استفاده شود — بخش بعدی را ببینید.

پایان دادن به حالت Perl همراه با ذخیره‌سازی

یک ویژگی مفید gperl ذخیره‌سازی یک یا چند نتیجه حاصل از حالت Perl است.

خروجی یک بخش Perl را می‌توان با استفاده از بکتیک‌های `...` دریافت کرد.

این برنامه تمام موارد چاپ‌شده در STDOUT (خروجی استاندارد معمول) توسط دستور print پرل را جمع‌آوری می‌کند. این خروجی شبه‌چاپی به دلیل شکست‌های خط چاپ‌شده با \n، می‌تواند شامل چند خط باشد. بدین ترتیب، خروجی حاصل از اجرای Perl باید در یک آرایه Perl ذخیره شود، با یک خط مجزا برای هر عضو آرایه.

این خروجی آرایه Perl می‌تواند توسط gperl در یکی از موارد زیر ذخیره شود:

رشته‌های groff: با ایجاد دستور groff به صورت .ds
ثبات‌های groff: با ایجاد دستور groff به صورت .nr

حالت‌های ذخیره‌سازی را می‌توان با آرگومان‌های دستور پایانی .Perl تعیین کرد. هر آرگومان .ds حالت را به رشته groff و هر آرگومان .nr حالت را به ثبات groff برای تمامی بخش‌های خروجی پس از آن تغییر می‌دهد.

به‌طور پیش‌فرض، تمامی خروجی‌ها به صورت رشته ذخیره می‌شوند، بنابراین .ds پیش از نخستین دستور .nr واقعاً مورد نیاز نیست. این امر با groff(7) سازگار است، چرا که هر خروجی می‌تواند به عنوان یک رشته groff ذخیره شود، در حالی که ثبات‌ها می‌توانند بسیار محدودکننده باشند.

در حالت رشته، برنامه gperl یک خط ذخیره‌سازی رشته groff تولید می‌کند:

.ds var_name content

در حالت ثبات دستور groff زیر تولید می‌شود:

.nr var_name content

در ادامه مجموعه‌های مختلف آرگومان‌ها را ارائه می‌دهیم. می‌توانید برای همگی، stop را به عنوان نخستین آرگومان اضافه کنید. ما این عنصر اضافی را حذف می‌کنیم.

.Perl .ds var_name: این دستور ۱ خط خروجی را با استفاده از دستورِ خودکار ایجادشده، در رشته groff با نام var_name ذخیره می‌کند:

.ds var_name output

.Perl var_name: اگر var_name مقداری غیر از start داشته باشد، معادل دستور قبلی است، چرا که حالت رشته‌ای با دستور .ds پیش‌فرض است.
.Perl var_name1 var_name2: این دستور ۲ خط خروجی را در نام‌های رشته groff به صورت var_name1 و var_name2 ذخیره می‌کند، زیرا حالت پیش‌فرض .ds فعال است، به طوری که به هیچ آرگومان .ds نیازی نیست. البته این معادل است با:

.Perl .ds var_name1 var_name2

و

.Perl .ds var_name1 .ds var_name2

.Perl .nr var_name1 varname2: هر دو متغیر را به عنوان متغیرهای ثبات ذخیره می‌کند. gperl دستورات زیر را تولید می‌کند:

.nr var_name1 output_line1
.nr var_name2 output_line2

.Perl .nr var_name1 .ds var_name2: آرگومان اول را به عنوان ثبات و آرگومان دوم را به عنوان رشته با دستورات زیر ذخیره می‌کند:

.nr var_name1 output_line1
.ds var_name2 output_line2

مثال‌ها (EXAMPLES)

یک بخش Perl احتمالی در یک فایل roff می‌تواند به این صورت باشد:

before
.Perl start
my $result = 'some data';
print $result;
.Perl stop .ds string_var
after

این دستور نتیجه ”some data” را در رشته roff به نام string_var ذخیره می‌کند، به طوری که خط زیر توسط gperl چاپ می‌شود:

.ds string_var some data

تا به عنوان ورودی برای اجرای بعدی groff مورد استفاده قرار گیرد.

یک بخش Perl با چند خروجی به شکل زیر است:

.Perl start
print ”first\n”;
print ”second line\n”;
print ”3\n”;
.Perl var1 var2 .nr var3

این کار ۳ خط چاپ‌شده را در ۳ متغیر groff شامل var1، var2 و var3 ذخیره می‌کند. بنابراین خطوط دستور groff زیر ایجاد می‌شوند:

.ds var1 first
.ds var2 second line
.nr var3 3

نویسندگان (AUTHORS)

gperl توسط Bernd Warken نوشته شده است.

همچنین ببینید (SEE ALSO)

صفحات راهنمای مرتبط با groff عبارتند از: groff(1), groff(7) و grog(1).

اسناد مرتبط با Perl عبارتند از: perl(1) و perl(7).