.TH PCRE2TEST 1 "22 August 2026" "PCRE2 10.48" .SH "نام (NAME)" pcre2test \- برنامه‌ای برای آزمایش عبارات باقاعده سازگار با پرل (Perl-compatible regular expressions). .SH "خلاصه دستور (SYNOPSIS)" .rs .sp .B pcre2test "[options] [input file [output file]]" .sp \fBpcre2test\fP یک برنامه آزمایشی برای کتابخانه‌های عبارات باقاعده PCRE2 است، اما می‌تواند برای آزمایش و کار تجربی با عبارات باقاعده نیز استفاده شود. این سند ویژگی‌های برنامه آزمایشی را شرح می‌دهد؛ برای جزئیات خود عبارات باقاعده، مستندات .\" HREF \fBpcre2pattern\fP .\" را ببینید. برای جزئیات فراخوانی توابع کتابخانه PCRE2 و گزینه‌های آن‌ها، مستندات .\" HREF \fBpcre2api\fP .\" را ببینید. .P ورودی \fBpcre2test\fP دنباله‌ای از الگوهای عبارات باقاعده و رشته‌های هدف (subject strings) برای تطبیق است. همچنین خطوط فرمانی برای تنظیم پیش‌فرض‌ها و کنترل برخی اقدامات ویژه وجود دارد. خروجی نتیجه هر تلاش برای تطبیق را نشان می‌دهد. اصلاح‌کننده‌ها (Modifiers) در خطوط فرمان خارجی یا داخلی، الگوها و خطوط رشته هدف، گزینه‌های توابع PCRE2 را تعیین کرده و نحوه پردازش رشته هدف و خروجی تولیدشده را کنترل می‌کنند. .P اصلاح‌کننده‌های مبهم و کم‌کاربرد زیادی وجود دارند که برخی از آن‌ها مشخصاً برای استفاده همراه با اسکریپت آزمایشی و فایل‌های داده توزیع‌شده به عنوان بخشی از PCRE2 طراحی شده‌اند. تمام اصلاح‌کننده‌ها در اینجا مستند شده‌اند، برخی بدون توجیه چندان، اما احتمال استفاده از بسیاری از آن‌ها جز در هنگام آزمایش کتابخانه‌ها کم است. . . .SH "کتابخانه‌های ۸ بیتی، ۱۶ بیتی و ۳۲ بیتی PCRE2 (PCRE2's 8-BIT, 16-BIT AND 32-BIT LIBRARIES)" .rs .sp نسخه‌های مختلفی از کتابخانه PCRE2 را می‌توان ساخت تا از رشته‌های نویسه‌ای کدگذاری‌شده در واحدهای کد (code units) ۸ بیتی، ۱۶ بیتی یا ۳۲ بیتی پشتیبانی کنند. یک، دو یا هر سه این کتابخانه‌ها می‌توانند به طور همزمان نصب شوند. برنامه \fBpcre2test\fP می‌تواند برای آزمایش همه این کتابخانه‌ها استفاده شود. با این حال، ورودی و خروجی خود برنامه همیشه در قالب ۸ بیتی است. هنگام آزمایش کتابخانه‌های ۱۶ بیتی یا ۳۲ بیتی، الگوها و رشته‌های هدف پیش از ارسال به توابع کتابخانه، به قالب ۱۶ بیتی یا ۳۲ بیتی تبدیل می‌شوند. نتایج برای خروجی دوباره به واحدهای کد ۸ بیتی تبدیل می‌شوند. .P در ادامه این سند، نام توابع و ساختارهای کتابخانه به شکل عمومی آورده شده است، برای مثال \fBpcre2_compile()\fP. نام‌های واقعی استفاده‌شده در کتابخانه‌ها بر حسب مورد دارای پسوند _8، _16 یا _32 هستند. . . .\" HTML .SH "کدگذاری ورودی (INPUT ENCODING)" .rs .sp ورودی \fBpcre2test\fP خط به خط پردازش می‌شود، یا با فراخوانی تابع \fBfgets()\fP از کتابخانه C یا از طریق کتابخانه \fBlibreadline\fP یا \fBlibedit\fP. در برخی محیط‌های Windows، نویسه ۲۶ (هگزادسیمال 1A) موجب پایان فوری فایل شده و داده دیگری خوانده نمی‌شود؛ بنابراین از این نویسه باید پرهیز شود مگر اینکه واقعاً این رفتار را بخواهید. .P ورودی با استفاده از توابع رشته‌ای C پردازش می‌شود، بنابراین نباید حاوی صفر باینری (binary zeros) باشد، حتی با اینکه در محیط‌های شبه یونیکس، تابع \fBfgets()\fP با هر بایتی به جز نویسه خط جدید به عنوان نویسه داده رفتار می‌کند. در صورت برخورد با صفر باینری، خطا ایجاد می‌شود. به طور پیش‌فرض، خطوط رشته هدف برای توالی‌های گریز با بک‌اسلش (backslash escapes) پردازش می‌شوند که گنجاندن هر مقدار داده‌ای را در رشته‌های ارسالی به کتابخانه برای تطبیق امکان‌پذیر می‌سازد. برای الگوها، قابلیتی برای تعیین برخی یا همه نویسه‌های ورودی ۸ بیتی به صورت جفت‌های هگزادسیمال وجود دارد که گنجاندن صفرهای باینری را ممکن می‌سازد. . . .SS "ورودی برای کتابخانه‌های ۱۶ بیتی و ۳۲ بیتی (Input for the 16-bit and 32-bit libraries)" .rs .sp هنگام آزمایش کتابخانه‌های ۱۶ بیتی یا ۳۲ بیتی، نیاز است که بتوان نقاط کد نویسه‌ای (character code points) بزرگتر از ۲۵۵ را در رشته‌های ارسالی به کتابخانه تولید کرد. برای خطوط رشته هدف و برخی الگوها، می‌توان از توالی‌های گریز بک‌اسلش استفاده کرد. علاوه بر این، هنگامی که اصلاح‌کننده \fButf\fP (بخش .\" HTML .\" "تنظیم گزینه‌های کامپایل" .\" در زیر را ببینید) تنظیم شده باشد، الگو و هر خط رشته هدف پس از آن به عنوان رشته‌های UTF-8 تفسیر شده و بر حسب مورد به UTF-16 یا UTF-32 ترجمه می‌شوند. .P برای آزمایش غیر UTF نویسه‌های عریض (wide characters)، می‌توان از اصلاح‌کننده \fButf8_input\fP استفاده کرد. این اصلاح‌کننده مانعة‌الجمع با \fButf\fP است و فقط در حالت ۱۶ بیتی یا ۳۲ بیتی مجاز است. این اصلاح‌کننده باعث می‌شود الگو و خطوط رشته هدف بعدی مطابق با تعریف اولیه (RFC 2279) به عنوان UTF-8 در نظر گرفته شوند که مقادیر نویسه‌ای تا 0x7fffffff را مجاز می‌داند. هر نویسه در یک واحد کد ۱۶ بیتی یا ۳۲ بیتی قرار می‌گیرد (در حالت ۱۶ بیتی، مقادیر بزرگتر از 0xffff باعث بروز خطا می‌شوند). .P کدگذاری UTF-8 (در تعریف اولیه آن) قادر به کدگذاری مقادیر بزرگتر از 0x7fffffff نیست، اما چنین مقادیری توسط کتابخانه ۳۲ بیتی قابل مدیریت هستند. هنگام آزمایش این کتابخانه در حالت غیر UTF با تنظیم \fButf8_input\fP، اگر پیش از هر نویسه، بایت 0xff قرار گیرد (که بایتی نامعتبر در UTF-8 است)، مقدار 0x80000000 به مقدار آن نویسه اضافه می‌شود. برای رشته‌های هدف، استفاده از توالی گریز ترجیح دارد. . . .SH "گزینه‌های خط فرمان (COMMAND LINE OPTIONS)" .rs .TP 10 \fB-8\fP اگر کتابخانه ۸ بیتی ساخته شده باشد، این گزینه باعث استفاده از آن می‌شود (این حالت پیش‌فرض است). اگر کتابخانه ۸ بیتی ساخته نشده باشد، این گزینه خطایی ایجاد می‌کند. .TP 10 \fB-16\fP اگر کتابخانه ۱۶ بیتی ساخته شده باشد، این گزینه باعث استفاده از آن می‌شود. اگر کتابخانه ۸ بیتی ساخته نشده باشد، این حالت پیش‌فرض است. اگر کتابخانه ۱۶ بیتی ساخته نشده باشد، این گزینه خطایی ایجاد می‌کند. .TP 10 \fB-32\fP اگر کتابخانه ۳۲ بیتی ساخته شده باشد، این گزینه باعث استفاده از آن می‌شود. اگر هیچ کتابخانه دیگری ساخته نشده باشد، این حالت پیش‌فرض است. اگر کتابخانه ۳۲ بیتی ساخته نشده باشد، این گزینه خطایی ایجاد می‌کند. .TP 10 \fB-ac\fP رفتار به گونه‌ای است که گویی هر الگو دارای اصلاح‌کننده \fBauto_callout\fP است، یعنی فراخوانی‌های خودکار (automatic callouts) را در هر الگوی کامپایل‌شده درج می‌کند. .TP 10 \fB-AC\fP مشابه \fB-ac\fP، اما علاوه بر آن به گونه‌ای رفتار می‌کند که گویی هر خط رشته هدف دارای اصلاح‌کننده \fBcallout_extra\fP است، یعنی اطلاعات اضافی حاصل از فراخوانی‌ها را نمایش می‌دهد. .TP 10 \fB-b\fP رفتار به گونه‌ای است که گویی هر الگو دارای اصلاح‌کننده \fBfullbincode\fP است؛ فرم باینری داخلی کامل الگو پس از کامپایل در خروجی چاپ می‌شود. .TP 10 \fB-C\fP شماره نسخه کتابخانه PCRE2 و تمام اطلاعات موجود درباره ویژگی‌های اختیاری گنجانده‌شده را در خروجی چاپ کرده و سپس با کد خروج صفر خارج می‌شود. سایر گزینه‌ها نادیده گرفته می‌شوند. اگر هر دو گزینه -C و -LM وجود داشته باشند، هر کدام که اول آمده باشد شناسایی می‌شود. .TP 10 \fB-C\fP \fIoption\fP اطلاعات مربوط به یک گزینه زمان ساخت (build-time option) خاص را در خروجی چاپ کرده، سپس خارج می‌شود. این قابلیت برای استفاده در اسکریپت‌هایی مانند \fBRunTest\fP در نظر گرفته شده است. گزینه‌های زیر مقدار را در خروجی چاپ کرده و کد خروج را طبق توضیحات تنظیم می‌کنند: .sp linksize اندازه پیوند داخلی پیکربندی‌شده (۲، ۳ یا ۴) کد خروج برابر با اندازه پیوند تنظیم می‌شود newline تنظیم پیش‌فرض خط جدید: CR, LF, CRLF, ANYCRLF, ANY یا NUL کد خروج همیشه ۰ است bsr تنظیم پیش‌فرض برای آنچه \eR با آن تطبیق می‌یابد: ANYCRLF یا ANY کد خروج همیشه ۰ است .sp گزینه‌های زیر برای true مقدار ۱ یا برای false مقدار ۰ را در خروجی چاپ کرده و کد خروج را روی همان مقدار تنظیم می‌کنند: .sp backslash-C از \eC پشتیبانی می‌شود (قفل نشده است) ebcdic برای محیط EBCDIC کامپایل شده است ebcdic-io اگر PCRE2 برای EBCDIC کامپایل شده باشد، آیا ورودی و خروجی pcre2test به صورت EBCDIC است یا ASCII ebcdic-nl25 اگر PCRE2 برای EBCDIC کامپایل شده باشد، آیا NL (= LF) مقدار 0x25 است (در غیر این صورت 0x15 است که پیش‌فرض می‌باشد) jit پشتیبانی JIT (just-in-time) در دسترس است pcre2-16 کتابخانه ۱۶ بیتی ساخته شده است pcre2-32 کتابخانه ۳۲ بیتی ساخته شده است pcre2-8 کتابخانه ۸ بیتی ساخته شده است unicode پشتیبانی یونیکد (Unicode) در دسترس است .sp توجه داشته باشید که در دسترس بودن پشتیبانی JIT در کتابخانه تضمین نمی‌کند که واقعاً قابل استفاده باشد، زیرا در برخی محیط‌ها قادر به تخصیص حافظه اجرایی نیست. گزینه "jitusable" اطلاعات دقیق‌تری ارائه می‌دهد و یکی از مقادیر زیر را برمی‌گرداند: .sp 0 پشتیبانی JIT در دسترس و قابل استفاده است 1 پشتیبانی JIT در دسترس است اما نمی‌تواند حافظه اجرایی تخصیص دهد 2 پشتیبانی JIT در دسترس نیست 3 مقدار بازگشتی غیرمنتظره از فراخوانی آزمایشی به \fBpcre2_jit_compile()\fP .sp اگر گزینه‌ای ناشناخته داده شود، پیام خطا چاپ شده و کد خروج ۰ خواهد بود. .TP 10 \fB--colo[u]r[=]\fP با \fBauto\fP، اگر خروجی به یک ترمینال باشد، رنگی می‌شود. با \fBalways\fP (یا در صورت عدم ارائه مشخصه) خروجی کدهای رنگی ANSI اجبار می‌شود و با \fBnever\fP سرکوب می‌گردد. اگر هیچ گزینه رنگی مشخص نشود، مقدار پیش‌فرض \fBauto\fP است، مگر اینکه متغیر محیطی NO_COLOR تعریف شده و غیرخالی باشد. .TP 10 \fB-d\fP رفتار به گونه‌ای است که گویی هر الگو دارای اصلاح‌کننده \fBdebug\fP است؛ فرم داخلی و اطلاعات مربوط به الگوی کامپایل‌شده پس از کامپایل در خروجی چاپ می‌شود؛ گزینه \fB-d\fP معادل \fB-b -i\fP است. .TP 10 \fB-dfa\fP رفتار به گونه‌ای است که گویی هر خط رشته هدف دارای اصلاح‌کننده \fBdfa\fP است؛ تطبیق به جای تابع پیش‌فرض \fBpcre2_match()\fP با استفاده از تابع \fBpcre2_dfa_match()\fP انجام می‌شود. .TP 10 \fB-E\fP اجرا در حالت "فقط پیش‌پردازش" (مشابه "gcc -E"). دستورات "#if ... #endif" پردازش شده و سایر خطوط عیناً چاپ می‌شوند. .TP 10 \fB-error\fP \fInumber[,number,...]\fP تابع \fBpcre2_get_error_message()\fP را برای هر یک از شماره‌های خطای موجود در فهرست جداشده با کاما فراخوانی کرده، پیام‌های حاصل را در خروجی استاندارد نمایش می‌دهد و سپس با کد خروج صفر خارج می‌شود. شماره‌ها می‌توانند مثبت یا منفی باشند. این یک امکان رفاهی برای نگه‌دارندگان PCRE2 است. .TP 10 \fB-help\fP خلاصه‌ای کوتاه از این گزینه‌ها را در خروجی چاپ کرده و سپس خارج می‌شود. .TP 10 \fB-i\fP رفتار به گونه‌ای است که گویی هر الگو دارای اصلاح‌کننده \fBinfo\fP است؛ اطلاعات مربوط به الگوی کامپایل‌شده پس از کامپایل ارائه می‌شود. .TP 10 \fB-jit\fP رفتار به گونه‌ای است که گویی هر خط الگو دارای اصلاح‌کننده \fBjit\fP است؛ پس از کامپایل موفقیت‌آمیز، هر الگو در صورت در دسترس بودن به کامپایلر JIT ارسال می‌شود. .TP 10 \fB-jitfast\fP رفتار به گونه‌ای است که گویی هر خط الگو دارای اصلاح‌کننده \fBjitfast\fP است؛ پس از کامپایل موفقیت‌آمیز، هر الگو در صورت در دسترس بودن به کامپایلر JIT ارسال شده و هر خط رشته هدف از طریق "مسیر سریع" (fast path) مستقیماً به تطبیق‌دهنده JIT ارسال می‌شود. .TP 10 \fB-jitverify\fP رفتار به گونه‌ای است که گویی هر خط الگو دارای اصلاح‌کننده \fBjitverify\fP است؛ پس از کامپایل موفقیت‌آمیز، هر الگو در صورت در دسترس بودن به کامپایلر JIT ارسال شده و استفاده از JIT برای تطبیق اعتبارسنجی می‌شود. .TP 10 \fB-LM\fP فهرست کردن اصلاح‌کننده‌ها: فهرستی از اصلاح‌کننده‌های موجود الگو و رشته هدف را در خروجی استاندارد نوشته و سپس با کد خروج صفر خارج می‌شود. سایر گزینه‌ها نادیده گرفته می‌شوند. اگر هر دو گزینه -C و هر یک از گزینه‌های -Lx وجود داشته باشند، هر کدام که اول آمده باشد شناسایی می‌شود. .TP 10 \fB-LP\fP فهرست کردن ویژگی‌ها: فهرستی از ویژگی‌های شناخته‌شده یونیکد (Unicode properties) را در خروجی استاندارد نوشته و سپس با کد خروج صفر خارج می‌شود. سایر گزینه‌ها نادیده گرفته می‌شوند. اگر هر دو گزینه -C و هر یک از گزینه‌های -Lx وجود داشته باشند، هر کدام که اول آمده باشد شناسایی می‌شود. .TP 10 \fB-LS\fP فهرست کردن خط‌ها/اسکریپت‌ها: فهرستی از نام‌های خطوط شناخته‌شده یونیکد (Unicode scripts) را در خروجی استاندارد نوشته و سپس با کد خروج صفر خارج می‌شود. سایر گزینه‌ها نادیده گرفته می‌شوند. اگر هر دو گزینه -C و هر یک از گزینه‌های -Lx وجود داشته باشند، هر کدام که اول آمده باشد شناسایی می‌شود. .TP 10 \fB-malloc\fP آزمودن شکست‌های malloc()؛ ابتدا با شمارش تعداد فراخوانی‌های انجام‌شده به malloc در طول کامپایل و تطبیق الگو، سپس اجرای مجدد کامپایل و تطبیق به همان تعداد دفعات، همراه با اعمال شکست در هر فراخوانی malloc(). .TP 10 \fB-pattern\fP \fImodifier-list\fP رفتار به گونه‌ای است که گویی هر خط الگو حاوی اصلاح‌کننده‌های داده‌شده است. .TP 10 \fB-q\fP شماره نسخه \fBpcre2test\fP را در ابتدای اجرا چاپ نمی‌کند. .TP 10 \fB-S\fP \fIsize\fP در سیستم‌های شبه یونیکس، اندازه پشته زمان اجرا (run-time stack) را به میزان \fIsize\fP مبی‌بایت (واحدهای 1024*1024 بایت) تنظیم می‌کند. .TP 10 \fB-subject\fP \fImodifier-list\fP رفتار به گونه‌ای است که گویی هر خط رشته هدف حاوی اصلاح‌کننده‌های داده‌شده است. .TP 10 \fB-t\fP هر کامپایل و تطبیق را بارها با یک زمان‌سنج اجرا کرده و زمان‌های حاصل را به ازای هر کامپایل یا تطبیق در خروجی چاپ می‌کند. هنگام استفاده از JIT، زمان‌های جداگانه‌ای برای کامپایل اولیه و کامپایل JIT ارائه می‌شود. می‌توانید با قرار دادن یک عدد پس از \fB-t\fP (به عنوان یک مورد جداگانه در خط فرمان)، تعداد تکرارها برای زمان‌سنجی را کنترل کنید. برای مثال، "-t 1000" تعداد ۱۰۰۰ بار تکرار می‌کند. حالت پیش‌فرض ۵۰۰٬۰۰۰ بار تکرار است. .TP 10 \fB-tm\fP مشابه \fB-t\fP است به جز اینکه فقط فاز تطبیق را زمان‌سنجی می‌کند، نه فاز کامپایل را. .TP 10 \fB-T\fP \fB-TM\fP این گزینه‌ها مانند \fB-t\fP و \fB-tm\fP عمل می‌کنند، اما علاوه بر آن در پایان اجرا، کل زمان‌های صرف‌شده برای تمام کامپایل‌ها و تطبیق‌ها را در خروجی چاپ می‌کنند. .TP 10 \fB-unittest\fP مجموعه‌ای ثابت از آزمایش‌های اضافی API مربوط به PCRE2 را که با فایل‌های ورودی آزمایشی هدایت نمی‌شوند اجرا کرده و سپس خارج می‌شود. .TP 10 \fB-version\fP شماره نسخه PCRE2 را در خروجی چاپ کرده و سپس خارج می‌شود. . . .SH "توضیحات (DESCRIPTION)" .rs .sp اگر به \fBpcre2test\fP دو آرگومان نام فایل داده شود، از فایل اول خوانده و در فایل دوم می‌نویسد. اگر نام اول "-" باشد، ورودی از ورودی استاندارد (stdin) گرفته می‌شود. اگر به \fBpcre2test\fP فقط یک آرگومان داده شود، از آن فایل خوانده و در خروجی استاندارد (stdout) می‌نویسد. در غیر این صورت، از stdin خوانده و در stdout می‌نویسد. .P هنگام ساخت \fBpcre2test\fP، یک گزینه پیکربندی می‌تواند مشخص کند که این برنامه باید با کتابخانه \fBlibreadline\fP یا \fBlibedit\fP پیوند (link) داده شود. در این صورت، اگر ورودی از یک ترمینال باشد، با استفاده از تابع \fBreadline()\fP خوانده می‌شود. این کار امکانات ویرایش خط و تاریخچه (history) را فراهم می‌کند. خروجی گزینه \fB-help\fP مشخص می‌کند که آیا از \fBreadline()\fP استفاده خواهد شد یا خیر. .P این برنامه هر تعداد آزمایش را مدیریت می‌کند که هر کدام شامل مجموعه‌ای از خطوط ورودی است. هر مجموعه با یک الگوی عبارت باقاعده شروع می‌شود و به دنبال آن هر تعداد خط رشته هدف برای تطبیق با آن الگو قرار می‌گیرد. در بین مجموعه‌های داده‌های آزمایشی، خطوط فرمانی که با # شروع می‌شوند ممکن است ظاهر شوند. این قالب فایل با برخی محدودیت‌ها، توسط اسکریپت \fBperltest.sh\fP که همراه با PCRE2 توزیع شده نیز قابل پردازش است تا به عنوان ابزاری برای بررسی یکسان بودن رفتار PCRE2 و Perl به کار رود. برای مشخصات فنی \fBperltest.sh\fP، توضیحات نزدیک به ابتدای آن را ببینید. همچنین دستور #perltest در زیر را ببینید. .P هنگامی که ورودی از ترمینال باشد، \fBpcre2test\fP برای هر خط ورودی اعلان (prompt) نمایش می‌دهد؛ با استفاده از "re>" برای الگوهای عبارت باقاعده و "data>" برای خطوط رشته هدف. خطوط فرمانی که با # شروع می‌شوند تنها در پاسخ به اعلان "re>" قابل ورود هستند. .P هر خط رشته هدف به صورت جداگانه و مستقل تطبیق داده می‌شود. اگر می‌خواهید تطبیق‌های چندخطی انجام دهید، باید از توالی گریز \en (یا \er یا \er\en و غیره، بسته به تنظیم خط جدید) در یک خط ورودی واحد برای کدگذاری توالی‌های خط جدید استفاده کنید. هیچ محدودیتی در طول خطوط رشته هدف وجود ندارد؛ بافر ورودی در صورت کوچک بودن به طور خودکار افزایش می‌یابد. ویژگی‌های تکرار (replication) وجود دارند که تولید خطوط الگوی تکراری طولانی یا رشته‌های هدف را بدون نیاز به ارائه صریح آن‌ها ممکن می‌سازند. .P یک خط خالی یا پایان فایل نشان‌دهنده پایان خطوط رشته هدف برای یک آزمایش است؛ در این نقطه در صورت وجود ورودی‌های بیشتر برای خواندن، یک الگوی جدید یا خط فرمان انتظار می‌رود. . . .SH "خطوط فرمان (COMMAND LINES)" .rs .sp در بین مجموعه‌های داده‌های آزمایشی، خطی که با # شروع شود به عنوان یک خط فرمان تفسیر می‌شود. اگر اولین نویسه با فاصله یا علامت تعجب دنبال شود، با آن خط به عنوان یک توضیح (comment) برخورد شده و نادیده گرفته می‌شود. در غیر این صورت، دستورات زیر شناخته می‌شوند: .sp #forbid_utf .sp الگوهای بعدی به طور خودکار گزینه‌های PCRE2_NEVER_UTF و PCRE2_NEVER_UCP را تنظیم‌شده خواهند داشت که استفاده از گزینه‌های PCRE2_UTF و PCRE2_UCP و استفاده از (*UTF) و (*UCP) را در ابتدای الگوها قفل و مسدود می‌کند. این دستور همچنین در صورتی که الگوی بعدی حاوی هر گونه رخداد \eP، \ep یا \eX باشد که در صورت عدم تنظیم PCRE2_UTF همچنان پشتیبانی می‌شوند اما نیازمند گنجانده شدن پشتیبانی از ویژگی‌های یونیکد در کتابخانه هستند، موجب خطا می‌شود. .P این یک محافظ تحریک (trigger guard) است که در فایل‌های آزمایشی استفاده می‌شود تا اطمینان حاصل شود که آزمایش‌های UTF یا ویژگی‌های یونیکد به طور تصادفی به فایل‌هایی که در هنگام عدم وجود پشتیبانی یونیکد در کتابخانه استفاده می‌شوند، اضافه نشوند. تنظیم PCRE2_NEVER_UTF و PCRE2_NEVER_UCP به عنوان پیش‌فرض را می‌توان با استفاده از \fB#pattern\fP نیز به دست آورد؛ تفاوت در این است که \fB#forbid_utf\fP را نمی‌توان لغو کرد و گزینه‌های خودکار در اطلاعات الگو نمایش داده نمی‌شوند تا از شلوغ شدن خروجی آزمایشی جلوگیری شود. .sp #load .sp این دستور برای بارگذاری مجموعه‌ای از الگوهای از پیش کامپایل‌شده از یک فایل استفاده می‌شود، همان‌طور که در بخش "ذخیره و بازیابی الگوهای کامپایل‌شده" .\" HTML .\" در زیر شرح داده شده است. .\" .sp #loadtables .sp این دستور برای بارگذاری مجموعه‌ای از جدول‌های نویسه‌ای باینری استفاده می‌شود که با تعیین‌کننده tables=3 قابل دسترسی هستند. چنین جدول‌هایی را می‌توان توسط برنامه \fBpcre2_dftables\fP با گزینه -b ایجاد کرد. .sp #newline_default [] .sp هنگام ساخت PCRE2، می‌توان یک قرارداد پیش‌فرض برای خط جدید مشخص کرد. این قرارداد تعیین می‌کند کدام نویسه‌ها و/یا جفت نویسه‌ها به عنوان نشان‌دهنده خط جدید در یک الگو یا رشته هدف شناخته شوند. این پیش‌فرض را می‌توان هنگام کامپایل یک الگو بازنویسی کرد. فایل‌های آزمایشی استاندارد حاوی آزمایش‌هایی از قراردادهای مختلف خط جدید هستند، اما اکثر آزمایش‌ها انتظار دارند که به طور پیش‌فرض یک نویسه linefeed تکی به عنوان خط جدید شناخته شود. بدون اقدام ویژه، در صورتی که PCRE2 با CR یا CRLF به عنوان خط جدید پیش‌فرض کامپایل شده باشد، آزمایش‌ها شکست خواهند خورد. .P دستور #newline_default فهرستی از انواع خط جدید (newline) را مشخص می‌کند که به‌عنوان پیش‌فرض قابل قبول هستند. این انواع باید یکی از موارد CR، LF، CRLF، ANYCRLF، ANY یا NUL (با حروف بزرگ یا کوچک) باشند؛ برای مثال: .sp #newline_default LF Any anyCRLF .sp اگر خط جدید پیش‌فرض در فهرست باشد، این دستور هیچ تاثیری ندارد. در غیر این صورت، به‌جز هنگام آزمایش POSIX API، یک تغییردهندهٔ \fBnewline\fP که اولین قرارداد خط جدید در فهرست را مشخص می‌کند (LF در مثال بالا)، به هر الگویی که از قبل تغییردهندهٔ \fBnewline\fP نداشته باشد افزوده می‌شود. اگر فهرست خط جدید خالی باشد، این ویژگی غیرفعال می‌شود. این دستور در تعدادی از فایل‌های ورودی آزمون استاندارد وجود دارد. .P هنگام آزمایش POSIX API راهی برای بازنویسی قرارداد خط جدید پیش‌فرض وجود ندارد، اگرچه تنظیم قرارداد خط جدید از درون خود الگو امکان‌پذیر است. اگر از تغییردهندهٔ \fBposix\fP یا \fBposix_nosub\fP در شرایطی استفاده شود که \fB#newline_default\fP مقداری پیش‌فرض را برای API غیرپازیکس تنظیم کند، یک هشدار صادر می‌شود. .sp #pattern .sp این دستور یک فهرست پیش‌فرض از تغییردهنده‌ها را تنظیم می‌کند که برای تمام الگوهای بعدی اعمال می‌شود. تغییردهنده‌های روی یک الگو می‌توانند این تنظیمات را تغییر دهند. .sp #perltest .sp این خط در فایل‌های آزمونی استفاده می‌شود که توسط \fBperltest.sh\fP نیز قابل پردازش هستند تا تأیید شود Perl همان نتایج PCRE2 را تولید می‌کند. آزمون‌های بعدی برای استفاده از ویژگی‌های \fBpcre2test\fP که با اسکریپت \fBperltest.sh\fP ناسازگار هستند بررسی می‌شوند. .P الگوها باید از '/' به‌عنوان جداکنندهٔ (delimiter) خود استفاده کنند، و تنها تغییردهنده‌های خاصی پشتیبانی می‌شوند. خطوط توضیحات، دستورات #pattern، و دستورات #subject که "mark" را تنظیم یا لغو می‌کنند شناسایی شده و بر اساس آن‌ها اقدام می‌شود. دستورات #perltest، #forbid_utf و #newline_default که در فایل‌های مربوطهٔ pcre2test مورد نیاز هستند، بدون پیام نادیده گرفته می‌شوند. تمام خطوط فرمان دیگر نادیده گرفته می‌شوند، اما یک پیام هشدار صادر می‌کنند. دستور \fB#perltest\fP به شناسایی آزمون‌هایی کمک می‌کند که به اشتباه در فایل نادرست قرار گرفته‌اند یا از جداکنندهٔ اشتباه استفاده می‌کنند. برای جزئیات بیشتر دربارهٔ اسکریپت \fBperltest.sh\fP، توضیحات موجود در آن را ببینید. .sp #pop [] #popcopy [] .sp این دستورات برای دستکاری پشتهٔ الگوهای کامپایل‌شده استفاده می‌شوند، همان‌طور که در بخش .\" HTML .\" "ذخیره و بازیابی الگوهای کامپایل‌شده" .\" در زیر شرح داده شده است. .\" .sp #save .sp این دستور برای ذخیرهٔ مجموعه‌ای از الگوهای کامپایل‌شده در یک فایل استفاده می‌شود، همان‌طور که در بخش .\" HTML .\" "ذخیره و بازیابی الگوهای کامپایل‌شده" .\" در زیر شرح داده شده است. .\" .sp #subject .sp این دستور یک فهرست پیش‌فرض از تغییردهنده‌ها را تنظیم می‌کند که برای تمام خطوط هدف (subject) بعدی اعمال می‌شود. تغییردهنده‌های روی یک خط هدف می‌توانند این تنظیمات را تغییر دهند. .sp #if CONDITION ... #endif .sp اگر CONDITION درست (true) باشد، دستور چاپ می‌شود و محتویات آن طبق روال معمول پردازش می‌گردد، از جمله چاپ خطوط فرمان در خروجی. اگر CONDITION نادرست (false) باشد، تمام خطوط بین "#if" و "#endif" نادیده گرفته شده و چاپ نمی‌شوند. شرط CONDITION می‌تواند هر یک از شرایطی باشد که با گزینهٔ خط فرمان "-C" آزمایش می‌شوند و کد خروج pcre2test را روی یک مقدار بولی تنظیم می‌کنند. شرط CONDITION همچنین ممکن است با "!" آغاز شود. . . .SH "نحو تغییردهنده‌ها (MODIFIER SYNTAX)" .rs .sp فهرست‌های تغییردهنده هم برای خطوط الگو و هم برای خطوط هدف (subject) استفاده می‌شوند. آیتم‌های موجود در فهرست با کاما و به دنبال آن فاصلهٔ خالی اختیاری از یکدیگر جدا می‌شوند. فاصله‌های خالی انتهایی در یک فهرست تغییردهنده نادیده گرفته می‌شوند. برخی از تغییردهنده‌ها ممکن است هم برای الگوها و هم برای خطوط هدف مشخص شوند، در حالی که برخی دیگر تنها برای یکی از آن‌ها معتبر هستند. هر تغییردهنده یک نام طولانی دارد، برای مثال "anchored"، و برخی از آن‌ها باید با علامت مساوی و یک مقدار همراه باشند، برای مثال "offset=12". مقادیر نمی‌توانند شامل نویسهٔ کاما باشند، اما ممکن است شامل فاصله باشند. تغییردهنده‌هایی که مقدار نمی‌پذیرند می‌توانند با علامت منفی آغاز شوند تا تنظیم قبلی را غیرفعال کنند. .P چند مورد از تغییردهنده‌های رایج‌تر را می‌توان به‌صورت تک‌حرفی نیز مشخص کرد، برای مثال "i" برای "caseless". در مستندات، به پیروی از قرارداد Perl، برای وضوح بیشتر این موارد با یک اسلش نوشته می‌شوند ("تغییردهندهٔ /i"). تغییردهنده‌های اختصاری همگی باید در اولین آیتم از فهرست تغییردهنده‌ها پشت سر هم ادغام شوند. اگر اولین آیتم به‌عنوان یک نام طولانی تغییردهنده شناخته نشود، به‌صورت توالی این حروف اختصاری تفسیر می‌شود. برای مثال: .sp /abc/ig,newline=cr,jit=3 .sp این یک خط الگو است که فهرست تغییردهنده‌های آن با دو تغییردهندهٔ تک‌حرفی (/i و /g) آغاز می‌شود. تغییردهنده‌های اختصاری با حروف کوچک همان مواردی هستند که در Perl استفاده می‌شوند. . . .SH "نحو الگو (PATTERN SYNTAX)" .rs .sp یک خط الگو باید با یکی از نویسه‌های زیر آغاز شود (نمادهای رایج، به استثنای فرانویسه‌های الگو): .sp / ! " ' ` - = _ : ; , % & @ ~ .sp این نویسه به‌عنوان جداکنندهٔ (delimiter) الگو تفسیر می‌شود. یک عبارت باقاعده ممکن است در چندین خط ورودی ادامه یابد، که در این صورت نویسه‌های خط جدید درون آن گنجانده می‌شوند. گنجاندن جداکننده به‌صورت لفظی (literal) درون الگو با اسکیپ کردن آن توسط بک‌اسلش امکان‌پذیر است، برای مثال: .sp /abc\e/def/ .sp اگر این کار را انجام دهید، نویسهٔ گریز و جداکننده بخشی از الگو را تشکیل می‌دهند، اما از آنجا که جداکننده‌ها همگی غیرالفبایی-عددی هستند، گنجاندن بک‌اسلش تأثیری در تفسیر الگو نخواهد داشت. با این حال، توجه داشته باشید که این ترفند درون محدوده‌بندی لفظی \eQ...\eE کار نمی‌کند زیرا خود بک‌اسلش به‌عنوان یک نویسهٔ لفظی تفسیر خواهد شد. اگر بلافاصله پس از جداکنندهٔ پایانی یک بک‌اسلش بیاید، برای مثال: .sp /abc/\e .sp یک بک‌اسلش به انتهای الگو اضافه می‌شود. این کار برای فراهم کردن راهی جهت آزمایش شرایط خطایی انجام می‌شود که در صورت پایان یافتن الگو با یک بک‌اسلش رخ می‌دهد، زیرا: .sp /abc\e/ .sp به‌عنوان اولین خط از الگویی تفسیر می‌شود که با "abc/" آغاز می‌گردد، و باعث می‌شود pcre2test خط بعدی را به‌عنوان ادامهٔ عبارت باقاعده بخواند. .P یک الگو می‌تواند با یک فهرست تغییردهنده دنبال شود (جزئیات در زیر). . . .SH "نحو خط هدف (SUBJECT LINE SYNTAX)" .rs .sp پیش از آنکه هر خط هدف (subject) به \fBpcre2_match()\fP، \fBpcre2_dfa_match()\fP یا \fBpcre2_jit_match()\fP ارسال شود، فاصله‌های خالی ابتدا و انتهای آن حذف شده و خط برای یافتن توالی‌های گریز بک‌اسلش بررسی می‌گردد، مگر اینکه تغییردهندهٔ \fBsubject_literal\fP برای الگو تنظیم شده باشد. موارد زیر روشی برای کدگذاری نویسه‌های غیرقابل‌چاپ به شکلی قابل مشاهده فراهم می‌کنند: .sp \ea هشدار (BEL, \ex07) \eb پس‌بر / Backspace (\ex08) \ee اسکیپ (\ex27) \ef برگه‌خور / Form feed (\ex0c) \en خط جدید (\ex0a) \eN{U+hh...} نویسهٔ یونیکد (هر تعداد رقم هگزادسیمال) \er بازگشت به ابتدای سطر / Carriage return (\ex0d) \et تب (\ex09) \ev تب عمودی (\ex0b) \eddd عدد هشت‌هشتی (تا ۳ رقم هشت‌هشتی)؛ نمایانگر یک نقطه کد واحد مگر آنکه در کتابخانهٔ ۸ بیتی بزرگتر از ۲۵۵ باشد \eo{dd...} عدد هشت‌هشتی (هر تعداد رقم هشت‌هشتی) نمایانگر یک نویسه در حالت UTF یا یک نقطه کد \exhh بایت هگزادسیمال (تا ۲ رقم هگزادسیمال) \ex{hh...} عدد هگزادسیمال (تا ۸ رقم هگزادسیمال) نمایانگر یک نویسه در حالت UTF یا یک نقطه کد .sp فراخوانی \eN{U+hh...} یا \ex{hh...} نیازی به استفاده از تغییردهندهٔ \fButf\fP روی الگو ندارد و همیشه شناخته می‌شود. هر تعداد رقم هگزادسیمال می‌تواند درون آکولادها قرار گیرد؛ مقادیر نامعتبر پیام خطا صادر می‌کنند، اما هنگام استفاده از \eN{U+hh...} با برخی نویسه‌های یونیکد نامعتبر، به جای خطا با یک هشدار پذیرفته می‌شوند. .P توجه داشته باشید که حتی در حالت UTF-8، عبارت \exhh (و بسته به اندازه، \eddd) یک بایت را توصیف می‌کند نه یک نویسه؛ این امر ساخت دنباله‌های نامعتبر UTF-8 را برای اهداف آزمایشی امکان‌پذیر می‌سازد. از سوی دیگر، \ex{hh...} در حالت UTF-8 به‌عنوان یک نویسهٔ UTF-8 تفسیر می‌شود، و تنها در صورتی بیش از یک بایت تولید می‌کند که مقدار آن بزرگتر از ۱۲۷ باشد. برای جلوگیری از ابهام، ترجیح داده می‌شود هنگام توصیف نویسه‌ها از \eN{U+hh...} استفاده شود. هنگام آزمایش کتابخانهٔ ۸ بیتی در حالتی غیر از UTF-8، عبارت \ex{hh} برای مقادیری که در آن جای می‌گیرند یک بایت تولید می‌کند و برای مقادیر بزرگتر باعث بروز خطا می‌شود. .P هنگام آزمایش کتابخانهٔ ۱۶ بیتی در حالتی غیر از UTF-16، تمام مقادیر ۴ رقمی \ex{hhhh} پذیرفته می‌شوند. این امر ساخت دنباله‌های نامعتبر UTF-16 را برای اهداف آزمایشی امکان‌پذیر می‌سازد. .P هنگام آزمایش کتابخانهٔ ۳۲ بیتی در حالتی غیر از UTF-32، تمام مقادیر ۴ تا ۸ رقمی \ex{...} پذیرفته می‌شوند. این امر ساخت دنباله‌های نامعتبر UTF-32 را برای اهداف آزمایشی امکان‌پذیر می‌سازد. .P یک توالی بک‌اسلش ویژه وجود دارد که تکرار یک یا چند نویسه را مشخص می‌کند: .sp \e[]{} .sp این امر آزمایش رشته‌های طولانی را بدون نیاز به ارائه صریح آن‌ها در فایل ممکن می‌سازد. برای مثال: .sp \e[abc]{4} .sp به "abcabcabcabc" تبدیل می‌شود. این ویژگی از حالت تودرتو پشتیبانی نمی‌کند. برای گنجاندن یک براکت بسته در میان نویسه‌ها، آن را به‌صورت \ex5D کدگذاری کنید. .P یک بک‌اسلش به همراه علامت مساوی، پایان رشتهٔ هدف و آغاز یک فهرست تغییردهنده را نشان می‌دهد. برای مثال: .sp abc\e=notbol,notempty .sp اگر رشتهٔ هدف خالی باشد و پس از \e= فاصلهٔ خالی بیاید، خط به‌عنوان خط توضیحات در نظر گرفته شده و برای تطبیق استفاده نمی‌شود. برای مثال: .sp \e= This is a comment. abc\e= This is an invalid modifier list. .sp یک بک‌اسلش که به دنبال آن هر نویسهٔ غیرالفبایی-عددی دیگری بیاید، صرفاً آن نویسه را اسکیپ می‌کند. بک‌اسلش به همراه هر چیز دیگری باعث ایجاد خطا می‌شود. با این حال، اگر آخرین نویسه در خط بک‌اسلش باشد (و هیچ فهرست تغییردهنده‌ای وجود نداشته باشد)، نادیده گرفته می‌شود. این روشی برای ارسال یک خط خالی به‌عنوان داده فراهم می‌کند، زیرا یک خط خالی واقعی ورودی داده را خاتمه می‌دهد. .P اگر تغییردهندهٔ \fBsubject_literal\fP برای یک الگو تنظیم شده باشد، تمام خطوط هدف بعدی به‌صورت لفظی (literal) و بدون هیچ‌گونه پردازش ویژه برای بک‌اسلش‌ها در نظر گرفته می‌شوند. هیچ تکراری امکان‌پذیر نیست و هرگونه تغییردهندهٔ هدف باید به‌عنوان پیش‌فرض توسط دستور \fB#subject\fP تنظیم شود. . . .SH "تغییردهنده‌های الگو (PATTERN MODIFIERS)" .rs .sp انواع مختلفی از تغییردهنده‌ها وجود دارند که می‌توانند در خطوط الگو ظاهر شوند. به جز موارد ذکرشده در زیر، آن‌ها می‌توانند در دستورات \fB#pattern\fP نیز استفاده شوند. فهرست تغییردهنده‌های یک الگو می‌تواند به تغییردهنده‌های پیش‌فرضی که توسط دستور قبلی \fB#pattern\fP تنظیم شده‌اند، اضافه شود یا آن‌ها را بازنویسی کند. . . .\" HTML .SS "تنظیم گزینه‌های کامپایل (Setting compilation options)" .rs .sp تغییردهنده‌های زیر گزینه‌هایی را برای \fBpcre2_compile()\fP تنظیم می‌کنند. بیشتر آن‌ها بیت‌هایی را در آرگومان گزینه‌های آن تابع تنظیم می‌کنند، اما مواردی که نام آن‌ها با PCRE2_EXTRA آغاز می‌شود، گزینه‌های اضافه‌ای هستند که در زمینهٔ کامپایل (compile context) تنظیم می‌شوند. برخی از این گزینه‌ها اختصارات تک‌حرفی دارند. رفتار ویژه‌ای برای /x وجود دارد: اگر یک x دوم وجود داشته باشد، همانند Perl مقدار PCRE2_EXTENDED به PCRE2_EXTENDED_MORE تبدیل می‌شود. حضور x سوم، گزینهٔ PCRE2_EXTENDED را نیز اضافه می‌کند، اگرچه این کار تفاوتی در رفتار \fBpcre2_compile()\fP ایجاد نمی‌کند. برای شرح اثرات این گزینه‌ها، مستندات .\" HREF \fBpcre2api\fP .\" را ببینید. .sp allow_empty_class تنظیم PCRE2_ALLOW_EMPTY_CLASS allow_lookaround_bsk تنظیم PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK allow_surrogate_escapes تنظیم PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES alt_bsux تنظیم PCRE2_ALT_BSUX alt_circumflex تنظیم PCRE2_ALT_CIRCUMFLEX alt_extended_class تنظیم PCRE2_ALT_EXTENDED_CLASS alt_verbnames تنظیم PCRE2_ALT_VERBNAMES anchored تنظیم PCRE2_ANCHORED /a ascii_all تنظیم تمام گزینه‌های ASCII ascii_bsd تنظیم PCRE2_EXTRA_ASCII_BSD ascii_bss تنظیم PCRE2_EXTRA_ASCII_BSS ascii_bsw تنظیم PCRE2_EXTRA_ASCII_BSW ascii_digit تنظیم PCRE2_EXTRA_ASCII_DIGIT ascii_posix تنظیم PCRE2_EXTRA_ASCII_POSIX auto_callout تنظیم PCRE2_AUTO_CALLOUT bad_escape_is_literal تنظیم PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL /i caseless تنظیم PCRE2_CASELESS /r caseless_restrict تنظیم PCRE2_EXTRA_CASELESS_RESTRICT dollar_endonly تنظیم PCRE2_DOLLAR_ENDONLY /s dotall تنظیم PCRE2_DOTALL dupnames تنظیم PCRE2_DUPNAMES endanchored تنظیم PCRE2_ENDANCHORED escaped_cr_is_lf تنظیم PCRE2_EXTRA_ESCAPED_CR_IS_LF /x extended تنظیم PCRE2_EXTENDED /xx extended_more تنظیم PCRE2_EXTENDED_MORE extra_alt_bsux تنظیم PCRE2_EXTRA_ALT_BSUX firstline تنظیم PCRE2_FIRSTLINE literal تنظیم PCRE2_LITERAL match_line تنظیم PCRE2_EXTRA_MATCH_LINE match_invalid_utf تنظیم PCRE2_MATCH_INVALID_UTF match_unset_backref تنظیم PCRE2_MATCH_UNSET_BACKREF match_word تنظیم PCRE2_EXTRA_MATCH_WORD /m multiline تنظیم PCRE2_MULTILINE never_backslash_c تنظیم PCRE2_NEVER_BACKSLASH_C never_callout تنظیم PCRE2_EXTRA_NEVER_CALLOUT never_ucp تنظیم PCRE2_NEVER_UCP never_utf تنظیم PCRE2_NEVER_UTF /n no_auto_capture تنظیم PCRE2_NO_AUTO_CAPTURE no_auto_possess تنظیم PCRE2_NO_AUTO_POSSESS no_bs0 تنظیم PCRE2_EXTRA_NO_BS0 no_dotstar_anchor تنظیم PCRE2_NO_DOTSTAR_ANCHOR no_start_optimize تنظیم PCRE2_NO_START_OPTIMIZE no_utf_check تنظیم PCRE2_NO_UTF_CHECK python_octal تنظیم PCRE2_EXTRA_PYTHON_OCTAL turkish_casing تنظیم PCRE2_EXTRA_TURKISH_CASING ucp تنظیم PCRE2_UCP ungreedy تنظیم PCRE2_UNGREEDY use_offset_limit تنظیم PCRE2_USE_OFFSET_LIMIT utf تنظیم PCRE2_UTF .sp تغییردهندهٔ \fButf\fP علاوه بر فعال کردن گزینهٔ PCRE2_UTF، باعث می‌شود تمام نویسه‌های غیرقابل‌چاپ در رشته‌های خروجی با استفاده از قالب \ex{hh...} چاپ شوند. در غیر این صورت، موارد کمتر از 0x100 به‌صورت هگزادسیمال بدون آکولاد چاپ می‌شوند. همچنین تنظیم \fButf\fP در حالت ۱۶ بیتی یا ۳۲ بیتی موجب می‌شود رشته‌های الگو و هدف پیش از ارسال به توابع کتابخانه، به ترتیب به UTF-16 یا UTF-32 ترجمه شوند. .sp تغییردهنده‌های زیر با فراخوانی \fBpcre2_set_optimize()\fP پیش از اجرای کامپایلر عبارات باقاعده، بهینه‌سازی‌های کارایی را فعال یا غیرفعال می‌کنند: .sp optimization_full فعال‌سازی تمام بهینه‌سازی‌های اختیاری optimization_none غیرفعال‌سازی تمام بهینه‌سازی‌های اختیاری auto_possess تملک خودکار سورهای متغیر auto_possess_off عدم تملک خودکار سورهای متغیر dotstar_anchor لنگر کردن الگوهای آغازشونده با .* dotstar_anchor_off عدم لنگر کردن الگوهای آغازشونده با .* start_optimize فعال‌سازی پیش‌پیمایش رشتهٔ هدف start_optimize_off غیرفعال‌سازی پیش‌پیمایش رشتهٔ هدف .sp برای جزئیات بیشتر دربارهٔ این بهینه‌سازی‌ها مستندات .\" HREF \fBpcre2_set_optimize\fP .\" را ببینید. . . .\" HTML .SS "تنظیم کنترل‌های کامپایل (Setting compilation controls)" .rs .sp تغییردهنده‌های زیر بر فرآیند کامپایل تأثیر می‌گذارند یا اطلاعاتی را دربارهٔ الگو درخواست می‌کنند. برای برخی مواردی که در فایل‌های آزمون کاربرد فراوان دارند، اختصارات تک‌حرفی وجود دارد. .sp /B bincode نمایش کد باینری بدون طول bsr=[anycrlf|unicode] مشخص کردن نحوهٔ مدیریت \eR callout_info نمایش اطلاعات کال‌اوت (callout) convert= درخواست تبدیل الگوی خارجی convert_glob_escape=c تنظیم نویسهٔ گریز glob convert_glob_separator=c تنظیم نویسهٔ جداکنندهٔ glob convert_length تنظیم طول بافر تبدیل debug مشابه info,fullbincode expand بسط ساختار تکرار در الگو framesize نمایش اندازهٔ فریم تطبیق fullbincode نمایش کد باینری به همراه طول /I info نمایش اطلاعات دربارهٔ الگوی کامپایل‌شده hex نویسه‌های خارج از نقل‌قول هگزادسیمال هستند jit[=] استفاده از JIT jitfast استفاده از مسیر سریع JIT jitverify تأیید صحت استفاده از JIT locale= استفاده از این لوکال (locale) max_pattern_compiled ) تنظیم حداکثر طول الگوی کامپایل‌شده _length= ) (به بایت) max_pattern_length= تنظیم حداکثر طول الگو (واحدهای کد) max_varlookbehind= تنظیم حداکثر طول تطبیق پس‌نگر متغیر memory نمایش حافظهٔ استفاده‌شده newline= تنظیم نوع خط جدید null_context کامپایل با یک زمینهٔ NULL null_pattern ارسال الگو به‌صورت NULL parens_nest_limit= تنظیم حداکثر عمق پرانتزها posix استفاده از POSIX API posix_nosub استفاده از POSIX API همراه با REG_NOSUB push قراردادن الگوی کامپایل‌شده روی پشته pushcopy قراردادن یک کپی روی پشته pushtablescopy قراردادن یک کپی همراه با جداول روی پشته stackguard= آزمایش قابلیت stackguard subject_literal در نظر گرفتن تمام خطوط هدف به‌صورت لفظی tables=[0|1|2|3] انتخاب جداول داخلی use_length الگو با نویسهٔ صفر خاتمه داده نشود utf8_input در نظر گرفتن ورودی به‌صورت UTF-8 .sp تأثیرات این تغییردهنده‌ها در بخش‌های بعدی شرح داده شده است. . . .SS "مدیریت خط جدید (Newline) و \eR" .rs .sp تغییردهندهٔ \fBbsr\fP مشخص می‌کند که \eR در یک الگو باید با چه چیزی تطبیق یابد. اگر روی "anycrlf" تنظیم شود، \eR فقط با CR، LF یا CRLF تطبیق می‌یابد. اگر روی "unicode" تنظیم شود، \eR با هر توالی خط جدید در یونیکد تطبیق پیدا می‌کند. پیش‌فرض را می‌توان هنگام ساخت PCRE2 مشخص کرد؛ در غیر این صورت، مقدار پیش‌فرض روی Unicode تنظیم می‌شود. .P تغییردهندهٔ \fBnewline\fP مشخص می‌کند که کدام نویسه‌ها باید هم در الگو و هم در خطوط هدف (subject) به عنوان خط جدید تفسیر شوند. نوع باید یکی از CR، LF، CRLF، ANYCRLF، ANY یا NUL باشد (با حروف بزرگ یا کوچک). . . .SS "اطلاعات دربارهٔ یک الگو" .rs .sp تغییردهندهٔ \fBdebug\fP کوته‌نوشتی برای \fBinfo,fullbincode\fP است که تمام اطلاعات موجود را درخواست می‌کند. .P تغییردهندهٔ \fBbincode\fP باعث می‌شود نمایشی از کد کامپایل‌شده پس از کامپایل در خروجی چاپ شود. این اطلاعات حاوی مقادیر طول و آفست نیست، که تضمین می‌کند خروجی یکسانی برای اندازه‌های مختلف پیوند داخلی (internal link sizes) و عرض‌های مختلف واحد کد (code unit widths) تولید می‌شود. با استفاده از \fBbincode\fP، می‌توان از همان آزمون‌های رگرسیون در محیط‌های مختلف استفاده کرد. .P در مقابل، تغییردهندهٔ \fBfullbincode\fP مقادیر طول و آفست را \fIشامل می‌شود\fP. این مورد در چند آزمون خاص استفاده می‌شود که تنها برای عرض‌های واحد کد و اندازه‌های پیوند مشخصی اجرا می‌شوند، و همچنین برای آزمون‌های یک‌باره کاربرد دارد. .P تغییردهندهٔ \fBinfo\fP اطلاعاتی دربارهٔ الگوی کامپایل‌شده درخواست می‌کند (اینکه آیا مهار شده است، نویسهٔ اول ثابتی دارد، و غیره). این اطلاعات از تابع \fBpcre2_pattern_info()\fP به دست می‌آید. در اینجا چند نمونه معمولی آورده شده است: .sp re> /(?i)(^a|^b)/m,info Capture group count = 1 Compile options: multiline Overall options: caseless multiline First code unit at start or follows newline Subject length lower bound = 1 .sp re> /(?i)abc/info Capture group count = 0 Compile options: Overall options: caseless First code unit = 'a' (caseless) Last code unit = 'c' (caseless) Subject length lower bound = 3 .sp عبارت «Compile options» گزینه‌هایی هستند که توسط تغییردهنده‌ها مشخص شده‌اند؛ «overall options» گزینه‌های اضافه‌ای دارند که از خود الگو گرفته یا استنتاج شده‌اند. اگر هر دو مجموعه گزینه یکسان باشند، تنها یک خط «options» در خروجی چاپ می‌شود؛ اگر هیچ گزینه‌ای وجود نداشته باشد، این خط حذف می‌شود. عبارت «First code unit» جایی است که هر تطبیق باید از آنجا آغاز شود؛ اگر بیش از یک مورد باشد، تحت عنوان «starting code units» فهرست می‌شوند. «Last code unit» آخرین واحد کد لفظی است که باید در هر تطبیق وجود داشته باشد. این لزوماً آخرین نویسه نیست. اگر هیچ واحد کد ابتدایی یا انتهایی ثبت نشده باشد، این خطوط حذف می‌شوند. خط طول رشتهٔ هدف هنگامی که \fBno_start_optimize\fP تنظیم شده باشد حذف می‌شود، زیرا وقتی حداقل طول هرگز قابل استفاده نباشد، محاسبه نمی‌شود. .P تغییردهندهٔ \fBframesize\fP اندازه (به بایت) هر فریم ذخیره‌سازی را نشان می‌دهد که توسط \fBpcre2_match()\fP برای مدیریت پس‌گرد (backtracking) استفاده می‌شود. اندازه به تعداد پرانتزهای گیرنده در الگو بستگی دارد. برداری از این فریم‌ها در زمان تطبیق استفاده می‌شود؛ اندازهٔ کلی آن زمانی نشان داده می‌شود که تغییردهندهٔ هدف \fBheapframes_size\fP تنظیم شده باشد. .P تغییردهندهٔ \fBcallout_info\fP اطلاعاتی دربارهٔ تمام کال‌اوت‌های موجود در الگو درخواست می‌کند. فهرستی از آن‌ها در انتهای هر اطلاعات درخواستی دیگر در خروجی قرار می‌گیرد. برای هر کال‌اوت، شماره یا رشتهٔ آن و به دنبال آن آیتمی که بعد از آن در الگو می‌آید آورده می‌شود. . . .SS "ارسال یک زمینهٔ NULL" .rs .sp در حالت عادی، \fBpcre2test\fP یک بلوک زمینه را به \fBpcre2_compile()\fP ارسال می‌کند. با این حال، اگر تغییردهندهٔ \fBnull_context\fP تنظیم شده باشد، مقدار NULL ارسال می‌شود. این برای آزمایش رفتار صحیح \fBpcre2_compile()\fP در این حالت است (از مقادیر پیش‌فرض استفاده می‌کند). . . .SS "ارسال یک الگوی NULL" .rs .sp تغییردهندهٔ \fBnull_pattern\fP برای آزمایش رفتار \fBpcre2_compile()\fP زمانی است که آرگومان الگو NULL باشد. مقدار طول ارسالی همان پیش‌فرض PCRE2_ZERO_TERMINATED است مگر اینکه \fBuse_length\fP تنظیم شده باشد. هر طولی غیر از صفر باعث ایجاد خطا می‌شود. . . .SS "مشخص کردن نویسه‌های الگو در مبنای شانزده" .rs .sp تغییردهندهٔ \fBhex\fP مشخص می‌کند که نویسه‌های الگو، به جز زیررشته‌های محصور در نقل‌قول تکی یا دوتایی، باید به عنوان جفت‌ارقام هگزادسیمال تفسیر شوند. این قابلیت به عنوان روشی برای ایجاد الگوهایی ارائه شده است که شامل صفرهای دودویی و سایر نویسه‌های غیرقابل‌چاپ هستند. وجود فاصله خالی میان جفت‌ارقام مجاز است. به عنوان مثال، این الگو شامل سه نویسه است: .sp /ab 32 59/hex .sp بخش‌هایی از چنین الگویی در صورت قرار گرفتن در نقل‌قول، به صورت لفظی (literal) در نظر گرفته می‌شوند. این الگو شامل نه نویسه است که فقط دو تای آن‌ها در مبنای شانزده مشخص شده‌اند: .sp /ab "literal" 32/hex .sp می‌توان از نقل‌قول تکی یا دوتایی استفاده کرد. راهی برای گنجاندن جداکننده در داخل یک زیررشته وجود ندارد. تغییردهنده‌های \fBhex\fP و \fBexpand\fP مانعة‌الجمع هستند. . . .SS "مشخص کردن طول الگو" .rs .sp به طور پیش‌فرض، الگوها به عنوان رشته‌های خاتمه‌یافته با صفر (zero-terminated) به توابع کامپایل ارسال می‌شوند، اما می‌توان آن‌ها را به جای خاتمه با صفر، با تعیین طول ارسال کرد. تغییردهندهٔ \fBuse_length\fP باعث این اتفاق می‌شود. ارسال با تعیین طول زمانی که \fBhex\fP تنظیم شده باشد به طور خودکار انجام می‌شود (چه \fBuse_length\fP تنظیم شده باشد چه نباشد)، زیرا الگوهای مشخص‌شده در مبنای شانزده ممکن است حاوی صفرهای دودویی باشند. .P اگر \fBhex\fP یا \fBuse_length\fP همراه با رابط برنامه‌نویسی بسته‌بند POSIX استفاده شوند (بخش .\" HTML .\" «استفاده از رابط برنامه‌نویسی بسته‌بند POSIX» .\" در زیر را ببینید)، افزونهٔ REG_PEND برای ارسال طول الگو استفاده می‌شود. . . .SS "مشخص کردن حداکثر برای پس‌نگری‌های متغیر" .rs .sp ارهان‌های پس‌نگری متغیر (Variable lookbehind assertions) تنها در صورتی پشتیبانی می‌شوند که برای هر کدام، حداکثر طولی (بر حسب نویسه) که می‌تواند با آن تطبیق یابد وجود داشته باشد. محدودیتی برای این موضوع وجود دارد که مقدار پیش‌فرض آن را می‌توان در زمان ساخت تعیین کرد، و پیش‌فرض نهایی آن ۲۵۵ است. تغییردهندهٔ \fBmax_varlookbehind\fP از تابع \fBpcre2_set_max_varlookbehind()\fP برای تغییر این محدودیت استفاده می‌کند. پس‌نگری‌هایی که شاخه‌های آن‌ها هر کدام با یک طول ثابت تطبیق می‌یابند، به ۶۵۵۳۵ نویسه در هر شاخه محدود هستند. . . .SS "مشخص کردن نویسه‌های عریض در حالت‌های ۱۶ بیتی و ۳۲ بیتی" .rs .sp در حالت‌های ۱۶ بیتی و ۳۲ بیتی، زمانی که تغییردهندهٔ \fButf\fP تنظیم شده باشد، تمام ورودی به طور خودکار به عنوان UTF-8 در نظر گرفته شده و به UTF-16 یا UTF-32 ترجمه می‌شود. برای آزمایش کتابخانه‌های ۱۶ بیتی و ۳۲ بیتی در حالت غیر UTF، می‌توان از تغییردهندهٔ \fButf8_input\fP استفاده کرد. این گزینه با \fButf\fP مانعة‌الجمع است. خطوط ورودی به عنوان روشی برای مشخص کردن نویسه‌های عریض، به صورت UTF-8 تفسیر می‌شوند. جزئیات بیشتر در بخش .\" HTML .\" «کدگذاری ورودی» .\" در بالا آمده است. . . .SS "تولید الگوهای تکراری طولانی" .rs .sp برخی آزمون‌ها از الگوهای طولانی که بسیار تکراری هستند استفاده می‌کنند. به جای ایجاد یک خط ورودی بسیار طولانی برای چنین الگویی، می‌توانید از قابلیت تکرار ویژه استفاده کنید، مشابه آنچه برای خطوط هدف در بالا شرح داده شد. اگر تغییردهندهٔ \fBexpand\fP روی یک الگو وجود داشته باشد، بخش‌هایی از الگو که به شکل .sp \e[]{} .sp هستند، قبل از ارسال الگو به \fBpcre2_compile()\fP گسترش می‌یابند. برای مثال، \e[AB]{6000} به مقدار "ABAB..." تا ۶۰۰۰ بار گسترش می‌یابد. این ساختار نمی‌تواند تو در تو باشد. توالی ابتدایی "\e[" تنها در صورتی تشخیص داده می‌شود که "]{" به دنبال ارقام ده‌دهی و "}" در ادامهٔ الگو یافت شود. در غیر این صورت، نویسه‌ها بدون تغییر در الگو باقی می‌مانند. تغییردهنده‌های \fBexpand\fP و \fBhex\fP مانعة‌الجمع هستند. .P اگر بخشی از یک الگوی گسترش‌یافته شبیه به ساختار گسترش باشد اما در واقع بخشی از خود الگوی اصلی باشد، با دادن دو مقدار در کمیت‌سنج می‌توان از گسترش ناخواسته جلوگیری کرد. برای مثال، \e[AB]{6000,6000} به عنوان یک آیتم گسترش شناخته نمی‌شود. .P اگر تغییردهندهٔ \fBinfo\fP روی یک الگوی گسترش‌یافته تنظیم شده باشد، نتیجهٔ گسترش در اطلاعات خروجی گنجانده می‌شود. . . .SS "کامپایل درجا (JIT compilation)" .rs .sp کامپایل درجا یا Just-in-time (JIT) یک بهینه‌سازی سنگین است که می‌تواند سرعت تطبیق الگو را به میزان قابل توجهی افزایش دهد. برای جزئیات به مستندات .\" HREF \fBpcre2jit\fP .\" مراجعه کنید. کامپایل JIT به صورت اختیاری، پس از کامپایل موفق الگو به یک فرم داخلی، انجام می‌شود. کامپایلر JIT این فرم را به کد ماشین بهینه‌شده تبدیل می‌کند. کامپایلر باید بداند که آیا گزینه‌های زمان تطبیق PCRE2_PARTIAL_HARD و PCRE2_PARTIAL_SOFT استفاده خواهند شد یا خیر، زیرا کدهای متفاوتی برای حالت‌های مختلف تولید می‌شود. برای جزئیات نحوه مشخص کردن این گزینه‌ها برای هر تلاش تطبیق، تغییردهندهٔ \fBpartial\fP را در «تغییردهنده‌های هدف» .\" HTML .\" در زیر ببینید. .\" .P کامپایل JIT توسط تغییردهندهٔ الگوی \fBjit\fP درخواست می‌شود، که می‌تواند به صورت اختیاری با یک علامت مساوی و عددی در محدودهٔ ۰ تا ۷ همراه باشد. سه بیتی که این عدد را تشکیل می‌دهند مشخص می‌کنند کدام یک از سه حالت عملیاتی JIT باید کامپایل شوند: .sp 1 compile JIT code for non-partial matching 2 compile JIT code for soft partial matching 4 compile JIT code for hard partial matching .sp بنابراین مقادیر مجاز برای تغییردهندهٔ \fBjit\fP عبارتند از: .sp 0 disable JIT 1 normal matching only 2 soft partial matching only 3 normal and soft partial matching 4 hard partial matching only 6 soft and hard partial matching only 7 all three modes .sp اگر عددی داده نشود، مقدار ۷ در نظر گرفته می‌شود. عبارت «partial matching» (تطبیق جزئی) به معنای فراخوانی \fBpcre2_match()\fP با تنظیم یکی از گزینه‌های PCRE2_PARTIAL_SOFT یا PCRE2_PARTIAL_HARD است. توجه داشته باشید که چنین فراخوانی ممکن است یک تطبیق کامل را بازگرداند؛ این گزینه‌ها امکان تطبیق جزئی را فراهم می‌کنند، اما آن را الزامی نمی‌سازند. همچنین توجه داشته باشید که اگر کامپایل JIT را فقط برای تطبیق جزئی درخواست کنید (برای مثال jit=2) اما تغییردهندهٔ \fBpartial\fP را روی خط هدف تنظیم نکنید، آن تطبیق از کد JIT استفاده نخواهد کرد زیرا کدی برای تطبیق غیرجزئی کامپایل نشده است. .P اگر کامپایل JIT موفقیت‌آمیز باشد، کد JIT کامپایل‌شده به طور خودکار هنگام اجرای نوع مناسبی از تطبیق استفاده خواهد شد، مگر زمانی که گزینه‌های ناسازگار زمان اجرا مشخص شده باشند. برای جزئیات بیشتر به مستندات .\" HREF \fBpcre2jit\fP .\" مراجعه کنید. همچنین تغییردهندهٔ \fBjitstack\fP در زیر را برای روش تنظیم اندازهٔ پشتهٔ JIT ببینید. .P اگر تغییردهندهٔ \fBjitfast\fP مشخص شده باشد، تطبیق با استفاده از رابط «مسیر سریع» JIT یعنی \fBpcre2_jit_match()\fP انجام می‌شود، که از برخی بررسی‌های صحت که توسط \fBpcre2_match()\fP انجام می‌شود صرف‌نظر می‌کند و البته در صورتی که JIT پشتیبانی نشود کار نخواهد کرد. اگر \fBjitfast\fP بدون \fBjit\fP مشخص شود، jit=7 فرض می‌شود. .P اگر تغییردهندهٔ \fBjitverify\fP مشخص شده باشد، اطلاعات مربوط به الگوی کامپایل‌شده نشان می‌دهد که آیا کامپایل JIT موفق بوده است یا خیر. اگر \fBjitverify\fP بدون \fBjit\fP مشخص شود، jit=7 فرض می‌شود. در صورتی که کامپایل JIT موفق باشد و \fBjitverify\fP تنظیم شده باشد، در صورتی که کد کامپایل‌شده با JIT واقعاً در تطبیق استفاده شده باشد، متن "(JIT)" به اولین خط خروجی پس از تطبیق یا عدم تطبیق اضافه می‌شود. . . .SS "تنظیم یک لوکال (Locale)" .rs .sp تغییردهندهٔ \fBlocale\fP باید نام یک لوکال را مشخص کند، برای مثال: .sp /pattern/locale=fr_FR .sp لوکال داده‌شده تنظیم می‌شود، تابع \fBpcre2_maketables()\fP برای ساخت مجموعه‌ای از جداول نویسه برای آن لوکال فراخوانی می‌شود، و سپس هنگام کامپایل عبارت باقاعده به \fBpcre2_compile()\fP ارسال می‌گردد. همین جداول هنگام تطبیق خطوط هدف بعدی استفاده می‌شوند. تغییردهندهٔ \fBlocale\fP فقط برای الگویی که روی آن قرار دارد اعمال می‌شود، اما اگر پیش‌فرضی نیاز باشد می‌توان آن را در دستور \fB#pattern\fP ارائه داد. تنظیم لوکال و جداول نویسهٔ جایگزین مانعة‌الجمع هستند. . . .SS "نمایش حافظهٔ الگو" .rs .sp تغییردهندهٔ \fBmemory\fP باعث می‌شود اندازه (به بایت) حافظهٔ استفاده‌شده برای نگهداری الگوی کامپایل‌شده در خروجی چاپ شود. این اندازه شامل حجم بلوک \fBpcre2_code\fP نمی‌شود؛ بلکه صرفاً داده‌های کامپایل‌شدهٔ واقعی است. اگر الگو متعاقباً به کامپایلر JIT ارسال شود، اندازهٔ کد کامپایل‌شدهٔ JIT نیز در خروجی نمایش داده می‌شود. در اینجا یک مثال آورده شده است: .sp re> /a(b)c/jit,memory Memory allocation (code space): 21 Memory allocation (JIT code): 1910 .sp . . .SS "محدود کردن پرانتزهای تو در تو" .rs .sp تغییردهندهٔ \fBparens_nest_limit\fP محدودیتی برای عمق پرانتزهای تو در تو در یک الگو تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض کتابخانه هنگام ساخت PCRE2 تنظیم می‌شود، اما \fBpcre2test\fP پیش‌فرض خود را روی ۲۲۰ قرار می‌دهد که برای اجرای مجموعه آزمون‌های استاندارد لازم است. . . .SS "محدود کردن طول الگو" .rs .sp تغییردهندهٔ \fBmax_pattern_length\fP محدودیتی (بر حسب واحدهای کد) برای طول الگویی که \fBpcre2_compile()\fP می‌پذیرد تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض بزرگترین عددی است که یک متغیر PCRE2_SIZE می‌تواند نگه دارد (اساساً نامحدود). . . .SS "محدود کردن اندازهٔ الگوی کامپایل‌شده" .rs .sp تغییردهندهٔ \fBmax_pattern_compiled_length\fP محدودیتی (به بایت) برای میزان حافظهٔ استفاده‌شده توسط یک الگوی کامپایل‌شده تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض بزرگترین عددی است که یک متغیر PCRE2_SIZE می‌تواند نگه دارد (اساساً نامحدود). . . .\" HTML .SS "استفاده از رابط برنامه‌نویسی بسته‌بند POSIX" .rs .sp تغییردهنده‌های \fBposix\fP و \fBposix_nosub\fP باعث می‌شوند \fBpcre2test\fP کتابخانهٔ PCRE2 را از طریق رابط برنامه‌نویسی بسته‌بند POSIX فراخوانی کند به جای رابط بومی آن. هنگامی که \fBposix_nosub\fP استفاده می‌شود، گزینهٔ REG_NOSUB مربوط به POSIX به \fBregcomp()\fP ارسال می‌گردد. بسته‌بند POSIX فقط از کتابخانهٔ ۸ بیتی پشتیبانی می‌کند. توجه داشته باشید که این به معنای معناشناسی تطبیق POSIX نیست؛ برای جزئیات بیشتر به مستندات .\" HREF \fBpcre2posix\fP .\" مراجعه کنید. تغییردهنده‌های الگوی زیر گزینه‌هایی را برای تابع \fBregcomp()\fP تنظیم می‌کنند: .sp caseless REG_ICASE multiline REG_NEWLINE dotall REG_DOTALL ) ungreedy REG_UNGREEDY ) These options are not part of ucp REG_UCP ) the POSIX standard utf REG_UTF8 ) .sp تغییردهندهٔ \fBregerror_buffsize\fP اندازه‌ای را برای بافر خطا مشخص می‌کند که در صورت بروز خطای کامپایل به \fBregerror()\fP ارسال می‌شود. برای مثال: .sp /abc/posix,regerror_buffsize=20 .sp این امکانی برای آزمایش رفتار \fBregerror()\fP هنگامی که بافر برای پیام خطا خیلی کوچک است فراهم می‌کند. اگر این تغییردهنده تنظیم نشده باشد، از یک بافر بزرگ استفاده می‌شود. .P تغییردهنده‌های هدف \fBaftertext\fP و \fBallaftertext\fP همان‌طور که در زیر شرح داده شده کار می‌کنند. تمام تغییردهنده‌های دیگر یا نادیده گرفته می‌شوند (همراه با پیام هشدار) یا باعث ایجاد خطا می‌شوند. .P الگو به صورت پیش‌فرض به عنوان یک رشتهٔ خاتمه‌یافته با صفر به \fBregcomp()\fP ارسال می‌شود، اما اگر تغییردهنده‌های \fBuse_length\fP یا \fBhex\fP تنظیم شده باشند، از افزونهٔ REG_PEND برای ارسال آن با طول استفاده می‌شود. . . .SS "آزمایش ویژگی محافظ پشته (Testing the stack guard feature)" .rs .sp تغییردهنده \fBstackguard\fP برای آزمودن استفاده از \fBpcre2_set_compile_recursion_guard()\fP به کار می‌رود؛ تابعی که برای امکان بررسی در دسترس بودن پشته در حین کامپایل ارائه شده است (برای جزئیات به مستندات .\" HREF \fBpcre2api\fP .\" مراجعه کنید). اگر عدد مشخص‌شده توسط این تغییردهنده بزرگ‌تر از صفر باشد، \fBpcre2_set_compile_recursion_guard()\fP فراخوانی می‌شود تا یک فراخوانی بازگشتی (callback) از \fBpcre2_compile()\fP به یک تابع محلی برقرار کند. آرگومانی که این تابع دریافت می‌کند، عمق فعلی پرانتزهای تودرتو است؛ اگر این مقدار از مقدار تعیین‌شده توسط تغییردهنده بزرگ‌تر باشد، مقداری غیرصفر برگردانده می‌شود که باعث لغو و توقف کامپایل می‌گردد. . . .SS "استفاده از جدول‌های کاراکتری جایگزین (Using alternative character tables)" .rs .sp مقدار مشخص‌شده برای تغییردهنده \fBtables\fP باید یکی از ارقام 0، 1، 2 یا 3 باشد. این مقدار باعث می‌شود مجموعه خاصی از جدول‌های کاراکتری توکار به \fBpcre2_compile()\fP ارسال شود. این ویژگی در آزمون‌های PCRE2 برای بررسی رفتار با جدول‌های کاراکتری مختلف به کار می‌رود. این رقم جدول‌ها را به شرح زیر مشخص می‌کند: .sp 0 عدم ارسال هرگونه جدول کاراکتری خاص 1 جدول‌های پیش‌فرض ASCII، به شکلی که در pcre2_chartables.c.dist توزیع شده است 2 مجموعه‌ای از جدول‌ها برای تعریف کاراکترهای ISO 8859 3 مجموعه‌ای از جدول‌ها که توسط دستور #loadtables بارگذاری شده‌اند .sp در جدول‌های 2، برخی کاراکترها با کدهای بزرگ‌تر از 128 به عنوان حروف، ارقام، فاصله‌ها و غیره شناسایی می‌شوند. جدول‌های 3 تنها پس از آن قابل استفاده هستند که دستور \fB#loadtables\fP آن‌ها را از یک فایل باینری بارگذاری کرده باشد. تنظیم جدول‌های کاراکتری جایگزین و لوکال (locale) مانعه‌الجمع (متضاد) هستند. . . .SS "تنظیم برخی کنترل‌های تطبیق (Setting certain match controls)" .rs .sp تغییردهنده‌های زیر در واقع تغییردهنده‌های سوژه هستند و در بخش «تغییردهنده‌های سوژه» در ادامه شرح داده شده‌اند. با این حال، می‌توان آن‌ها را در فهرست تغییردهنده‌های الگو گنجاند؛ در این صورت بر هر خط سوژه‌ای که با آن الگو پردازش می‌شود اعمال می‌گردند. این تغییردهنده‌ها بر فرآیند کامپایل تأثیری نمی‌گذارند. .sp aftertext نمایش متن پس از تطبیق allaftertext نمایش متن پس از گروه‌های ضبط‌شده allcaptures نمایش تمام موارد ضبط‌شده allvector نمایش کامل ovector allusedtext نمایش تمام متن‌های بررسی‌شده altglobal تطبیق سراسری جایگزین /g global تطبیق سراسری heapframes_size نمایش اندازه heapframes داده‌های تطبیق jitstack= تنظیم اندازه پشته JIT mark نمایش مقادیر mark null_substitute_match_data جایگزینی با داده‌های تطبیق NULL replace= مشخص کردن یک رشته جایگزین startchar نمایش کاراکتر شروع در صورت مرتبط بودن substitute_callout استفاده از فراخوان‌های جایگزینی substitute_case_callout استفاده از فراخوان‌های وضعیت حروف جایگزینی substitute_extended استفاده از PCRE2_SUBSTITUTE_EXTENDED substitute_literal استفاده از PCRE2_SUBSTITUTE_LITERAL substitute_matched استفاده از PCRE2_SUBSTITUTE_MATCHED substitute_overflow_length استفاده از PCRE2_SUBSTITUTE_OVERFLOW_LENGTH substitute_replacement_only استفاده از PCRE2_SUBSTITUTE_REPLACEMENT_ONLY substitute_skip= رد کردن جایگزینی substitute_stop= رد کردن جایگزینی و موارد پس از آن substitute_unknown_unset استفاده از PCRE2_SUBSTITUTE_UNKNOWN_UNSET substitute_unset_empty استفاده از PCRE2_SUBSTITUTE_UNSET_EMPTY .sp این تغییردهنده‌ها نباید در یک دستور \fB#pattern\fP ظاهر شوند. اگر می‌خواهید آن‌ها را به عنوان پیش‌فرض قرار دهید، در یک دستور \fB#subject\fP تنظیمشان کنید. . . .SS "مشخص کردن خطوط سوژه لفظی (Specifying literal subject lines)" .rs .sp اگر تغییردهنده \fBsubject_literal\fP روی یک الگو وجود داشته باشد، تمام خطوط سوژه‌ای که با آن تطبیق داده می‌شوند به عنوان رشته‌های لفظی (literal) و بدون تفسیر بک‌اسلش‌ها در نظر گرفته می‌شوند. تنظیم تغییردهنده‌های سوژه روی چنین خطوطی امکان‌پذیر نیست، اما هر تغییری که به عنوان پیش‌فرض توسط دستور \fB#subject\fP تنظیم شده باشد، شناسایی می‌شود. . . .SS "ذخیره الگوی کامپایل‌شده (Saving a compiled pattern)" .rs .sp هنگامی که الگویی با تغییردهنده \fBpush\fP با موفقیت کامپایل می‌شود، به داخل پشته الگوهای کامپایل‌شده فرستاده می‌شود (push) و \fBpcre2test\fP انتظار دارد که خط بعدی به جای یک خط سوژه، حاوی یک الگوی جدید (یا یک دستور) باشد. این امکان هنگام ذخیره الگوهای کامپایل‌شده در یک فایل استفاده می‌شود، همان‌طور که در بخش تحت عنوان «ذخیره و بازیابی الگوهای کامپایل‌شده» .\" HTML .\" در ادامه شرح داده شده است. .\" اگر به جای \fBpush\fP از \fBpushcopy\fP استفاده شود، یک کپی از الگوی کامپایل‌شده در پشته قرار می‌گیرد و نسخه اصلی به عنوان الگوی جاری باقی می‌ماند تا آماده تطبیق با خطوط ورودی بعدی باشد. این قابلیت روشی را برای آزمایش تابع \fBpcre2_code_copy()\fP فراهم می‌کند. .\" تغییردهنده‌های \fBpush\fP و \fBpushcopy \fP با تغییردهنده‌های کامپایلی مانند \fBglobal\fP که در زمان تطبیق عمل می‌کنند، ناسازگار هستند. هر موردی که مشخص شود (برای نسخه درون پشته) نادیده گرفته شده و یک پیام هشدار صادر می‌شود، به جز \fBreplace\fP که موجب بروز خطا می‌گردد. توجه داشته باشید که \fBjitverify\fP با اینکه مجاز است، به هیچ تطبیق بعدی که از یک الگوی ذخیره‌شده در پشته استفاده می‌کند منتقل نمی‌شود. . . .SS "آزمایش تبدیل الگوهای خارجی (Testing foreign pattern conversion)" .rs .sp توابع آزمایشی تبدیل الگوهای خارجی در PCRE2 را می‌توان با تنظیم تغییردهنده \fBconvert\fP آزمایش کرد. آرگومان آن فهرستی از گزینه‌ها است که با دو‌نقطه از هم جدا شده‌اند و گزینه معادل را برای تابع \fBpcre2_pattern_convert()\fP تنظیم می‌کنند: .sp glob PCRE2_CONVERT_GLOB glob_no_starstar PCRE2_CONVERT_GLOB_NO_STARSTAR glob_no_wild_separator PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR posix_basic PCRE2_CONVERT_POSIX_BASIC posix_extended PCRE2_CONVERT_POSIX_EXTENDED unset لغو تمام گزینه‌ها (Unset all options) .sp مقدار "unset" برای غیرفعال کردن حالت پیش‌فرضی که توسط یک دستور \fB#pattern\fP تنظیم شده مفید است. هنگامی که یکی از این گزینه‌ها تنظیم شود، الگوی ورودی به \fBpcre2_pattern_convert()\fP ارسال می‌گردد. اگر تبدیل موفقیت‌آمیز باشد، نتیجه در خروجی منعکس شده و سپس به \fBpcre2_compile()\fP ارسال می‌شود. گزینه‌های معمول \fButf\fP و \fBno_utf_check\fP در صورت تنظیم، باعث می‌شوند گزینه‌های PCRE2_CONVERT_UTF و PCRE2_CONVERT_NO_UTF_CHECK به \fBpcre2_pattern_convert()\fP ارسال گردند. .P به طور پیش‌فرض، تابع تبدیل مجاز است برای خروجی خود یک بافر تخصیص دهد. با این حال، اگر تغییردهنده \fBconvert_length\fP به مقداری بزرگ‌تر از صفر تنظیم شود، \fBpcre2test\fP بافری با طول داده‌شده را ارسال می‌کند. این امر آزمودن بررسی طول را امکان‌پذیر می‌سازد. .P تغییردهنده‌های \fBconvert_glob_escape\fP و \fBconvert_glob_separator\fP می‌توانند برای تعیین کاراکترهای اسکیپ و جداکننده در پردازش glob استفاده شوند، و پیش‌فرض‌هایی را که به سیستم‌عامل وابسته‌اند بازنویسی و لغو نمایند. . . .\" HTML .SH "تغییردهنده‌های سوژه (SUBJECT MODIFIERS)" .rs .sp تغییردهنده‌هایی که می‌توانند در خطوط سوژه و دستور \fB#subject\fP ظاهر شوند از دو نوع هستند. . . .SS "تنظیم گزینه‌های تطبیق (Setting match options)" .rs .sp تغییردهنده‌های زیر گزینه‌هایی را برای \fBpcre2_match()\fP یا \fBpcre2_dfa_match()\fP تنظیم می‌کنند. برای شرح اثرات آن‌ها به .\" HREF \fBpcre2api\fP .\" مراجعه نمایید. .sp anchored تنظیم PCRE2_ANCHORED copy_matched_subject تنظیم PCRE2_COPY_MATCHED_SUBJECT endanchored تنظیم PCRE2_ENDANCHORED dfa_restart تنظیم PCRE2_DFA_RESTART dfa_shortest تنظیم PCRE2_DFA_SHORTEST disable_recurseloop_check تنظیم PCRE2_DISABLE_RECURSELOOP_CHECK no_jit تنظیم PCRE2_NO_JIT no_utf_check تنظیم PCRE2_NO_UTF_CHECK notbol تنظیم PCRE2_NOTBOL notempty تنظیم PCRE2_NOTEMPTY notempty_atstart تنظیم PCRE2_NOTEMPTY_ATSTART noteol تنظیم PCRE2_NOTEOL partial_hard (or ph) تنظیم PCRE2_PARTIAL_HARD partial_soft (or ps) تنظیم PCRE2_PARTIAL_SOFT .sp تغییردهنده‌های تطبیق جزئی همراه با اختصار ارائه شده‌اند زیرا به وفور در آزمون‌ها ظاهر می‌شوند. .P اگر تغییردهنده \fBposix\fP یا \fBposix_nosub\fP روی الگو وجود داشته باشد، که موجب استفاده از رابط کاربری POSIX wrapper می‌شود، تنها تغییردهنده‌های تنظیم گزینه که مؤثر خواهند بود \fBnotbol\fP، \fBnotempty\fP و \fBnoteol\fP هستند که به ترتیب موجب ارسال REG_NOTBOL، REG_NOTEMPTY و REG_NOTEOL به \fBregexec()\fP می‌شوند. سایر تغییردهنده‌ها همراه با یک پیام هشدار نادیده گرفته می‌شوند. .P یک تغییردهنده اضافی دیگر وجود دارد که می‌تواند با POSIX wrapper استفاده شود. اگر برای تطبیق غیر POSIX استفاده شود، نادیده گرفته می‌شود (همراه با هشدار). .sp posix_startend=[:] .sp این گزینه موجب می‌شود رشته سوژه با استفاده از گزینه REG_STARTEND به \fBregexec()\fP ارسال شود، که از آفست‌ها برای تعیین این‌که کدام بخش از رشته مورد جستجو قرار گیرد استفاده می‌کند. اگر تنها یک عدد مشخص شود، آفست پایانی به عنوان انتهای رشته سوژه در نظر گرفته می‌شود. برای جزئیات بیشتر در مورد REG_STARTEND، به مستندات .\" HREF \fBpcre2posix\fP .\" مراجعه کنید. اگر رشته سوژه حاوی صفرهای باینری باشد (کدگذاری‌شده به صورت کاراکترهای گریز مانند \ex{00} زیرا \fBpcre2test\fP از صفرهای باینری واقعی در ورودی خود پشتیبانی نمی‌کند)، باید از \fBposix_startend\fP برای تعیین طول آن استفاده کنید. . . .SS "تنظیم کنترل‌های تطبیق (Setting match controls)" .rs .sp تغییردهنده‌های زیر بر فرآیند تطبیق تأثیر می‌گذارند یا اطلاعات بیشتری را درخواست می‌نمایند. برخی از آن‌ها را می‌توان در خط الگو نیز مشخص کرد (به بالا مراجعه کنید)، که در این صورت بر هر خط سوژه‌ای که با آن الگو تطبیق داده می‌شود اعمال می‌شوند، اما می‌توان آن‌ها را با تغییردهنده‌های روی سوژه بازنویسی کرد. .sp aftertext نمایش متن پس از تطبیق allaftertext نمایش متن پس از گروه‌های ضبط‌شده allcaptures نمایش تمام موارد ضبط‌شده allusedtext نمایش تمام متن‌های بررسی‌شده (فقط non-JIT) allvector نمایش کامل ovector altglobal تطبیق سراسری جایگزین callout_capture نمایش موارد ضبط‌شده در زمان فراخوان callout_data= تنظیم مقداری برای ارسال از طریق فراخوان‌ها callout_error=[:] کنترل خطای فراخوان callout_extra نمایش اطلاعات اضافی فراخوان callout_fail=[:] کنترل شکست فراخوان callout_no_where عدم نمایش موقعیت یک فراخوان callout_none عدم ارائه تابع فراخوان copy= کپی زیررشته ضبط‌شده depth_limit= تنظیم محدودیت عمق dfa استفاده از \fBpcre2_dfa_match()\fP find_limits یافتن محدودیت‌های هیپ (heap)، تطبیق و عمق find_limits_noheap یافتن محدودیت‌های تطبیق و عمق get= استخراج زیررشته ضبط‌شده getall استخراج تمام زیررشته‌های ضبط‌شده /g global تطبیق سراسری heapframes_size نمایش اندازه heapframes داده‌های تطبیق heap_limit= تنظیم محدودیت حافظه هیپ (کیلوبایت) jitstack= تنظیم اندازه پشته JIT mark نمایش مقادیر mark match_limit= تنظیم محدودیت تطبیق memory نمایش میزان مصرف حافظه هیپ null_context تطبیق با یک بافت (context) از نوع NULL null_replacement جایگزینی با مقدار جایگزین NULL null_subject تطبیق با سوژه NULL null_substitute_match_data جایگزینی با داده‌های تطبیق NULL offset= تنظیم آفست شروع offset_limit= تنظیم محدودیت آفست ovector= تنظیم اندازه بردار خروجی (output vector) recursion_limit= مترادف منسوخ‌شده برای depth_limit replace= مشخص کردن یک رشته جایگزین startchar نمایش startchar در صورت مرتبط بودن startoffset= مشابه offset= substitute_callout استفاده از فراخوان‌های جایگزینی substitute_case_callout استفاده از فراخوان‌های وضعیت حروف جایگزینی substitute_extended استفاده از PCRE2_SUBSTITUTE_EXTENDED substitute_literal استفاده از PCRE2_SUBSTITUTE_LITERAL substitute_matched استفاده از PCRE2_SUBSTITUTE_MATCHED substitute_overflow_length استفاده از PCRE2_SUBSTITUTE_OVERFLOW_LENGTH substitute_replacement_only استفاده از PCRE2_SUBSTITUTE_REPLACEMENT_ONLY substitute_skip= رد کردن جایگزینی شماره n substitute_stop= رد کردن جایگزینی شماره n و بالاتر substitute_subject= مشخص کردن سوژه‌ای متفاوت برای جایگزینی substitute_unknown_unset استفاده از PCRE2_SUBSTITUTE_UNKNOWN_UNSET substitute_unset_empty استفاده از PCRE2_SUBSTITUTE_UNSET_EMPTY zero_terminate ارسال سوژه به صورت خاتمه‌یافته با صفر (zero-terminated) .sp اثرات این تغییردهنده‌ها در بخش‌های بعدی شرح داده شده است. هنگام تطبیق از طریق رابط کاربری POSIX wrapper، تغییردهنده‌های سوژه \fBaftertext\fP، \fBallaftertext\fP و \fBovector\fP طبق توضیحات زیر عمل می‌کنند. تمام تغییردهنده‌های دیگر یا نادیده گرفته می‌شوند (همراه با هشدار) و یا موجب بروز خطا می‌گردند. . . .SS "نمایش متن بیشتر (Showing more text)" .rs .sp تغییردهنده \fBaftertext\fP درخواست می‌کند که علاوه بر چاپ بخشی از رشته سوژه که با کل الگو تطبیق یافته است، \fBpcre2test\fP باقی‌مانده رشته سوژه را نیز در خروجی نمایش دهد. این قابلیت برای آزمون‌هایی کاربرد دارد که در آن‌ها سوژه شامل چند کپی از یک زیررشته مشابه است. تغییردهنده \fBallaftertext\fP همین عمل را برای زیررشته‌های ضبط‌شده علاوه بر زیررشته تطبیق‌یافته اصلی درخواست می‌کند. در هر حالت، باقی‌مانده در خط بعدی همراه با یک کاراکتر مثبت (+) بعد از شماره ضبط چاپ می‌شود. .P تغییردهنده \fBallusedtext\fP درخواست می‌کند تمام متنی که در حین یک تطبیق موفق الگو توسط مفسر بررسی شده است، هم برای تطبیق کامل و هم جزئی نمایش داده شود. این ویژگی برای تطبیق JIT پشتیبانی نمی‌شود و اگر همراه با JIT درخواست شود نادیده گرفته خواهد شد (همراه با پیام هشدار). تنظیم این تغییردهنده در صورتی بر خروجی تأثیر می‌گذارد که یک lookbehind در ابتدای تطبیق، یا برای یک تطبیق کامل، یک lookahead در انتها وجود داشته باشد، یا اینکه از \eK در الگو استفاده شده باشد. کاراکترهایی که قبل یا بعد از شروع و پایان تطبیق واقعی قرار دارند در خروجی با کاراکترهای '<' یا '>' در زیر آن‌ها نشان داده می‌شوند. در اینجا یک مثال آورده شده است: .sp re> /(?<=pqr)abc(?=xyz)/ data> 123pqrabcxyz456\e=allusedtext 0: pqrabcxyz <<< >>> data> 123pqrabcxy\e=ph,allusedtext Partial match: pqrabcxy <<< .sp اولین تطبیق (تطبیق کامل) نشان می‌دهد که رشته تطبیق‌یافته "abc" است، و رشته‌های قبلی و بعدی "pqr" و "xyz" در حین تطبیق (هنگام پردازش assertionها) بررسی شده‌اند. تطبیق جزئی تنها می‌تواند رشته قبلی را نشان دهد. .P تغییردهنده \fBstartchar\fP درخواست می‌کند که کاراکتر شروع تطبیق نشان داده شود، در صورتی که با ابتدای رشته تطبیق‌یافته متفاوت باشد. تنها زمانی که این اتفاق می‌افتد وقتی است که \eK به عنوان بخشی از تطبیق پردازش شده باشد. در این حالت، خروجی رشته تطبیق‌یافته به جای نقطه تطبیق از کاراکتر شروع نمایش داده می‌شود، و علامت‌های هشتک (^) در زیر کاراکترهای قبلی قرار می‌گیرند. به عنوان مثال: .sp re> /abc\eKxyz/ data> abcxyz\e=startchar 0: abcxyz ^^^ .sp برخلاف \fBallusedtext\fP، تغییردهنده \fBstartchar\fP می‌تواند همراه با JIT استفاده شود. با این حال، این دو تغییردهنده مانعه‌الجمع هستند. . . .SS "نمایش مقدار تمام گروه‌های ضبط‌شده (Showing the value of all capture groups)" .rs .sp تغییردهنده \fBallcaptures\fP درخواست می‌کند که مقادیر تمام پرانتزهای ضبط‌شده بالقوه پس از تطبیق در خروجی چاپ شوند. به طور پیش‌فرض، تنها گروه‌هایی تا بالاترین گروهی که واقعاً در تطبیق استفاده شده است در خروجی نمایش می‌یابند (مطابق با کد بازگشتی از \fBpcre2_match()\fP). گروه‌هایی که در تطبیق نقشی نداشته‌اند به صورت "" نمایش داده می‌شوند. این تغییردهنده برای تطبیق DFA (که هیچ ضبطی انجام نمی‌دهد) مرتبط نیست و زمانی که \fBreplace\fP مشخص شده باشد اعمال نمی‌شود؛ در صورت وجود، همراه با یک پیام هشدار نادیده گرفته خواهد شد. . . .SS "نمایش کامل ovector، برای تمام نتایج (Showing the entire ovector, for all outcomes)" .rs .sp تغییردهنده \fBallvector\fP درخواست می‌کند که تمام ovector بدون توجه به نتیجه تطبیق نمایش داده شود. این را با \fBallcaptures\fP مقایسه کنید که فقط تا حداکثر تعداد گروه‌های ضبط الگو و آن هم تنها برای یک تطبیق کامل و موفق غیر DFA خروجی می‌دهد. این تغییردهنده که پس از هر نتیجه تطبیق و همچنین برای تطبیق DFA عمل می‌کند، روشی را برای بررسی عدم وجود تغییرات غیرمنتظره در فیلدهای ovector فراهم می‌سازد. قبل از هر تلاش برای تطبیق، ovector با یک مقدار خاص پر می‌شود، و اگر این مقدار در هر دو عنصر یک جفت ضبط‌کننده یافت شود، عبارت "" چاپ می‌گردد. پس از یک تطبیق موفق، این امر برای تمام گروه‌های بعد از حداکثر گروه ضبط الگو اعمال می‌شود. در سایر موارد، برای کل ovector اعمال می‌گردد. پس از یک تطبیق جزئی، دو عنصر اول تنها مواردی هستند که باید مقداردهی شوند. پس از یک تطبیق DFA، میزان استفاده از ovector به تعداد تطبیق‌های یافت‌شده بستگی دارد. . . .SS "آزمایش فراخوان‌های الگو (Testing pattern callouts)" .rs .sp هنگامی که \fBpcre2test\fP توابع تطبیق کتابخانه را فراخوانی می‌کند یک تابع فراخوان (callout) ارائه می‌شود، مگر اینکه \fBcallout_none\fP مشخص شده باشد. رفتار آن را می‌توان توسط تغییردهنده‌های مختلفی که در بالا فهرست شده و نام آن‌ها با \fBcallout_\fP شروع می‌شود کنترل کرد. جزئیات در بخش تحت عنوان «فراخوان‌ها» (Callouts) .\" HTML .\" در ادامه ارائه شده است. .\" آزمودن فراخوان‌ها از \fBpcre2_substitute()\fP به طور جداگانه در بخش «آزمایش تابع جایگزینی» .\" HTML .\" در ادامه شرح داده شده است. .\" . . .SS "یافتن تمام تطابق‌ها در یک رشته" .rs .sp جستجو برای تمام تطابق‌های ممکن در یک رشته هدف (subject) را می‌توان با اصلاح‌کننده \fBglobal\fP یا \fBaltglobal\fP درخواست کرد. پس از یافتن یک تطابق، تابع تطابق دوباره فراخوانی می‌شود تا باقی‌مانده رشته هدف را جستجو کند. تفاوت بین \fBglobal\fP و \fBaltglobal\fP در این است که اولی از آرگومان \fIstart_offset\fP در \fBpcre2_match()\fP یا \fBpcre2_dfa_match()\fP برای شروع جستجو در نقطه‌ای جدید در کل رشته استفاده می‌کند (همان کاری که Perl انجام می‌دهد)، در حالی که دومی یک رشته هدف کوتاه‌شده را ارسال می‌کند. این امر در صورتی که الگو با یک ادعای پس‌نگاه (شامل \eb یا \eB) شروع شود، در فرآیند تطابق تفاوت ایجاد می‌کند. .P اگر یک رشته خالی مطابقت داده شود، تطابق بعدی با تنظیم فلگ PCRE2_NOTEMPTY_ATSTART انجام می‌شود تا برای تطابق دیگری که غیرخالی باشد در همان نقطه از رشته هدف جستجو شود. این رفتار نحوه مدیریت چنین مواردی توسط Perl را هنگام استفاده از اصلاح‌کننده \fB/g\fP یا تابع \fBsplit()\fP تقلید می‌کند. . . .SS "آزمودن توابع استخراج زیررشته" .rs .sp اصلاح‌کننده‌های \fBcopy\fP و \fBget\fP را می‌توان برای آزمودن توابع \fBpcre2_substring_copy_xxx()\fP و \fBpcre2_substring_get_xxx()\fP استفاده کرد. آن‌ها می‌توانند بیش از یک بار مشخص شوند و هر کدام می‌توانند نام یا شماره یک گروه ضبط (capture group) را مشخص کنند، برای نمونه: .sp abcd\e=copy=1,copy=3,get=G1 .sp اگر از دستور \fB#subject\fP برای تنظیم فهرست‌های پیش‌فرض copy و/یا get استفاده شود، می‌توان آن‌ها را با تعیین یک عدد منفی برای لغو تمام گروه‌های شماره‌دار و یک نام خالی برای لغو تمام گروه‌های نام‌گذاری‌شده، بازنشانی (unset) کرد. .P اصلاح‌کننده \fBgetall\fP تابع \fBpcre2_substring_list_get()\fP را آزمایش می‌کند که تمام زیررشته‌های ضبط‌شده را استخراج می‌کند. .P اگر خط رشته هدف با موفقیت تطابق یابد، زیررشته‌های استخراج‌شده توسط توابع کمکی با C، G، یا L پس از شماره رشته به جای دو نقطه خروجی داده می‌شوند. این علاوه بر فهرست کامل معمولی است. طول رشته (یعنی مقدار بازگشتی از تابع استخراج) در پرانتز پس از هر زیررشته آورده می‌شود و در صورتی که استخراج بر اساس نام بوده باشد، نام آن نیز در ادامه می‌آید. . . .\" HTML .SS "آزمودن تابع جایگزینی (substitution)" .rs .sp اگر اصلاح‌کننده \fBreplace\fP تنظیم شود، تابع \fBpcre2_substitute()\fP به جای یکی از توابع تطابق (یا پس از یک بار فراخوانی \fBpcre2_match()\fP در مورد PCRE2_SUBSTITUTE_MATCHED) فراخوانی می‌شود. توجه داشته باشید که رشته‌های جایگزین نمی‌توانند حاوی کاما باشند، زیرا کاما نشان‌دهنده پایان یک اصلاح‌کننده است. گمان نمی‌رود این موضوع در یک برنامه آزمایشی مشکلی ایجاد کند. .P مشخص کردن یک رشته جایگزین کاملاً خالی این اصلاح‌کننده را غیرفعال می‌کند. با این حال، همان‌طور که در زیر شرح داده شده است، می‌توان با ارائه طول بافر برای یک جایگزینی که در غیر این صورت خالی است، یک جایگزینی خالی تعیین کرد. .P برخلاف رشته‌های هدف، \fBpcre2test\fP رشته‌های جایگزین را برای توالی‌های گریز (escape sequences) پردازش نمی‌کند. در حالت UTF، بررسی می‌شود که آیا رشته جایگزین یک رشته معتبر UTF-8 است یا خیر. اگر چنین باشد، به درستی به یک رشته UTF با عرض واحد کد (code unit width) مناسب تبدیل می‌شود. اگر یک رشته UTF-8 معتبر نباشد، واحدهای کد به صورت مستقیم کپی می‌شوند. این روش راهکاری برای ارسال یک رشته نامعتبر UTF-8 برای اهداف آزمایشی فراهم می‌کند. .P اصلاح‌کننده‌های زیر گزینه‌هایی را (علاوه بر گزینه‌های تطابق عادی) برای \fBpcre2_substitute()\fP تنظیم می‌کنند: .sp global PCRE2_SUBSTITUTE_GLOBAL substitute_extended PCRE2_SUBSTITUTE_EXTENDED substitute_literal PCRE2_SUBSTITUTE_LITERAL substitute_matched PCRE2_SUBSTITUTE_MATCHED substitute_overflow_length PCRE2_SUBSTITUTE_OVERFLOW_LENGTH substitute_replacement_only PCRE2_SUBSTITUTE_REPLACEMENT_ONLY substitute_unknown_unset PCRE2_SUBSTITUTE_UNKNOWN_UNSET substitute_unset_empty PCRE2_SUBSTITUTE_UNSET_EMPTY .sp برای جزئیات این گزینه‌ها، مستندات .\" HREF \fBpcre2api\fP .\" را ببینید. .P پس از یک جایگزینی موفق، رشته تغییریافته که تعداد جایگزینی‌ها قبل از آن آمده است خروجی داده می‌شود. اگر تطابقی وجود نداشته باشد، این مقدار ممکن است صفر باشد. در اینجا نمونه‌ای ساده از یک آزمایش جایگزینی آمده است: .sp /abc/replace=xxx =abc=abc= 1: =xxx=abc= =abc=abc=\e=global 2: =xxx=xxx= .sp رشته‌های هدف و جایگزین برای آزمایش‌های جایگزینی باید نسبتاً کوتاه نگه داشته شوند (کمتر از ۲۵۶ کاراکتر)، زیرا از بافرهای با اندازه ثابت استفاده می‌شود. برای تسهیل آزمایش سرریز بافر، اگر رشته جایگزین با یک عدد درون قلاب‌ها شروع شود، آن عدد به عنوان اندازه بافر خروجی به \fBpcre2_substitute()\fP ارسال می‌شود و رشته جایگزین از کاراکتر بعدی شروع می‌شود. در اینجا مثالی آمده است که این حالت حدی را آزمایش می‌کند: .sp /abc/ 123abc123\e=replace=[10]XYZ 1: 123XYZ123 123abc123\e=replace=[9]XYZ Failed: error -48: no more memory .sp رفتار پیش‌فرض \fBpcre2_substitute()\fP هنگامی که بافر خروجی بیش از حد کوچک است، بازگرداندن PCRE2_ERROR_NOMEMORY است. با این حال، اگر گزینه PCRE2_SUBSTITUTE_OVERFLOW_LENGTH (با استفاده از اصلاح‌کننده \fBsubstitute_overflow_length\fP) تنظیم شده باشد، \fBpcre2_substitute()\fP مراحل تطابق و جایگزینی را ادامه می‌دهد (اما هیچ کال‌اوتی انجام نمی‌دهد) تا اندازه بافر مورد نیاز را محاسبه کند. هنگامی که این اتفاق می‌افتد، \fBpcre2test\fP طول بافر مورد نیاز را (شامل فضا برای صفر انتهایی) به عنوان بخشی از پیام خطا نشان می‌دهد. برای نمونه: .sp /abc/substitute_overflow_length 123abc123\e=replace=[9]XYZ Failed: error -48: no more memory: 10 code units are needed .sp رشته جایگزین در تطابق POSIX و DFA نادیده گرفته می‌شود. تعیین تطابق جزئی باعث ایجاد یک خطای بازگشتی (\(dqbad option value\(dq) از طرف \fBpcre2_substitute()\fP می‌شود. .sp اصلاح‌کننده \fBsubstitute_subject\fP ممکن است برای آزمودن استفاده از PCRE2 API به کار رود؛ حالتی که در آن کلاینت \fBpcre2_match()\fP و به دنبال آن \fBpcre2_substitute()\fP را با PCRE2_SUBSTITUTE_MATCHED فراخوانی می‌کند، اما در فاصله میان تطابق و جایگزینی، تغییری غیرمنتظره و پشتیبانی‌نشده را به صورت درجا روی بافر رشته هدف انجام می‌دهد. . . .SS "آزمودن کال‌اوت‌های جایگزینی" .rs .sp اگر اصلاح‌کننده \fBsubstitute_callout\fP تنظیم شود، یک تابع کال‌اوت جایگزینی راه‌اندازی می‌شود. اصلاح‌کننده \fBnull_context\fP نباید تنظیم شده باشد، زیرا آدرس تابع کال‌اوت در یک زمینه تطابق (match context) ارسال می‌شود. هنگامی که تابع کال‌اوت فراخوانی می‌شود (پس از هر جایگزینی)، جزئیات رشته‌های ورودی و خروجی چاپ می‌شوند. برای نمونه: .sp /abc/g,replace=<$0>,substitute_callout abcdefabcpqr 1(1) Old 0 3 "abc" New 0 5 "" 2(1) Old 6 9 "abc" New 8 13 "" 2: defpqr .sp نخستین عدد در هر خط کال‌اوت، تعداد تطابق‌ها است. عدد داخل پرانتز تعداد جفت‌هایی است که در ovector تنظیم شده‌اند (یعنی یک عدد بیشتر از تعداد گروه‌های ضبط‌کننده‌ای که تنظیم شده بودند). سپس آفست‌های زیررشته قدیمی، محتویات آن و همین موارد برای جایگزین فهرست می‌شوند. .P به‌طور پیش‌فرض، تابع کال‌اوت جایگزینی مقدار صفر را برمی‌گرداند که جایگزینی را می‌پذیرد و در صورت استفاده از /g باعث ادامه تطابق می‌شود. از دو اصلاح‌کننده دیگر می‌توان برای آزمودن مقادیر بازگشتی دیگر استفاده کرد. اگر \fBsubstitute_skip\fP روی مقداری بزرگتر از صفر تنظیم شود، تابع کال‌اوت برای تطابق آن شماره مقدار +1 را برمی‌گرداند و به طور مشابه \fBsubstitute_stop\fP مقدار \-1 را برمی‌گرداند. این موارد باعث رد شدن جایگزینی می‌شوند و \-1 باعث می‌شود که هیچ تطابق دیگری انجام نشود. در صورت تنظیم هر یک از آن‌ها، \fBsubstitute_callout\fP فرض می‌شود. برای نمونه: .sp /abc/g,replace=<$0>,substitute_skip=1 abcdefabcpqr 1(1) Old 0 3 "abc" New 0 5 " SKIPPED" 2(1) Old 6 9 "abc" New 6 11 "" 2: abcdefpqr abcdefabcpqr\e=substitute_stop=1 1(1) Old 0 3 "abc" New 0 5 " STOPPED" 1: abcdefabcpqr .sp اگر هر دو برای یک شماره تنظیم شوند، stop تقدم دارد. تنها یک skip یا stop تکی پشتیبانی می‌شود که برای آزمودن عملکرد این قابلیت کافی است. . . .SS "آزمودن کال‌اوت‌های تغییر حالت حروف جایگزین" .rs .sp اگر اصلاح‌کننده \fBsubstitute_case_callout\fP تنظیم شود، یک تابع کال‌اوت تغییر حالت حروف (case) جایگزینی راه‌اندازی می‌شود. این تابع کال‌اوت برای هر بخش جایگزین‌شده‌ای که قرار است تغییر حالت حروف روی آن انجام شود فراخوانی می‌گردد. .P تابع کال‌اوت ارائه‌شده یک تابع ثابت با پیاده‌سازی برای رفتارهای مشخصی است: ورودی‌هایی که هنگام تبدیل حالت حروف کوچک‌تر می‌شوند؛ ورودی‌هایی که بزرگ‌تر می‌شوند؛ و ورودی‌هایی با حالت‌های متمایز حروف بزرگ/کوچک/عنوان (upper/lower/titlecase). کاراکترهایی که برای اهداف آزمایشی مشمول حالت خاصی نشده‌اند، دست‌نخورده باقی می‌مانند، گویی کاراکترهای فاقد حالت حروف (caseless) هستند. . . .SS "تنظیم اندازه پشته JIT" .rs .sp اصلاح‌کننده \fBjitstack\fP روشی برای تنظیم حداکثر اندازه پشته که توسط کد بهینه‌سازی درجا (just-in-time) استفاده می‌شود ارائه می‌دهد. در صورتی که از بهینه‌سازی JIT استفاده نشود، این مورد نادیده گرفته می‌شود. مقدار آن به صورت کیبی‌بایت (واحدهای ۱۰۲۴ بایتی) است. تنظیم آن روی صفر به مقدار پیش‌فرض 32KiB بازمی‌گردد. ارائه پشته‌ای بزرگتر از مقدار پیش‌فرض تنها برای الگوهای بسیار پیچیده ضروری است. اگر \fBjitstack\fP در یک خط رشته هدف روی مقداری غیرصفر تنظیم شود، هر مقداری را که روی الگو تنظیم شده بود بازنویسی (override) می‌کند. . . .SS "تنظیم محدودیت‌های هیپ، تطابق و عمق" .rs .sp اصلاح‌کننده‌های \fBheap_limit\fP، \fBmatch_limit\fP و \fBdepth_limit\fP محدودیت‌های مناسب را در زمینه تطابق (match context) تنظیم می‌کنند. این مقادیر هنگام مشخص شدن اصلاح‌کننده \fBfind_limits\fP یا \fBfind_limits_noheap\fP نادیده گرفته می‌شوند. . . .SS "یافتن حداقل محدودیت‌ها" .rs .sp اگر اصلاح‌کننده \fBfind_limits\fP در یک خط رشته هدف وجود داشته باشد، \fBpcre2test\fP تابع تطابق مربوطه را چندین بار فراخوانی می‌کند و مقادیر متفاوتی را در زمینه تطابق از طریق \fBpcre2_set_heap_limit()\fP، \fBpcre2_set_match_limit()\fP یا \fBpcre2_set_depth_limit()\fP تنظیم می‌کند تا زمانی که کوچک‌ترین مقدار برای هر پارامتر را بیابد که اجازه می‌دهد تطابق بدون خطای \(dqlimit exceeded\(dq کامل شود. خود تطابق ممکن است موفق یا ناموفق باشد. یک اصلاح‌کننده جایگزین به نام \fBfind_limits_noheap\fP محدودیت هیپ را حذف می‌کند. این مورد در آزمایش‌های استاندارد استفاده می‌شود، زیرا حداقل محدودیت هیپ بین سیستم‌ها متفاوت است. اگر از JIT استفاده شود، تنها محدودیت تطابق مرتبط است و دو مورد دیگر به طور خودکار حذف می‌شوند. .P هنگام استفاده از این اصلاح‌کننده، الگو نباید حاوی هیچ‌گونه تنظیمات محدودیتی مانند (*LIMIT_MATCH=...) در درون خود باشد. اگر چنین تنظیمی وجود داشته باشد و کمتر از حداقل مقدار تطابق باشد، حداقل مقدار پیدا نمی‌شود زیرا \fBpcre2_set_match_limit()\fP و غیره تنها قادر به کاهش مقدار یک محدودیت درون الگو هستند؛ آن‌ها نمی‌توانند آن را افزایش دهند. .P برای تطابق غیر DFA، حداقل عدد \fIdepth_limit\fP معیاری است از میزان پس‌گرد (backtracking) تودرتویی که رخ می‌دهد (یعنی درخت الگو تا چه عمقی جستجو می‌شود). در مورد تطابق DFA، گزینه \fIdepth_limit\fP عمق فراخوانی‌های بازگشتی تابع داخلی را کنترل می‌کند که برای مدیریت بازگشت الگو، ادعاهای پیرامون‌نگاه (lookaround assertions) و گروه‌های اتمی استفاده می‌شود. .P برای تطابق غیر DFA، عدد \fImatch_limit\fP معیاری برای میزان پس‌گردی است که صورت می‌گیرد و فهمیدن حداقل مقدار می‌تواند آموزنده باشد. برای اکثر تطابق‌های ساده، این عدد نسبتاً کوچک است، اما برای الگوهایی با تعداد بسیار زیاد احتمالات تطابق، با افزایش طول رشته هدف می‌تواند خیلی سریع بسیار بزرگ شود. در مورد تطابق DFA، گزینه \fImatch_limit\fP تعداد کل فراخوانی‌ها (اعم از بازگشتی و غیربازگشتی) به تابع تطابق داخلی را کنترل می‌کند، و در نتیجه مقدار کلی منبع محاسباتی مورداستفاده را کنترل می‌نماید. .P برای هر دو نوع تطابق، عدد \fIheap_limit\fP که به کیبی‌بایت (واحدهای ۱۰۲۴ بایتی) است، مقدار حافظه هیپ استفاده‌شده برای تطابق را محدود می‌کند. . . .SS "نمایش نام‌های MARK" .rs .sp .P اصلاح‌کننده \fBmark\fP باعث می‌شود نام‌های حاصل از افعال کنترلی پس‌گرد (backtracking control verbs) که از فراخوانی‌های \fBpcre2_match()\fP بازگردانده می‌شوند، نمایش یابند. اگر یک mark برای یک تطابق، عدم تطابق یا تطابق جزئی بازگردانده شود، \fBpcre2test\fP آن را نشان می‌دهد. برای یک تطابق، در یک خط جداگانه قرار می‌گیرد و با \(dqMK:\(dq برچسب‌گذاری می‌شود. در غیر این صورت، به پیام عدم تطابق افزوده می‌شود. . . .SS "نمایش مصرف حافظه" .rs .sp اصلاح‌کننده \fBmemory\fP باعث می‌شود \fBpcre2test\fP اندازه تمام فراخوانی‌های تخصیص و آزادسازی حافظه هیپ را که در طول فراخوانی \fBpcre2_match()\fP یا \fBpcre2_dfa_match()\fP رخ می‌دهند، ثبت (log) کند. در حالت دوم، حافظه هیپ تنها زمانی استفاده می‌شود که یک تطابق به فضای کاری داخلی بیشتری نسبت به تخصیص پیش‌فرض روی پشته نیاز داشته باشد، بنابراین در بسیاری از موارد هیچ خروجی وجود نخواهد داشت. در طول تطابق با JIT هیچ حافظه هیپی تخصیص داده نمی‌شود. برای کارکرد این اصلاح‌کننده، اصلاح‌کننده \fBnull_context\fP نباید روی هر دوی الگو و رشته هدف تنظیم شده باشد، هرچند می‌تواند روی یکی از آن‌ها تنظیم شود. . . .SS "نمایش اندازه کلی بردار فریم‌های هیپ (heap frame)" .rs .sp اصلاح‌کننده \fBheapframes_size\fP برای تطابق‌هایی که از \fBpcre2_match()\fP بدون JIT استفاده می‌کنند مرتبط است. پس از اجرای یک تطابق (چه موفق و چه ناموفق)، اندازه (به بایت) بردار فریم‌های هیپ تخصیص‌یافته که به بلوک داده‌های تطابق متصل مانده است، نمایش داده می‌شود. اگر عمل تطابق شامل چندین فراخوانی برای \fBpcre2_match()\fP بود (برای نمونه، تطابق سراسری یا برای زمان‌سنجی)، تنها مقدار نهایی نشان داده می‌شود. .P این اصلاح‌کننده برای تطابق POSIX یا DFA، همراه با یک هشدار نادیده گرفته می‌شود. تطابق JIT از بردار فریم‌های هیپ استفاده نمی‌کند، بنابراین اندازه همیشه صفر است، مگر اینکه تطابق قبلی بدون JIT وجود داشته باشد. توجه داشته باشید که تعیین اندازه صفر برای بردار خروجی (به زیر مراجعه کنید) باعث می‌شود \fBpcre2test\fP بلوک داده‌های تطابق خود (و بردار فریم‌های هیپ مرتبط با آن) را آزاد کند و یک بلوک جدید تخصیص دهد. . . .SS "تنظیم آفست شروع" .rs .sp اصلاح‌کننده \fBoffset\fP یک آفست را در رشته هدف تعیین می‌کند که تطابق از آنجا آغاز می‌شود. مقدار آن تعداد واحدهای کد است، نه کاراکترها. . . .SS "تنظیم محدودیت آفست" .rs .sp اصلاح‌کننده \fBoffset_limit\fP محدودیتی را برای تطابق‌های مهارنشده (unanchored) تعیین می‌کند. اگر تطابقی با شروع در این آفست یا قبل از آن در رشته هدف یافت نشود، بازگشت \(dqno match\(dq داده می‌شود. مقدار داده تعداد واحدهای کد است، نه کاراکترها. هنگامی که از این اصلاح‌کننده استفاده می‌شود، اصلاح‌کننده \fBuse_offset_limit\fP باید برای الگو تنظیم شده باشد؛ در غیر این صورت، خطا ایجاد می‌شود. . . .SS "تنظیم اندازه بردار خروجی" .rs .sp اصلاح‌کننده \fBovector\fP تنها به خط رشته هدفی که در آن ظاهر می‌شود اعمال می‌گردد، هرچند طبیعتاً می‌توان از آن برای تنظیم پیش‌فرض در دستور \fB#subject\fP نیز استفاده کرد. این گزینه تعداد جفت‌های آفست موجود برای ذخیره اطلاعات تطابق را مشخص می‌کند. مقدار پیش‌فرض ۱۵ است. .P مقدار صفر هنگام آزمودن POSIX API مفید است، زیرا باعث می‌شود \fBregexec()\fP با یک بردار ضبط NULL فراخوانی شود. هنگام عدم آزمودن POSIX API، از مقدار صفر استفاده می‌شود تا باعث فراخوانی \fBpcre2_match_data_create_from_pattern()\fP برای ایجاد یک بلوک تطابق جدید با اندازه دقیقاً مناسب برای الگو شود. (ایجاد یک بلوک تطابق با ovector با طول صفر امکان‌پذیر نیست؛ همیشه حداقل یک جفت آفست وجود دارد.) بلوک داده‌های تطابق قدیمی آزاد می‌شود. . . .SS "ارسال رشته هدف به صورت خاتمه‌یافته با صفر" .rs .sp به‌طور پیش‌فرض، رشته هدف با طول صحیح خود به تابع تطابق API بومی ارسال می‌شود. به منظور آزمایش قابلیت ارسال رشته خاتمه‌یافته با صفر (zero-terminated)، اصلاح‌کننده \fBzero_terminate\fP ارائه شده است. این گزینه باعث می‌شود طول به عنوان PCRE2_ZERO_TERMINATED ارسال شود. هنگام تطابق از طریق رابط POSIX، این اصلاح‌کننده با یک هشدار نادیده گرفته می‌شود. .P هنگام آزمودن \fBpcre2_substitute()\fP، این اصلاح‌کننده همچنین اثر ارسال رشته جایگزین به صورت خاتمه‌یافته با صفر را دارد. . . .SS "ارسال زمینه، رشته هدف یا جایگزین NULL" .rs .sp به طور معمول، \fBpcre2test\fP یک بلوک زمینه را به \fBpcre2_match()\fP، \fBpcre2_dfa_match()\fP، \fBpcre2_jit_match()\fP یا \fBpcre2_substitute()\fP ارسال می‌کند. با این حال، اگر اصلاح‌کننده \fBnull_context\fP تنظیم شده باشد، NULL ارسال می‌شود. این برای آزمودن این است که آیا توابع تطابق و جایگزینی در این حالت به درستی رفتار می‌کنند یا خیر (آن‌ها از مقادیر پیش‌فرض استفاده می‌کنند). این اصلاح‌کننده را نمی‌توان همراه با اصلاح‌کننده‌های \fBfind_limits\fP، \fBfind_limits_noheap\fP یا \fBsubstitute_callout\fP استفاده کرد. .P به طور مشابه، برای اهداف آزمایشی، اگر اصلاح‌کننده \fBnull_subject\fP یا \fBnull_replacement\fP تنظیم شود، اشاره‌گرهای رشته هدف یا جایگزین به ترتیب به عنوان NULL به توابع مربوطه ارسال می‌شوند. . . .SH "تابع تطابق جایگزین" .rs .sp به‌طور پیش‌فرض، \fBpcre2test\fP از تابع تطابق استاندارد PCRE2 یعنی \fBpcre2_match()\fP برای تطابق هر خط رشته هدف استفاده می‌کند. PCRE2 همچنین از یک تابع تطابق جایگزین به نام \fBpcre2_dfa_match()\fP پشتیبانی می‌کند که به روش متفاوتی عمل می‌کند و دارای محدودیت‌هایی است. تفاوت‌های بین این دو تابع در مستندات .\" HREF \fBpcre2matching\fP .\" توضیح داده شده است. .P اگر اصلاح‌کننده \fBdfa\fP تنظیم شده باشد، تابع تطبیق جایگزین استفاده می‌شود. این تابع تمام تطابق‌های ممکن را در یک نقطه معین در رشته موضوع می‌یابد. اما اگر اصلاح‌کننده \fBdfa_shortest\fP تنظیم شده باشد، پردازش پس از یافتن اولین تطابق متوقف می‌شود. این تطابق همیشه کوتاه‌ترین تطابق ممکن است. . . .SH "خروجی پیش‌فرض از pcre2test (DEFAULT OUTPUT FROM pcre2test)" .rs .sp این بخش خروجی را در زمانی که تابع تطبیق عادی، \fBpcre2_match()\fP، استفاده می‌شود، توصیف می‌کند. .P هنگامی که یک تطابق با موفقیت انجام شود، \fBpcre2test\fP فهرستی از زیررشته‌های ضبط‌شده را خروجی می‌دهد که با شماره 0 برای رشته‌ای که با کل الگو تطابق یافته است شروع می‌شود. در غیر این صورت، در صورتی که مقدار بازگشتی PCRE2_ERROR_NOMATCH باشد عبارت "No match" را خروجی می‌دهد، یا در صورتی که مقدار بازگشتی PCRE2_ERROR_PARTIAL باشد "Partial match:" و به دنبال آن زیررشته‌ای که به صورت جزئی تطبیق یافته است را نمایش می‌دهد. (توجه داشته باشید که این کل زیررشته‌ای است که در طول تطبیق جزئی بررسی شده است؛ در صورتی که یک ادعای پس‌نگری (lookbehind)، \eK، \eb، یا \eB دخیل بوده باشد، ممکن است شامل نویسه‌های قبل از شروع واقعی تطابق نیز باشد.) .P برای هر مقدار بازگشتی دیگر، \fBpcre2test\fP شماره خطای منفی PCRE2 و یک عبارت توصیفی کوتاه را خروجی می‌دهد. اگر خطا ناشی از ناموفق بودن بررسی رشته UTF باشد، آفست واحد کد شروع نویسه نامعتبر نیز خروجی داده می‌شود. در اینجا نمونه‌ای از یک اجرای تعاملی \fBpcre2test\fP آورده شده است. .sp $ pcre2test PCRE2 version 10.22 2016-07-29 .sp re> /^abc(\ed+)/ data> abc123 0: abc123 1: 123 data> xyz No match .sp زیررشته‌های ضبط‌کننده‌ای که مقداردهی نشده‌اند و پس از آن‌ها زیررشته‌ای که مقداردهی شده باشد وجود ندارد، توسط \fBpcre2test\fP نمایش داده نمی‌شوند مگر اینکه اصلاح‌کننده \fBallcaptures\fP مشخص شده باشد. در مثال زیر، دو زیررشته ضبط‌کننده وجود دارد، اما هنگام تطبیق اولین خط داده، زیررشته دوم که مقداردهی نشده است نمایش داده نمی‌شود. یک زیررشته مقداردهی‌نشده «داخلی» به صورت "" نشان داده می‌شود، مانند خط داده دوم. .sp re> /(a)|(b)/ data> a 0: a 1: a data> b 0: b 1: 2: b .sp اگر رشته‌ها شامل هرگونه نویسه غیرقابل چاپ باشند، در صورتی که مقدار کمتر از 256 باشد و حالت UTF تنظیم نشده باشد به صورت گریزهای \exhh خروجی داده می‌شوند. در غیر این صورت به صورت گریزهای \ex{hh...} خروجی داده می‌شوند. برای تعریف نویسه‌های غیرقابل چاپ به ادامه متن مراجعه کنید. اگر اصلاح‌کننده \fBaftertext\fP تنظیم شده باشد، خروجی برای زیررشته 0 با باقی‌مانده رشته موضوع همراه می‌شود که با "0+" به این صورت مشخص می‌گردد: .sp re> /cat/aftertext data> cataract 0: cat 0+ aract .sp اگر تطبیق سراسری درخواست شود، نتایج تلاش‌های پی‌درپی تطبیق به ترتیب خروجی داده می‌شوند، مانند زیر: .sp re> /\eBi(\ew\ew)/g data> Mississippi 0: iss 1: ss 0: iss 1: ss 0: ipp 1: pp .sp عبارت "No match" تنها در صورتی خروجی داده می‌شود که اولین تلاش تطبیق ناموفق باشد. در اینجا نمونه‌ای از یک پیام خطا آورده شده است (آفست 4 که توسط اصلاح‌کننده \fBoffset\fP مشخص شده است فراتر از انتهای رشته موضوع است): .sp re> /xyz/ data> xyz\e=offset=4 Error -24 (bad offset value) .P توجه داشته باشید در حالی که الگوها می‌توانند در چند خط ادامه یابند (از یک اعلان ساده ">" برای ادامه‌ها استفاده می‌شود)، خطوط موضوع نمی‌توانند ادامه یابند. با این حال خطوط جدید را می‌توان با استفاده از گریز \en (یا \er، \er\en و غیره، بسته به تنظیمات توالی خط جدید) در یک موضوع گنجاند. . . . .SH "خروجی تابع تطبیق جایگزین (OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION)" .rs .sp هنگامی که از تابع تطبیق جایگزین، \fBpcre2_dfa_match()\fP، استفاده می‌شود، خروجی شامل فهرستی از تمام تطابق‌هایی است که از اولین نقطه در موضوع که حداقل یک تطابق در آن وجود دارد، شروع می‌شوند. برای مثال: .sp re> /(tang|tangerine|tan)/ data> yellow tangerine\e=dfa 0: tangerine 1: tang 2: tan .sp استفاده از تابع تطبیق عادی روی این داده‌ها تنها "tang" را پیدا می‌کند. طولانی‌ترین رشته منطبق همیشه ابتدا ارائه می‌شود (و با صفر شماره‌گذاری می‌گردد). پس از بازگشت PCRE2_ERROR_PARTIAL، خروجی "Partial match:" است که زیررشته منطبق‌شده به صورت جزئی به دنبال آن می‌آید. توجه داشته باشید که این کل زیررشته‌ای است که در طول تطبیق جزئی بررسی شده است؛ اگر ادعای پس‌نگری (lookbehind)، \eb، یا \eB دخیل بوده باشد، ممکن است شامل نویسه‌های قبل از شروع واقعی تطابق نیز باشد. (\eK برای تطبیق DFA پشتیبانی نمی‌شود.) .P اگر تطبیق سراسری درخواست شود، جستجو برای تطابق‌های بعدی از انتهای طولانی‌ترین تطابق از سر گرفته می‌شود. برای مثال: .sp re> /(tang|tangerine|tan)/g data> yellow tangerine and tangy sultana\e=dfa 0: tangerine 1: tang 2: tan 0: tang 1: tan 0: tan .sp تابع تطبیق جایگزین از ضبط زیررشته پشتیبانی نمی‌کند، بنابراین اصلاح‌کننده‌هایی که مربوط به زیررشته‌های ضبط‌شده هستند، کاربردی ندارند. . . .SH "شروع مجدد پس از تطبیق جزئی (RESTARTING AFTER A PARTIAL MATCH)" .rs .sp هنگامی که تابع تطبیق جایگزین مقدار بازگشتی PCRE2_ERROR_PARTIAL را داده است، که نشان می‌دهد موضوع تا حدی با الگو تطبیق یافته است، می‌توانید تطبیق را با داده‌های موضوعی اضافی به کمک اصلاح‌کننده \fBdfa_restart\fP مجدداً آغاز کنید. برای مثال: .sp re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ data> 23ja\e=ps,dfa Partial match: 23ja data> n05\e=dfa,dfa_restart 0: n05 .sp برای اطلاعات بیشتر درباره تطبیق جزئی، به مستندات .\" HREF \fBpcre2partial\fP .\" مراجعه کنید. . . .\" HTML .SH "فراخوانی‌ها (CALLOUTS)" .rs .sp اگر الگو شامل هرگونه درخواست فراخوانی (callout) باشد، تابع فراخوانی \fBpcre2test\fP در حین تطبیق صدا زده می‌شود مگر اینکه \fBcallout_none\fP مشخص شده باشد. این قابلیت با هر دو تابع تطبیق و همچنین با JIT کار می‌کند، هرچند تفاوت‌هایی در رفتار وجود دارد. خروجی برای فراخوانی‌های با آرگومان‌های عددی و فراخوانی‌های با آرگومان‌های رشته‌ای کمی متفاوت است. . . .SS "فراخوانی‌ها با آرگومان‌های عددی (Callouts with numerical arguments)" .rs .sp به‌طور پیش‌فرض، تابع فراخوانی شماره فراخوانی، موقعیت‌های شروع و فعلی در متن موضوع را در زمان فراخوانی، و مورد بعدی الگو را که باید آزمایش شود نمایش می‌دهد. برای مثال: .sp --->pqrabcdef 0 ^ ^ \ed .sp این خروجی نشان می‌دهد که فراخوانی شماره 0 برای یک تلاش تطبیق رخ داده است که از چهارمین نویسه رشته موضوع شروع شده، زمانی که اشاره‌گر در هفتمین نویسه بوده و مورد بعدی الگو \ed بوده است. اگر موقعیت شروع و موقعیت فعلی یکسان باشند، یا اگر موقعیت فعلی پیش از موقعیت شروع باشد (که در صورت قرار داشتن فراخوانی در یک ادعای پس‌نگری ممکن است رخ دهد)، تنها یک علامت هشتک (circumflex) خروجی داده می‌شود. .P فراخوانی‌های شماره 255 به عنوان فراخوانی‌های خودکار در نظر گرفته می‌شوند که در نتیجه اصلاح‌کننده الگوی \fBauto_callout\fP درج شده‌اند. در این حالت، به جای نمایش شماره فراخوانی، آفست در الگو که با علامت مثبت پیشوند شده است، خروجی داده می‌شود. برای مثال: .sp re> /\ed?[A-E]\e*/auto_callout data> E* --->E* +0 ^ \ed? +3 ^ [A-E] +8 ^^ \e* +10 ^ ^ 0: E* .sp اگر یک الگو شامل موارد (*MARK) باشد، هر زمان که تغییری در آخرین علامت (mark) به تابع فراخوانی ارسال شود، یک خط اضافی خروجی داده می‌شود. برای مثال: .sp re> /a(*MARK:X)bc/auto_callout data> abc --->abc +0 ^ a +1 ^^ (*MARK:X) +10 ^^ b Latest Mark: X +11 ^ ^ c +12 ^ ^ 0: abc .sp علامت بین تطبیق "a" و "b" تغییر می‌کند، اما برای بقیه تطابق ثابت می‌ماند، بنابراین خروجی دیگری تولید نمی‌شود. اگر در نتیجه پس‌گرد (backtracking)، علامت به حالت مقداردهی‌نشده بازگردد، متن "" خروجی داده می‌شود. . . .SS "فراخوانی‌ها با آرگومان‌های رشته‌ای (Callouts with string arguments)" .rs .sp خروجی برای یک فراخوانی با آرگومان رشته‌ای مشابه است، به جز اینکه به جای خروجی دادن شماره فراخوانی قبل از نشانگرهای موقعیت، رشته فراخوانی و آفست آن در رشته الگو قبل از بازتاب رشته موضوع خروجی داده می‌شوند، و رشته موضوع برای هر فراخوانی بازتاب می‌یابد. برای مثال: .sp re> /^ab(?C'first')cd(?C"second")ef/ data> abcdefg Callout (7): 'first' --->abcdefg ^ ^ c Callout (20): "second" --->abcdefg ^ ^ e 0: abcdef .sp . . .SS "اصلاح‌کننده‌های فراخوانی (Callout modifiers)" .rs .sp تابع فراخوانی در \fBpcre2test\fP به‌طور پیش‌فرض مقدار صفر (ادامه تطبیق) را بازمی‌گرداند، اما می‌توانید از یک اصلاح‌کننده \fBcallout_fail\fP در یک خط موضوع برای تغییر این رفتار و سایر پارامترهای فراخوانی استفاده کنید (به زیر مراجعه کنید). .P اگر اصلاح‌کننده \fBcallout_capture\fP تنظیم شده باشد، گروه‌های ضبط‌شده فعلی هنگام وقوع یک فراخوانی خروجی داده می‌شوند. این مورد تنها برای تطبیق غیر DFA مفید است، زیرا \fBpcre2_dfa_match()\fP از ضبط پشتیبانی نمی‌کند، بنابراین هیچ گروه ضبط‌شده‌ای هرگز نمایش داده نمی‌شود. .P خروجی عادی فراخوانی، که شماره فراخوانی یا آفست الگو را نشان می‌دهد (همان‌طور که در بالا شرح داده شد)، در صورتی که اصلاح‌کننده \fBcallout_no_where\fP تنظیم شده باشد سرکوب می‌شود. .P هنگام استفاده از تابع تطبیق تفسیری \fBpcre2_match()\fP بدون JIT، تنظیم اصلاح‌کننده \fBcallout_extra\fP باعث می‌شود خروجی اضافی از تابع فراخوانی \fBpcre2test\fP تولید شود. برای اولین فراخوانی در یک تلاش تطبیق در موقعیت شروع جدید در موضوع، عبارت "New match attempt" خروجی داده می‌شود. اگر از زمان آخرین فراخوانی (یا شروع تطبیق اگر این اولین فراخوانی باشد) پس‌گرد (backtrack) رخ داده باشد، عبارت "Backtrack" خروجی داده می‌شود، و به دنبال آن در صورتی که پس‌گرد به تلاش قبلی تطبیق پایان داده باشد، عبارت "No other matching paths" می‌آید. برای مثال: .sp re> /(a+)b/auto_callout,no_start_optimize,no_auto_possess data> aac\e=callout_extra New match attempt --->aac +0 ^ ( +1 ^ a+ +3 ^ ^ ) +4 ^ ^ b Backtrack --->aac +3 ^^ ) +4 ^^ b Backtrack No other matching paths New match attempt --->aac +0 ^ ( +1 ^ a+ +3 ^^ ) +4 ^^ b Backtrack No other matching paths New match attempt --->aac +0 ^ ( +1 ^ a+ Backtrack No other matching paths New match attempt --->aac +0 ^ ( +1 ^ a+ No match .sp توجه داشته باشید که اگر می‌خواهید تمام مسیرهای ممکن تطبیق بررسی شوند، بهینه‌سازی‌های مختلف باید خاموش شوند. اگر \fBno_start_optimize\fP استفاده نشود، یک "no match" فوری بدون هیچ فراخوانی رخ می‌دهد، زیرا بهینه‌سازی شروع نمی‌تواند "b" را در موضوع پیدا کند، که می‌داند برای هر تطابقی باید حضور داشته باشد. اگر \fBno_auto_possess\fP استفاده نشود، مورد "a+" به "a++" تبدیل می‌شود، که تعداد پس‌گردها را کاهش می‌دهد. .P اصلاح‌کننده \fBcallout_extra\fP در صورت استفاده با تابع تطبیق DFA یا با JIT هیچ تاثیری ندارد. . . .SS "مقادیر بازگشتی از فراخوانی‌ها (Return values from callouts)" .rs .sp مقدار بازگشتی پیش‌فرض از تابع فراخوانی صفر است که به تطبیق اجازه می‌دهد ادامه یابد. به اصلاح‌کننده \fBcallout_fail\fP می‌توان یک یا دو عدد اختصاص داد. اگر تنها یک عدد وجود داشته باشد، هنگامی که به فراخوانی آن شماره رسیده شود مقدار 1 به جای 0 بازگردانده می‌شود (که باعث پس‌گرد در تطبیق می‌گردد). اگر دو عدد (:) داده شود، هنگامی که به فراخوانی رسیده شود و حداقل فراخوانی وجود داشته باشد، مقدار 1 بازگردانده می‌شود. اصلاح‌کننده \fBcallout_error\fP نیز مشابه است، با این تفاوت که مقدار PCRE2_ERROR_CALLOUT بازگردانده می‌شود و باعث می‌گردد کل فرآیند تطبیق لغو شود. اگر هر دوی این اصلاح‌کننده‌ها برای یک شماره فراخوانی تنظیم شوند، \fBcallout_error\fP تقدم دارد. توجه داشته باشید که به فراخوانی‌های با آرگومان‌های رشته‌ای همیشه شماره صفر اختصاص داده می‌شود. .P به اصلاح‌کننده \fBcallout_data\fP می‌توان یک عدد بدون علامت یا منفی داد. این مقدار به عنوان "user data" تنظیم می‌شود که به تابع تطبیق ارسال می‌گردد و هنگام فراخوانی تابع callout برگردانده می‌شود. هر مقداری غیر از صفر به عنوان مقدار بازگشتی از تابع فراخوانی \fBpcre2test\fP استفاده می‌شود. .P درج فراخوانی‌ها می‌تواند هنگام استفاده از \fBpcre2test\fP برای بررسی عبارت‌های منظم پیچیده مفید باشد. برای اطلاعات بیشتر درباره فراخوانی‌ها، به .\" HREF \fBpcre2callout\fP .\" مستندات مراجعه کنید. . . . .SH "نویسه‌های غیرقابل چاپ (NON-PRINTING CHARACTERS)" .rs .sp هنگامی که \fBpcre2test\fP متنی را در نسخه کامپایل‌شده یک الگو خروجی می‌دهد، بایت‌های غیر از 32-126 همیشه به عنوان نویسه‌های غیرقابل چاپ در نظر گرفته می‌شوند و بنابراین به صورت گریزهای هگزادسیمال نمایش داده می‌شوند. .P هنگامی که \fBpcre2test\fP متنی را خروجی می‌دهد که بخشی منطبق‌شده از یک رشته موضوع است، به همان روش عمل می‌کند، مگر اینکه محلی‌سازی (locale) متفاوتی برای الگو تنظیم شده باشد (با استفاده از اصلاح‌کننده \fBlocale\fP). در این حالت، تابع \fBisprint()\fP برای تمایز بین نویسه‌های قابل چاپ و غیرقابل چاپ استفاده می‌شود. . . . .\" HTML .SH "ذخیره و بازیابی الگوهای کامپایل‌شده (SAVING AND RESTORING COMPILED PATTERNS)" .rs .sp امکان ذخیره الگوهای کامپایل‌شده روی دیسک یا هر جای دیگر و بارگذاری مجدد آن‌ها در آینده، با رعایت تعدادی محدودیت، وجود دارد. داده‌های JIT قابل ذخیره‌سازی نیستند. میزبانی که الگوها روی آن بازگذاری مجدد می‌شوند باید نسخه یکسانی از PCRE2 را با عرض واحد کد یکسان اجرا کند، و همچنین باید دارای ترتیب بایت (endianness)، عرض اشاره‌گر و نوع PCRE2_SIZE یکسان باشد. پیش از آنکه الگوهای کامپایل‌شده ذخیره شوند باید سریال‌سازی شوند، یعنی به یک جریان از بایت‌ها تبدیل گردند. یک جریان بایت منفرد می‌تواند شامل هر تعداد الگوی کامپایل‌شده باشد، اما همه آن‌ها باید از جداول نویسه یکسانی استفاده کنند. یک نسخه واحد از جداول در جریان بایت گنجانده می‌شود (اندازه آن 1088 بایت است). .P توابعی که نام آن‌ها با \fBpcre2_serialize_\fP آغاز می‌شود، برای سریال‌سازی و واسریال‌سازی (de-serializing) به کار می‌روند. این توابع در مستندات .\" HREF \fBpcre2serialize\fP .\" توضیح داده شده‌اند. در این بخش، قابلیت‌هایی از \fBpcre2test\fP را شرح می‌دهیم که می‌توانند برای آزمودن این توابع استفاده شوند. .P توجه داشته باشید که «سریال‌سازی» در PCRE2 الگوهای کامپایل‌شده را به یک قالب انتزاعی مانند جاوا یا ‎.NET‎ تبدیل نمی‌کند؛ بلکه صرفاً یک جریان بایت‌کد با قابلیت بارگذاری مجدد ایجاد می‌کند. از این رو محدودیت‌های بارگذاری مجدد که در بالا ذکر شد اعمال می‌شوند. .P در \fBpcre2test\fP، هنگامی که یک الگو با اصلاح‌کننده \fBpush\fP با موفقیت کامپایل می‌شود، به پشته الگوهای کامپایل‌شده رانده (push) می‌شود و \fBpcre2test\fP انتظار دارد خط بعدی به‌جای خط موضوع (subject)، شامل یک الگوی جدید (یا دستور) باشد. در مقابل، اصلاح‌کننده \fBpushcopy\fP باعث می‌شود نسخه‌ای از الگوی کامپایل‌شده روی پشته قرار گیرد و نسخه اصلی را برای تطبیق فوری در دسترس باقی گذارد. با استفاده از \fBpush\fP و/یا \fBpushcopy\fP، می‌توان تعدادی الگو را کامپایل و نگهداری کرد. این اصلاح‌کننده‌ها با \fBposix\fP ناسازگار هستند و اصلاح‌کننده‌های کنترلی که در زمان تطبیق عمل می‌کنند، برای الگوهای روی پشته نادیده گرفته می‌شوند (همراه با پیام). اصلاح‌کننده \fBjitverify\fP تنها در زمان کامپایل اعمال می‌شود. .P دستور .sp #save .sp باعث می‌شود تمامی الگوهای موجود روی پشته سریال‌سازی شده و نتیجه در فایل نام‌برده نوشته شود. پس از آن، تمامی الگوهای روی پشته آزاد می‌شوند. دستور .sp #load .sp داده‌های درون فایل را خوانده و سپس شرایط را برای واسریال‌سازی آن فراهم می‌کند، به‌طوری که الگوهای کامپایل‌شده حاصل به پشته الگوها اضافه می‌شوند. الگوی بالای پشته را می‌توان با دستور #pop بازیابی کرد؛ پس از این دستور باید خطوط موضوعی که قرار است با الگو تطبیق داده شوند بیایند که طبق معمول با یک خط خالی یا پایان فایل خاتمه می‌یابند. این دستور ممکن است با فهرستی از اصلاح‌کننده‌ها دنبال شود که تنها شامل .\" HTML .\" اصلاح‌کننده‌های کنترلی .\" هستند که پس از کامپایل شدن الگو عمل می‌کنند. به‌ویژه، \fBhex\fP، \fBposix\fP، \fBposix_nosub\fP، \fBpush\fP و \fBpushcopy\fP مجاز نیستند و هیچ‌یک از .\" HTML .\" اصلاح‌کننده‌های تنظیم‌کننده گزینه‌ها .\" نیز مجاز نمی‌باشند. اصلاح‌کننده‌های JIT، با این حال مجاز هستند. در اینجا مثالی آمده است که دو الگو را ذخیره و دوباره بارگذاری می‌کند: .sp /abc/push /xyz/push #save tempfile #load tempfile #pop info xyz .sp #pop jit,bincode abc .sp اگر \fBjitverify\fP با #pop استفاده شود، به‌طور خودکار به معنای \fBjit\fP نیست، که رفتاری متفاوت با زمان استفاده از آن روی یک الگو است. .P دستور #popcopy مشابه اصلاح‌کننده \fBpushcopy\fP است، از این نظر که رونوشتی از بالاترین الگوی پشته را فعال می‌کند و الگوی اصلی همچنان روی پشته باقی می‌ماند. . . . .SH "همچنین ببینید (SEE ALSO)" .rs .sp \fBpcre2\fP(3), \fBpcre2api\fP(3), \fBpcre2callout\fP(3), \fBpcre2jit\fP, \fBpcre2matching\fP(3), \fBpcre2partial\fP(d), \fBpcre2pattern\fP(3), \fBpcre2serialize\fP(3). . . .SH "نویسنده (AUTHOR)" .rs .sp .nf Philip Hazel Retired from University Computing Service Cambridge, England. .fi . . .SH "بازبینی (REVISION)" .rs .sp .nf Last updated: 22 August 2026 Copyright (c) 1997-2024 University of Cambridge. .fi