ورودی برای کتابخانه‌های ۱۶ بیتی و ۳۲ بیتی (Input for the 16-bit and 32-bit libraries)

هنگام آزمایش کتابخانه‌های ۱۶ بیتی یا ۳۲ بیتی، نیاز است که بتوان نقاط کد نویسه‌ای (character code points) بزرگتر از ۲۵۵ را در رشته‌های ارسالی به کتابخانه تولید کرد. برای خطوط رشته هدف و برخی الگوها، می‌توان از توالی‌های گریز بک‌اسلش استفاده کرد. علاوه بر این، هنگامی که اصلاح‌کننده utf (بخش "تنظیم گزینه‌های کامپایل" در زیر را ببینید) تنظیم شده باشد، الگو و هر خط رشته هدف پس از آن به عنوان رشته‌های UTF-8 تفسیر شده و بر حسب مورد به UTF-16 یا UTF-32 ترجمه می‌شوند.

برای آزمایش غیر UTF نویسه‌های عریض (wide characters)، می‌توان از اصلاح‌کننده utf8_input استفاده کرد. این اصلاح‌کننده مانعة‌الجمع با utf است و فقط در حالت ۱۶ بیتی یا ۳۲ بیتی مجاز است. این اصلاح‌کننده باعث می‌شود الگو و خطوط رشته هدف بعدی مطابق با تعریف اولیه (RFC 2279) به عنوان UTF-8 در نظر گرفته شوند که مقادیر نویسه‌ای تا 0x7fffffff را مجاز می‌داند. هر نویسه در یک واحد کد ۱۶ بیتی یا ۳۲ بیتی قرار می‌گیرد (در حالت ۱۶ بیتی، مقادیر بزرگتر از 0xffff باعث بروز خطا می‌شوند).

کدگذاری UTF-8 (در تعریف اولیه آن) قادر به کدگذاری مقادیر بزرگتر از 0x7fffffff نیست، اما چنین مقادیری توسط کتابخانه ۳۲ بیتی قابل مدیریت هستند. هنگام آزمایش این کتابخانه در حالت غیر UTF با تنظیم utf8_input، اگر پیش از هر نویسه، بایت 0xff قرار گیرد (که بایتی نامعتبر در UTF-8 است)، مقدار 0x80000000 به مقدار آن نویسه اضافه می‌شود. برای رشته‌های هدف، استفاده از توالی گریز ترجیح دارد.

تنظیم گزینه‌های کامپایل (Setting compilation options)

تغییردهنده‌های زیر گزینه‌هایی را برای pcre2_compile() تنظیم می‌کنند. بیشتر آن‌ها بیت‌هایی را در آرگومان گزینه‌های آن تابع تنظیم می‌کنند، اما مواردی که نام آن‌ها با PCRE2_EXTRA آغاز می‌شود، گزینه‌های اضافه‌ای هستند که در زمینهٔ کامپایل (compile context) تنظیم می‌شوند. برخی از این گزینه‌ها اختصارات تک‌حرفی دارند. رفتار ویژه‌ای برای /x وجود دارد: اگر یک x دوم وجود داشته باشد، همانند Perl مقدار PCRE2_EXTENDED به PCRE2_EXTENDED_MORE تبدیل می‌شود. حضور x سوم، گزینهٔ PCRE2_EXTENDED را نیز اضافه می‌کند، اگرچه این کار تفاوتی در رفتار pcre2_compile() ایجاد نمی‌کند. برای شرح اثرات این گزینه‌ها، مستندات pcre2api را ببینید.

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

تغییردهندهٔ utf علاوه بر فعال کردن گزینهٔ PCRE2_UTF، باعث می‌شود تمام نویسه‌های غیرقابل‌چاپ در رشته‌های خروجی با استفاده از قالب \x{hh...} چاپ شوند. در غیر این صورت، موارد کمتر از 0x100 به‌صورت هگزادسیمال بدون آکولاد چاپ می‌شوند. همچنین تنظیم utf در حالت ۱۶ بیتی یا ۳۲ بیتی موجب می‌شود رشته‌های الگو و هدف پیش از ارسال به توابع کتابخانه، به ترتیب به UTF-16 یا UTF-32 ترجمه شوند.

تغییردهنده‌های زیر با فراخوانی pcre2_set_optimize() پیش از اجرای کامپایلر عبارات باقاعده، بهینه‌سازی‌های کارایی را فعال یا غیرفعال می‌کنند:

optimization_full فعال‌سازی تمام بهینه‌سازی‌های اختیاری
optimization_none غیرفعال‌سازی تمام بهینه‌سازی‌های اختیاری
auto_possess تملک خودکار سورهای متغیر
auto_possess_off عدم تملک خودکار سورهای متغیر
dotstar_anchor لنگر کردن الگوهای آغازشونده با .*
dotstar_anchor_off عدم لنگر کردن الگوهای آغازشونده با .*
start_optimize فعال‌سازی پیش‌پیمایش رشتهٔ هدف
start_optimize_off غیرفعال‌سازی پیش‌پیمایش رشتهٔ هدف

برای جزئیات بیشتر دربارهٔ این بهینه‌سازی‌ها مستندات pcre2_set_optimize را ببینید.

تنظیم کنترل‌های کامپایل (Setting compilation controls)

تغییردهنده‌های زیر بر فرآیند کامپایل تأثیر می‌گذارند یا اطلاعاتی را دربارهٔ الگو درخواست می‌کنند. برای برخی مواردی که در فایل‌های آزمون کاربرد فراوان دارند، اختصارات تک‌حرفی وجود دارد.

/B bincode نمایش کد باینری بدون طول
bsr=[anycrlf|unicode] مشخص کردن نحوهٔ مدیریت \R
callout_info نمایش اطلاعات کال‌اوت (callout)
convert=<options> درخواست تبدیل الگوی خارجی
convert_glob_escape=c تنظیم نویسهٔ گریز glob
convert_glob_separator=c تنظیم نویسهٔ جداکنندهٔ glob
convert_length تنظیم طول بافر تبدیل
debug مشابه info,fullbincode
expand بسط ساختار تکرار در الگو
framesize نمایش اندازهٔ فریم تطبیق
fullbincode نمایش کد باینری به همراه طول
/I info نمایش اطلاعات دربارهٔ الگوی کامپایل‌شده
hex نویسه‌های خارج از نقل‌قول هگزادسیمال هستند
jit[=<number>] استفاده از JIT
jitfast استفاده از مسیر سریع JIT
jitverify تأیید صحت استفاده از JIT
locale=<name> استفاده از این لوکال (locale)
max_pattern_compiled ) تنظیم حداکثر طول الگوی کامپایل‌شده
_length=<n> ) (به بایت)
max_pattern_length=<n> تنظیم حداکثر طول الگو (واحدهای کد)
max_varlookbehind=<n> تنظیم حداکثر طول تطبیق پس‌نگر متغیر
memory نمایش حافظهٔ استفاده‌شده
newline=<type> تنظیم نوع خط جدید
null_context کامپایل با یک زمینهٔ NULL
null_pattern ارسال الگو به‌صورت NULL
parens_nest_limit=<n> تنظیم حداکثر عمق پرانتزها
posix استفاده از POSIX API
posix_nosub استفاده از POSIX API همراه با REG_NOSUB
push قراردادن الگوی کامپایل‌شده روی پشته
pushcopy قراردادن یک کپی روی پشته
pushtablescopy قراردادن یک کپی همراه با جداول روی پشته
stackguard=<number> آزمایش قابلیت stackguard
subject_literal در نظر گرفتن تمام خطوط هدف به‌صورت لفظی
tables=[0|1|2|3] انتخاب جداول داخلی
use_length الگو با نویسهٔ صفر خاتمه داده نشود
utf8_input در نظر گرفتن ورودی به‌صورت UTF-8

تأثیرات این تغییردهنده‌ها در بخش‌های بعدی شرح داده شده است.

مدیریت خط جدید (Newline) و \R

تغییردهندهٔ bsr مشخص می‌کند که \R در یک الگو باید با چه چیزی تطبیق یابد. اگر روی "anycrlf" تنظیم شود، \R فقط با CR، LF یا CRLF تطبیق می‌یابد. اگر روی "unicode" تنظیم شود، \R با هر توالی خط جدید در یونیکد تطبیق پیدا می‌کند. پیش‌فرض را می‌توان هنگام ساخت PCRE2 مشخص کرد؛ در غیر این صورت، مقدار پیش‌فرض روی Unicode تنظیم می‌شود.

تغییردهندهٔ newline مشخص می‌کند که کدام نویسه‌ها باید هم در الگو و هم در خطوط هدف (subject) به عنوان خط جدید تفسیر شوند. نوع باید یکی از CR، LF، CRLF، ANYCRLF، ANY یا NUL باشد (با حروف بزرگ یا کوچک).

اطلاعات دربارهٔ یک الگو

تغییردهندهٔ debug کوته‌نوشتی برای info,fullbincode است که تمام اطلاعات موجود را درخواست می‌کند.

تغییردهندهٔ bincode باعث می‌شود نمایشی از کد کامپایل‌شده پس از کامپایل در خروجی چاپ شود. این اطلاعات حاوی مقادیر طول و آفست نیست، که تضمین می‌کند خروجی یکسانی برای اندازه‌های مختلف پیوند داخلی (internal link sizes) و عرض‌های مختلف واحد کد (code unit widths) تولید می‌شود. با استفاده از bincode، می‌توان از همان آزمون‌های رگرسیون در محیط‌های مختلف استفاده کرد.

در مقابل، تغییردهندهٔ fullbincode مقادیر طول و آفست را شامل می‌شود. این مورد در چند آزمون خاص استفاده می‌شود که تنها برای عرض‌های واحد کد و اندازه‌های پیوند مشخصی اجرا می‌شوند، و همچنین برای آزمون‌های یک‌باره کاربرد دارد.

تغییردهندهٔ info اطلاعاتی دربارهٔ الگوی کامپایل‌شده درخواست می‌کند (اینکه آیا مهار شده است، نویسهٔ اول ثابتی دارد، و غیره). این اطلاعات از تابع pcre2_pattern_info() به دست می‌آید. در اینجا چند نمونه معمولی آورده شده است:

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

re> /(?i)abc/info
Capture group count = 0
Compile options: <none>
Overall options: caseless
First code unit = 'a' (caseless)
Last code unit = 'c' (caseless)
Subject length lower bound = 3

عبارت «Compile options» گزینه‌هایی هستند که توسط تغییردهنده‌ها مشخص شده‌اند؛ «overall options» گزینه‌های اضافه‌ای دارند که از خود الگو گرفته یا استنتاج شده‌اند. اگر هر دو مجموعه گزینه یکسان باشند، تنها یک خط «options» در خروجی چاپ می‌شود؛ اگر هیچ گزینه‌ای وجود نداشته باشد، این خط حذف می‌شود. عبارت «First code unit» جایی است که هر تطبیق باید از آنجا آغاز شود؛ اگر بیش از یک مورد باشد، تحت عنوان «starting code units» فهرست می‌شوند. «Last code unit» آخرین واحد کد لفظی است که باید در هر تطبیق وجود داشته باشد. این لزوماً آخرین نویسه نیست. اگر هیچ واحد کد ابتدایی یا انتهایی ثبت نشده باشد، این خطوط حذف می‌شوند. خط طول رشتهٔ هدف هنگامی که no_start_optimize تنظیم شده باشد حذف می‌شود، زیرا وقتی حداقل طول هرگز قابل استفاده نباشد، محاسبه نمی‌شود.

تغییردهندهٔ framesize اندازه (به بایت) هر فریم ذخیره‌سازی را نشان می‌دهد که توسط pcre2_match() برای مدیریت پس‌گرد (backtracking) استفاده می‌شود. اندازه به تعداد پرانتزهای گیرنده در الگو بستگی دارد. برداری از این فریم‌ها در زمان تطبیق استفاده می‌شود؛ اندازهٔ کلی آن زمانی نشان داده می‌شود که تغییردهندهٔ هدف heapframes_size تنظیم شده باشد.

تغییردهندهٔ callout_info اطلاعاتی دربارهٔ تمام کال‌اوت‌های موجود در الگو درخواست می‌کند. فهرستی از آن‌ها در انتهای هر اطلاعات درخواستی دیگر در خروجی قرار می‌گیرد. برای هر کال‌اوت، شماره یا رشتهٔ آن و به دنبال آن آیتمی که بعد از آن در الگو می‌آید آورده می‌شود.

ارسال یک زمینهٔ NULL

در حالت عادی، pcre2test یک بلوک زمینه را به pcre2_compile() ارسال می‌کند. با این حال، اگر تغییردهندهٔ null_context تنظیم شده باشد، مقدار NULL ارسال می‌شود. این برای آزمایش رفتار صحیح pcre2_compile() در این حالت است (از مقادیر پیش‌فرض استفاده می‌کند).

ارسال یک الگوی NULL

تغییردهندهٔ null_pattern برای آزمایش رفتار pcre2_compile() زمانی است که آرگومان الگو NULL باشد. مقدار طول ارسالی همان پیش‌فرض PCRE2_ZERO_TERMINATED است مگر اینکه use_length تنظیم شده باشد. هر طولی غیر از صفر باعث ایجاد خطا می‌شود.

مشخص کردن نویسه‌های الگو در مبنای شانزده

تغییردهندهٔ hex مشخص می‌کند که نویسه‌های الگو، به جز زیررشته‌های محصور در نقل‌قول تکی یا دوتایی، باید به عنوان جفت‌ارقام هگزادسیمال تفسیر شوند. این قابلیت به عنوان روشی برای ایجاد الگوهایی ارائه شده است که شامل صفرهای دودویی و سایر نویسه‌های غیرقابل‌چاپ هستند. وجود فاصله خالی میان جفت‌ارقام مجاز است. به عنوان مثال، این الگو شامل سه نویسه است:

/ab 32 59/hex

بخش‌هایی از چنین الگویی در صورت قرار گرفتن در نقل‌قول، به صورت لفظی (literal) در نظر گرفته می‌شوند. این الگو شامل نه نویسه است که فقط دو تای آن‌ها در مبنای شانزده مشخص شده‌اند:

/ab "literal" 32/hex

می‌توان از نقل‌قول تکی یا دوتایی استفاده کرد. راهی برای گنجاندن جداکننده در داخل یک زیررشته وجود ندارد. تغییردهنده‌های hex و expand مانعة‌الجمع هستند.

مشخص کردن طول الگو

به طور پیش‌فرض، الگوها به عنوان رشته‌های خاتمه‌یافته با صفر (zero-terminated) به توابع کامپایل ارسال می‌شوند، اما می‌توان آن‌ها را به جای خاتمه با صفر، با تعیین طول ارسال کرد. تغییردهندهٔ use_length باعث این اتفاق می‌شود. ارسال با تعیین طول زمانی که hex تنظیم شده باشد به طور خودکار انجام می‌شود (چه use_length تنظیم شده باشد چه نباشد)، زیرا الگوهای مشخص‌شده در مبنای شانزده ممکن است حاوی صفرهای دودویی باشند.

اگر hex یا use_length همراه با رابط برنامه‌نویسی بسته‌بند POSIX استفاده شوند (بخش «استفاده از رابط برنامه‌نویسی بسته‌بند POSIX» در زیر را ببینید)، افزونهٔ REG_PEND برای ارسال طول الگو استفاده می‌شود.

مشخص کردن حداکثر برای پس‌نگری‌های متغیر

ارهان‌های پس‌نگری متغیر (Variable lookbehind assertions) تنها در صورتی پشتیبانی می‌شوند که برای هر کدام، حداکثر طولی (بر حسب نویسه) که می‌تواند با آن تطبیق یابد وجود داشته باشد. محدودیتی برای این موضوع وجود دارد که مقدار پیش‌فرض آن را می‌توان در زمان ساخت تعیین کرد، و پیش‌فرض نهایی آن ۲۵۵ است. تغییردهندهٔ max_varlookbehind از تابع pcre2_set_max_varlookbehind() برای تغییر این محدودیت استفاده می‌کند. پس‌نگری‌هایی که شاخه‌های آن‌ها هر کدام با یک طول ثابت تطبیق می‌یابند، به ۶۵۵۳۵ نویسه در هر شاخه محدود هستند.

مشخص کردن نویسه‌های عریض در حالت‌های ۱۶ بیتی و ۳۲ بیتی

در حالت‌های ۱۶ بیتی و ۳۲ بیتی، زمانی که تغییردهندهٔ utf تنظیم شده باشد، تمام ورودی به طور خودکار به عنوان UTF-8 در نظر گرفته شده و به UTF-16 یا UTF-32 ترجمه می‌شود. برای آزمایش کتابخانه‌های ۱۶ بیتی و ۳۲ بیتی در حالت غیر UTF، می‌توان از تغییردهندهٔ utf8_input استفاده کرد. این گزینه با utf مانعة‌الجمع است. خطوط ورودی به عنوان روشی برای مشخص کردن نویسه‌های عریض، به صورت UTF-8 تفسیر می‌شوند. جزئیات بیشتر در بخش «کدگذاری ورودی» در بالا آمده است.

تولید الگوهای تکراری طولانی

برخی آزمون‌ها از الگوهای طولانی که بسیار تکراری هستند استفاده می‌کنند. به جای ایجاد یک خط ورودی بسیار طولانی برای چنین الگویی، می‌توانید از قابلیت تکرار ویژه استفاده کنید، مشابه آنچه برای خطوط هدف در بالا شرح داده شد. اگر تغییردهندهٔ expand روی یک الگو وجود داشته باشد، بخش‌هایی از الگو که به شکل

\[<characters>]{<count>}

هستند، قبل از ارسال الگو به pcre2_compile() گسترش می‌یابند. برای مثال، \[AB]{6000} به مقدار "ABAB..." تا ۶۰۰۰ بار گسترش می‌یابد. این ساختار نمی‌تواند تو در تو باشد. توالی ابتدایی "\[" تنها در صورتی تشخیص داده می‌شود که "]{" به دنبال ارقام ده‌دهی و "}" در ادامهٔ الگو یافت شود. در غیر این صورت، نویسه‌ها بدون تغییر در الگو باقی می‌مانند. تغییردهنده‌های expand و hex مانعة‌الجمع هستند.

اگر بخشی از یک الگوی گسترش‌یافته شبیه به ساختار گسترش باشد اما در واقع بخشی از خود الگوی اصلی باشد، با دادن دو مقدار در کمیت‌سنج می‌توان از گسترش ناخواسته جلوگیری کرد. برای مثال، \[AB]{6000,6000} به عنوان یک آیتم گسترش شناخته نمی‌شود.

اگر تغییردهندهٔ info روی یک الگوی گسترش‌یافته تنظیم شده باشد، نتیجهٔ گسترش در اطلاعات خروجی گنجانده می‌شود.

کامپایل درجا (JIT compilation)

کامپایل درجا یا Just-in-time (JIT) یک بهینه‌سازی سنگین است که می‌تواند سرعت تطبیق الگو را به میزان قابل توجهی افزایش دهد. برای جزئیات به مستندات pcre2jit مراجعه کنید. کامپایل JIT به صورت اختیاری، پس از کامپایل موفق الگو به یک فرم داخلی، انجام می‌شود. کامپایلر JIT این فرم را به کد ماشین بهینه‌شده تبدیل می‌کند. کامپایلر باید بداند که آیا گزینه‌های زمان تطبیق PCRE2_PARTIAL_HARD و PCRE2_PARTIAL_SOFT استفاده خواهند شد یا خیر، زیرا کدهای متفاوتی برای حالت‌های مختلف تولید می‌شود. برای جزئیات نحوه مشخص کردن این گزینه‌ها برای هر تلاش تطبیق، تغییردهندهٔ partial را در «تغییردهنده‌های هدف» در زیر ببینید.

کامپایل JIT توسط تغییردهندهٔ الگوی jit درخواست می‌شود، که می‌تواند به صورت اختیاری با یک علامت مساوی و عددی در محدودهٔ ۰ تا ۷ همراه باشد. سه بیتی که این عدد را تشکیل می‌دهند مشخص می‌کنند کدام یک از سه حالت عملیاتی JIT باید کامپایل شوند:

1 compile JIT code for non-partial matching
2 compile JIT code for soft partial matching
4 compile JIT code for hard partial matching

بنابراین مقادیر مجاز برای تغییردهندهٔ jit عبارتند از:

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

اگر عددی داده نشود، مقدار ۷ در نظر گرفته می‌شود. عبارت «partial matching» (تطبیق جزئی) به معنای فراخوانی pcre2_match() با تنظیم یکی از گزینه‌های PCRE2_PARTIAL_SOFT یا PCRE2_PARTIAL_HARD است. توجه داشته باشید که چنین فراخوانی ممکن است یک تطبیق کامل را بازگرداند؛ این گزینه‌ها امکان تطبیق جزئی را فراهم می‌کنند، اما آن را الزامی نمی‌سازند. همچنین توجه داشته باشید که اگر کامپایل JIT را فقط برای تطبیق جزئی درخواست کنید (برای مثال jit=2) اما تغییردهندهٔ partial را روی خط هدف تنظیم نکنید، آن تطبیق از کد JIT استفاده نخواهد کرد زیرا کدی برای تطبیق غیرجزئی کامپایل نشده است.

اگر کامپایل JIT موفقیت‌آمیز باشد، کد JIT کامپایل‌شده به طور خودکار هنگام اجرای نوع مناسبی از تطبیق استفاده خواهد شد، مگر زمانی که گزینه‌های ناسازگار زمان اجرا مشخص شده باشند. برای جزئیات بیشتر به مستندات pcre2jit مراجعه کنید. همچنین تغییردهندهٔ jitstack در زیر را برای روش تنظیم اندازهٔ پشتهٔ JIT ببینید.

اگر تغییردهندهٔ jitfast مشخص شده باشد، تطبیق با استفاده از رابط «مسیر سریع» JIT یعنی pcre2_jit_match() انجام می‌شود، که از برخی بررسی‌های صحت که توسط pcre2_match() انجام می‌شود صرف‌نظر می‌کند و البته در صورتی که JIT پشتیبانی نشود کار نخواهد کرد. اگر jitfast بدون jit مشخص شود، jit=7 فرض می‌شود.

اگر تغییردهندهٔ jitverify مشخص شده باشد، اطلاعات مربوط به الگوی کامپایل‌شده نشان می‌دهد که آیا کامپایل JIT موفق بوده است یا خیر. اگر jitverify بدون jit مشخص شود، jit=7 فرض می‌شود. در صورتی که کامپایل JIT موفق باشد و jitverify تنظیم شده باشد، در صورتی که کد کامپایل‌شده با JIT واقعاً در تطبیق استفاده شده باشد، متن "(JIT)" به اولین خط خروجی پس از تطبیق یا عدم تطبیق اضافه می‌شود.

تنظیم یک لوکال (Locale)

تغییردهندهٔ locale باید نام یک لوکال را مشخص کند، برای مثال:

/pattern/locale=fr_FR

لوکال داده‌شده تنظیم می‌شود، تابع pcre2_maketables() برای ساخت مجموعه‌ای از جداول نویسه برای آن لوکال فراخوانی می‌شود، و سپس هنگام کامپایل عبارت باقاعده به pcre2_compile() ارسال می‌گردد. همین جداول هنگام تطبیق خطوط هدف بعدی استفاده می‌شوند. تغییردهندهٔ locale فقط برای الگویی که روی آن قرار دارد اعمال می‌شود، اما اگر پیش‌فرضی نیاز باشد می‌توان آن را در دستور #pattern ارائه داد. تنظیم لوکال و جداول نویسهٔ جایگزین مانعة‌الجمع هستند.

نمایش حافظهٔ الگو

تغییردهندهٔ memory باعث می‌شود اندازه (به بایت) حافظهٔ استفاده‌شده برای نگهداری الگوی کامپایل‌شده در خروجی چاپ شود. این اندازه شامل حجم بلوک pcre2_code نمی‌شود؛ بلکه صرفاً داده‌های کامپایل‌شدهٔ واقعی است. اگر الگو متعاقباً به کامپایلر JIT ارسال شود، اندازهٔ کد کامپایل‌شدهٔ JIT نیز در خروجی نمایش داده می‌شود. در اینجا یک مثال آورده شده است:

re> /a(b)c/jit,memory
Memory allocation (code space): 21
Memory allocation (JIT code): 1910

محدود کردن پرانتزهای تو در تو

تغییردهندهٔ parens_nest_limit محدودیتی برای عمق پرانتزهای تو در تو در یک الگو تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض کتابخانه هنگام ساخت PCRE2 تنظیم می‌شود، اما pcre2test پیش‌فرض خود را روی ۲۲۰ قرار می‌دهد که برای اجرای مجموعه آزمون‌های استاندارد لازم است.

محدود کردن طول الگو

تغییردهندهٔ max_pattern_length محدودیتی (بر حسب واحدهای کد) برای طول الگویی که pcre2_compile() می‌پذیرد تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض بزرگترین عددی است که یک متغیر PCRE2_SIZE می‌تواند نگه دارد (اساساً نامحدود).

محدود کردن اندازهٔ الگوی کامپایل‌شده

تغییردهندهٔ max_pattern_compiled_length محدودیتی (به بایت) برای میزان حافظهٔ استفاده‌شده توسط یک الگوی کامپایل‌شده تعیین می‌کند. فراتر رفتن از این حد باعث خطای کامپایل می‌شود. مقدار پیش‌فرض بزرگترین عددی است که یک متغیر PCRE2_SIZE می‌تواند نگه دارد (اساساً نامحدود).

استفاده از رابط برنامه‌نویسی بسته‌بند POSIX

تغییردهنده‌های posix و posix_nosub باعث می‌شوند pcre2test کتابخانهٔ PCRE2 را از طریق رابط برنامه‌نویسی بسته‌بند POSIX فراخوانی کند به جای رابط بومی آن. هنگامی که posix_nosub استفاده می‌شود، گزینهٔ REG_NOSUB مربوط به POSIX به regcomp() ارسال می‌گردد. بسته‌بند POSIX فقط از کتابخانهٔ ۸ بیتی پشتیبانی می‌کند. توجه داشته باشید که این به معنای معناشناسی تطبیق POSIX نیست؛ برای جزئیات بیشتر به مستندات pcre2posix مراجعه کنید. تغییردهنده‌های الگوی زیر گزینه‌هایی را برای تابع regcomp() تنظیم می‌کنند:

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 )

تغییردهندهٔ regerror_buffsize اندازه‌ای را برای بافر خطا مشخص می‌کند که در صورت بروز خطای کامپایل به regerror() ارسال می‌شود. برای مثال:

/abc/posix,regerror_buffsize=20

این امکانی برای آزمایش رفتار regerror() هنگامی که بافر برای پیام خطا خیلی کوچک است فراهم می‌کند. اگر این تغییردهنده تنظیم نشده باشد، از یک بافر بزرگ استفاده می‌شود.

تغییردهنده‌های هدف aftertext و allaftertext همان‌طور که در زیر شرح داده شده کار می‌کنند. تمام تغییردهنده‌های دیگر یا نادیده گرفته می‌شوند (همراه با پیام هشدار) یا باعث ایجاد خطا می‌شوند.

الگو به صورت پیش‌فرض به عنوان یک رشتهٔ خاتمه‌یافته با صفر به regcomp() ارسال می‌شود، اما اگر تغییردهنده‌های use_length یا hex تنظیم شده باشند، از افزونهٔ REG_PEND برای ارسال آن با طول استفاده می‌شود.

آزمایش ویژگی محافظ پشته (Testing the stack guard feature)

تغییردهنده stackguard برای آزمودن استفاده از pcre2_set_compile_recursion_guard() به کار می‌رود؛ تابعی که برای امکان بررسی در دسترس بودن پشته در حین کامپایل ارائه شده است (برای جزئیات به مستندات pcre2api مراجعه کنید). اگر عدد مشخص‌شده توسط این تغییردهنده بزرگ‌تر از صفر باشد، pcre2_set_compile_recursion_guard() فراخوانی می‌شود تا یک فراخوانی بازگشتی (callback) از pcre2_compile() به یک تابع محلی برقرار کند. آرگومانی که این تابع دریافت می‌کند، عمق فعلی پرانتزهای تودرتو است؛ اگر این مقدار از مقدار تعیین‌شده توسط تغییردهنده بزرگ‌تر باشد، مقداری غیرصفر برگردانده می‌شود که باعث لغو و توقف کامپایل می‌گردد.

استفاده از جدول‌های کاراکتری جایگزین (Using alternative character tables)

مقدار مشخص‌شده برای تغییردهنده tables باید یکی از ارقام 0، 1، 2 یا 3 باشد. این مقدار باعث می‌شود مجموعه خاصی از جدول‌های کاراکتری توکار به pcre2_compile() ارسال شود. این ویژگی در آزمون‌های PCRE2 برای بررسی رفتار با جدول‌های کاراکتری مختلف به کار می‌رود. این رقم جدول‌ها را به شرح زیر مشخص می‌کند:

0 عدم ارسال هرگونه جدول کاراکتری خاص
1 جدول‌های پیش‌فرض ASCII، به شکلی که در
pcre2_chartables.c.dist توزیع شده است
2 مجموعه‌ای از جدول‌ها برای تعریف کاراکترهای ISO 8859
3 مجموعه‌ای از جدول‌ها که توسط دستور #loadtables بارگذاری شده‌اند

در جدول‌های 2، برخی کاراکترها با کدهای بزرگ‌تر از 128 به عنوان حروف، ارقام، فاصله‌ها و غیره شناسایی می‌شوند. جدول‌های 3 تنها پس از آن قابل استفاده هستند که دستور #loadtables آن‌ها را از یک فایل باینری بارگذاری کرده باشد. تنظیم جدول‌های کاراکتری جایگزین و لوکال (locale) مانعه‌الجمع (متضاد) هستند.

تنظیم برخی کنترل‌های تطبیق (Setting certain match controls)

تغییردهنده‌های زیر در واقع تغییردهنده‌های سوژه هستند و در بخش «تغییردهنده‌های سوژه» در ادامه شرح داده شده‌اند. با این حال، می‌توان آن‌ها را در فهرست تغییردهنده‌های الگو گنجاند؛ در این صورت بر هر خط سوژه‌ای که با آن الگو پردازش می‌شود اعمال می‌گردند. این تغییردهنده‌ها بر فرآیند کامپایل تأثیری نمی‌گذارند.

aftertext نمایش متن پس از تطبیق
allaftertext نمایش متن پس از گروه‌های ضبط‌شده
allcaptures نمایش تمام موارد ضبط‌شده
allvector نمایش کامل ovector
allusedtext نمایش تمام متن‌های بررسی‌شده
altglobal تطبیق سراسری جایگزین
/g global تطبیق سراسری
heapframes_size نمایش اندازه heapframes داده‌های تطبیق
jitstack=<n> تنظیم اندازه پشته JIT
mark نمایش مقادیر mark
null_substitute_match_data جایگزینی با داده‌های تطبیق NULL
replace=<str> مشخص کردن یک رشته جایگزین
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=<n> رد کردن جایگزینی <n>
substitute_stop=<n> رد کردن جایگزینی <n> و موارد پس از آن
substitute_unknown_unset استفاده از PCRE2_SUBSTITUTE_UNKNOWN_UNSET
substitute_unset_empty استفاده از PCRE2_SUBSTITUTE_UNSET_EMPTY

این تغییردهنده‌ها نباید در یک دستور #pattern ظاهر شوند. اگر می‌خواهید آن‌ها را به عنوان پیش‌فرض قرار دهید، در یک دستور #subject تنظیمشان کنید.

مشخص کردن خطوط سوژه لفظی (Specifying literal subject lines)

اگر تغییردهنده subject_literal روی یک الگو وجود داشته باشد، تمام خطوط سوژه‌ای که با آن تطبیق داده می‌شوند به عنوان رشته‌های لفظی (literal) و بدون تفسیر بک‌اسلش‌ها در نظر گرفته می‌شوند. تنظیم تغییردهنده‌های سوژه روی چنین خطوطی امکان‌پذیر نیست، اما هر تغییری که به عنوان پیش‌فرض توسط دستور #subject تنظیم شده باشد، شناسایی می‌شود.

ذخیره الگوی کامپایل‌شده (Saving a compiled pattern)

هنگامی که الگویی با تغییردهنده push با موفقیت کامپایل می‌شود، به داخل پشته الگوهای کامپایل‌شده فرستاده می‌شود (push) و pcre2test انتظار دارد که خط بعدی به جای یک خط سوژه، حاوی یک الگوی جدید (یا یک دستور) باشد. این امکان هنگام ذخیره الگوهای کامپایل‌شده در یک فایل استفاده می‌شود، همان‌طور که در بخش تحت عنوان «ذخیره و بازیابی الگوهای کامپایل‌شده» در ادامه شرح داده شده است. اگر به جای push از pushcopy استفاده شود، یک کپی از الگوی کامپایل‌شده در پشته قرار می‌گیرد و نسخه اصلی به عنوان الگوی جاری باقی می‌ماند تا آماده تطبیق با خطوط ورودی بعدی باشد. این قابلیت روشی را برای آزمایش تابع pcre2_code_copy() فراهم می‌کند. تغییردهنده‌های push و pushcopy با تغییردهنده‌های کامپایلی مانند global که در زمان تطبیق عمل می‌کنند، ناسازگار هستند. هر موردی که مشخص شود (برای نسخه درون پشته) نادیده گرفته شده و یک پیام هشدار صادر می‌شود، به جز replace که موجب بروز خطا می‌گردد. توجه داشته باشید که jitverify با اینکه مجاز است، به هیچ تطبیق بعدی که از یک الگوی ذخیره‌شده در پشته استفاده می‌کند منتقل نمی‌شود.

آزمایش تبدیل الگوهای خارجی (Testing foreign pattern conversion)

توابع آزمایشی تبدیل الگوهای خارجی در PCRE2 را می‌توان با تنظیم تغییردهنده convert آزمایش کرد. آرگومان آن فهرستی از گزینه‌ها است که با دو‌نقطه از هم جدا شده‌اند و گزینه معادل را برای تابع pcre2_pattern_convert() تنظیم می‌کنند:

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)

مقدار "unset" برای غیرفعال کردن حالت پیش‌فرضی که توسط یک دستور #pattern تنظیم شده مفید است. هنگامی که یکی از این گزینه‌ها تنظیم شود، الگوی ورودی به pcre2_pattern_convert() ارسال می‌گردد. اگر تبدیل موفقیت‌آمیز باشد، نتیجه در خروجی منعکس شده و سپس به pcre2_compile() ارسال می‌شود. گزینه‌های معمول utf و no_utf_check در صورت تنظیم، باعث می‌شوند گزینه‌های PCRE2_CONVERT_UTF و PCRE2_CONVERT_NO_UTF_CHECK به pcre2_pattern_convert() ارسال گردند.

به طور پیش‌فرض، تابع تبدیل مجاز است برای خروجی خود یک بافر تخصیص دهد. با این حال، اگر تغییردهنده convert_length به مقداری بزرگ‌تر از صفر تنظیم شود، pcre2test بافری با طول داده‌شده را ارسال می‌کند. این امر آزمودن بررسی طول را امکان‌پذیر می‌سازد.

تغییردهنده‌های convert_glob_escape و convert_glob_separator می‌توانند برای تعیین کاراکترهای اسکیپ و جداکننده در پردازش glob استفاده شوند، و پیش‌فرض‌هایی را که به سیستم‌عامل وابسته‌اند بازنویسی و لغو نمایند.

تنظیم گزینه‌های تطبیق (Setting match options)

تغییردهنده‌های زیر گزینه‌هایی را برای pcre2_match() یا pcre2_dfa_match() تنظیم می‌کنند. برای شرح اثرات آن‌ها به pcre2api مراجعه نمایید.

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

تغییردهنده‌های تطبیق جزئی همراه با اختصار ارائه شده‌اند زیرا به وفور در آزمون‌ها ظاهر می‌شوند.

اگر تغییردهنده posix یا posix_nosub روی الگو وجود داشته باشد، که موجب استفاده از رابط کاربری POSIX wrapper می‌شود، تنها تغییردهنده‌های تنظیم گزینه که مؤثر خواهند بود notbol، notempty و noteol هستند که به ترتیب موجب ارسال REG_NOTBOL، REG_NOTEMPTY و REG_NOTEOL به regexec() می‌شوند. سایر تغییردهنده‌ها همراه با یک پیام هشدار نادیده گرفته می‌شوند.

یک تغییردهنده اضافی دیگر وجود دارد که می‌تواند با POSIX wrapper استفاده شود. اگر برای تطبیق غیر POSIX استفاده شود، نادیده گرفته می‌شود (همراه با هشدار).

posix_startend=<n>[:<m>]

این گزینه موجب می‌شود رشته سوژه با استفاده از گزینه REG_STARTEND به regexec() ارسال شود، که از آفست‌ها برای تعیین این‌که کدام بخش از رشته مورد جستجو قرار گیرد استفاده می‌کند. اگر تنها یک عدد مشخص شود، آفست پایانی به عنوان انتهای رشته سوژه در نظر گرفته می‌شود. برای جزئیات بیشتر در مورد REG_STARTEND، به مستندات pcre2posix مراجعه کنید. اگر رشته سوژه حاوی صفرهای باینری باشد (کدگذاری‌شده به صورت کاراکترهای گریز مانند \x{00} زیرا pcre2test از صفرهای باینری واقعی در ورودی خود پشتیبانی نمی‌کند)، باید از posix_startend برای تعیین طول آن استفاده کنید.

تنظیم کنترل‌های تطبیق (Setting match controls)

تغییردهنده‌های زیر بر فرآیند تطبیق تأثیر می‌گذارند یا اطلاعات بیشتری را درخواست می‌نمایند. برخی از آن‌ها را می‌توان در خط الگو نیز مشخص کرد (به بالا مراجعه کنید)، که در این صورت بر هر خط سوژه‌ای که با آن الگو تطبیق داده می‌شود اعمال می‌شوند، اما می‌توان آن‌ها را با تغییردهنده‌های روی سوژه بازنویسی کرد.

aftertext نمایش متن پس از تطبیق
allaftertext نمایش متن پس از گروه‌های ضبط‌شده
allcaptures نمایش تمام موارد ضبط‌شده
allusedtext نمایش تمام متن‌های بررسی‌شده (فقط non-JIT)
allvector نمایش کامل ovector
altglobal تطبیق سراسری جایگزین
callout_capture نمایش موارد ضبط‌شده در زمان فراخوان
callout_data=<n> تنظیم مقداری برای ارسال از طریق فراخوان‌ها
callout_error=<n>[:<m>] کنترل خطای فراخوان
callout_extra نمایش اطلاعات اضافی فراخوان
callout_fail=<n>[:<m>] کنترل شکست فراخوان
callout_no_where عدم نمایش موقعیت یک فراخوان
callout_none عدم ارائه تابع فراخوان
copy=<number or name> کپی زیررشته ضبط‌شده
depth_limit=<n> تنظیم محدودیت عمق
dfa استفاده از pcre2_dfa_match()
find_limits یافتن محدودیت‌های هیپ (heap)، تطبیق و عمق
find_limits_noheap یافتن محدودیت‌های تطبیق و عمق
get=<number or name> استخراج زیررشته ضبط‌شده
getall استخراج تمام زیررشته‌های ضبط‌شده
/g global تطبیق سراسری
heapframes_size نمایش اندازه heapframes داده‌های تطبیق
heap_limit=<n> تنظیم محدودیت حافظه هیپ (کیلوبایت)
jitstack=<n> تنظیم اندازه پشته JIT
mark نمایش مقادیر mark
match_limit=<n> تنظیم محدودیت تطبیق
memory نمایش میزان مصرف حافظه هیپ
null_context تطبیق با یک بافت (context) از نوع NULL
null_replacement جایگزینی با مقدار جایگزین NULL
null_subject تطبیق با سوژه NULL
null_substitute_match_data جایگزینی با داده‌های تطبیق NULL
offset=<n> تنظیم آفست شروع
offset_limit=<n> تنظیم محدودیت آفست
ovector=<n> تنظیم اندازه بردار خروجی (output vector)
recursion_limit=<n> مترادف منسوخ‌شده برای depth_limit
replace=<str> مشخص کردن یک رشته جایگزین
startchar نمایش startchar در صورت مرتبط بودن
startoffset=<n> مشابه offset=<n>
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> رد کردن جایگزینی شماره n
substitute_stop=<n> رد کردن جایگزینی شماره n و بالاتر
substitute_subject=<str> مشخص کردن سوژه‌ای متفاوت برای جایگزینی
substitute_unknown_unset استفاده از PCRE2_SUBSTITUTE_UNKNOWN_UNSET
substitute_unset_empty استفاده از PCRE2_SUBSTITUTE_UNSET_EMPTY
zero_terminate ارسال سوژه به صورت خاتمه‌یافته با صفر (zero-terminated)

اثرات این تغییردهنده‌ها در بخش‌های بعدی شرح داده شده است. هنگام تطبیق از طریق رابط کاربری POSIX wrapper، تغییردهنده‌های سوژه aftertext، allaftertext و ovector طبق توضیحات زیر عمل می‌کنند. تمام تغییردهنده‌های دیگر یا نادیده گرفته می‌شوند (همراه با هشدار) و یا موجب بروز خطا می‌گردند.

نمایش متن بیشتر (Showing more text)

تغییردهنده aftertext درخواست می‌کند که علاوه بر چاپ بخشی از رشته سوژه که با کل الگو تطبیق یافته است، pcre2test باقی‌مانده رشته سوژه را نیز در خروجی نمایش دهد. این قابلیت برای آزمون‌هایی کاربرد دارد که در آن‌ها سوژه شامل چند کپی از یک زیررشته مشابه است. تغییردهنده allaftertext همین عمل را برای زیررشته‌های ضبط‌شده علاوه بر زیررشته تطبیق‌یافته اصلی درخواست می‌کند. در هر حالت، باقی‌مانده در خط بعدی همراه با یک کاراکتر مثبت (+) بعد از شماره ضبط چاپ می‌شود.

تغییردهنده allusedtext درخواست می‌کند تمام متنی که در حین یک تطبیق موفق الگو توسط مفسر بررسی شده است، هم برای تطبیق کامل و هم جزئی نمایش داده شود. این ویژگی برای تطبیق JIT پشتیبانی نمی‌شود و اگر همراه با JIT درخواست شود نادیده گرفته خواهد شد (همراه با پیام هشدار). تنظیم این تغییردهنده در صورتی بر خروجی تأثیر می‌گذارد که یک lookbehind در ابتدای تطبیق، یا برای یک تطبیق کامل، یک lookahead در انتها وجود داشته باشد، یا اینکه از \K در الگو استفاده شده باشد. کاراکترهایی که قبل یا بعد از شروع و پایان تطبیق واقعی قرار دارند در خروجی با کاراکترهای '<' یا '>' در زیر آن‌ها نشان داده می‌شوند. در اینجا یک مثال آورده شده است:

re> /(?<=pqr)abc(?=xyz)/
data> 123pqrabcxyz456\=allusedtext
0: pqrabcxyz
<<< >>>
data> 123pqrabcxy\=ph,allusedtext
Partial match: pqrabcxy
<<<

اولین تطبیق (تطبیق کامل) نشان می‌دهد که رشته تطبیق‌یافته "abc" است، و رشته‌های قبلی و بعدی "pqr" و "xyz" در حین تطبیق (هنگام پردازش assertionها) بررسی شده‌اند. تطبیق جزئی تنها می‌تواند رشته قبلی را نشان دهد.

تغییردهنده startchar درخواست می‌کند که کاراکتر شروع تطبیق نشان داده شود، در صورتی که با ابتدای رشته تطبیق‌یافته متفاوت باشد. تنها زمانی که این اتفاق می‌افتد وقتی است که \K به عنوان بخشی از تطبیق پردازش شده باشد. در این حالت، خروجی رشته تطبیق‌یافته به جای نقطه تطبیق از کاراکتر شروع نمایش داده می‌شود، و علامت‌های هشتک (^) در زیر کاراکترهای قبلی قرار می‌گیرند. به عنوان مثال:

re> /abc\Kxyz/
data> abcxyz\=startchar
0: abcxyz
^^^

برخلاف allusedtext، تغییردهنده startchar می‌تواند همراه با JIT استفاده شود. با این حال، این دو تغییردهنده مانعه‌الجمع هستند.

نمایش مقدار تمام گروه‌های ضبط‌شده (Showing the value of all capture groups)

تغییردهنده allcaptures درخواست می‌کند که مقادیر تمام پرانتزهای ضبط‌شده بالقوه پس از تطبیق در خروجی چاپ شوند. به طور پیش‌فرض، تنها گروه‌هایی تا بالاترین گروهی که واقعاً در تطبیق استفاده شده است در خروجی نمایش می‌یابند (مطابق با کد بازگشتی از pcre2_match()). گروه‌هایی که در تطبیق نقشی نداشته‌اند به صورت "<unset>" نمایش داده می‌شوند. این تغییردهنده برای تطبیق DFA (که هیچ ضبطی انجام نمی‌دهد) مرتبط نیست و زمانی که replace مشخص شده باشد اعمال نمی‌شود؛ در صورت وجود، همراه با یک پیام هشدار نادیده گرفته خواهد شد.

نمایش کامل ovector، برای تمام نتایج (Showing the entire ovector, for all outcomes)

تغییردهنده allvector درخواست می‌کند که تمام ovector بدون توجه به نتیجه تطبیق نمایش داده شود. این را با allcaptures مقایسه کنید که فقط تا حداکثر تعداد گروه‌های ضبط الگو و آن هم تنها برای یک تطبیق کامل و موفق غیر DFA خروجی می‌دهد. این تغییردهنده که پس از هر نتیجه تطبیق و همچنین برای تطبیق DFA عمل می‌کند، روشی را برای بررسی عدم وجود تغییرات غیرمنتظره در فیلدهای ovector فراهم می‌سازد. قبل از هر تلاش برای تطبیق، ovector با یک مقدار خاص پر می‌شود، و اگر این مقدار در هر دو عنصر یک جفت ضبط‌کننده یافت شود، عبارت "<unchanged>" چاپ می‌گردد. پس از یک تطبیق موفق، این امر برای تمام گروه‌های بعد از حداکثر گروه ضبط الگو اعمال می‌شود. در سایر موارد، برای کل ovector اعمال می‌گردد. پس از یک تطبیق جزئی، دو عنصر اول تنها مواردی هستند که باید مقداردهی شوند. پس از یک تطبیق DFA، میزان استفاده از ovector به تعداد تطبیق‌های یافت‌شده بستگی دارد.

آزمایش فراخوان‌های الگو (Testing pattern callouts)

هنگامی که pcre2test توابع تطبیق کتابخانه را فراخوانی می‌کند یک تابع فراخوان (callout) ارائه می‌شود، مگر اینکه callout_none مشخص شده باشد. رفتار آن را می‌توان توسط تغییردهنده‌های مختلفی که در بالا فهرست شده و نام آن‌ها با callout_ شروع می‌شود کنترل کرد. جزئیات در بخش تحت عنوان «فراخوان‌ها» (Callouts) در ادامه ارائه شده است. آزمودن فراخوان‌ها از pcre2_substitute() به طور جداگانه در بخش «آزمایش تابع جایگزینی» در ادامه شرح داده شده است.

یافتن تمام تطابق‌ها در یک رشته

جستجو برای تمام تطابق‌های ممکن در یک رشته هدف (subject) را می‌توان با اصلاح‌کننده global یا altglobal درخواست کرد. پس از یافتن یک تطابق، تابع تطابق دوباره فراخوانی می‌شود تا باقی‌مانده رشته هدف را جستجو کند. تفاوت بین global و altglobal در این است که اولی از آرگومان start_offset در pcre2_match() یا pcre2_dfa_match() برای شروع جستجو در نقطه‌ای جدید در کل رشته استفاده می‌کند (همان کاری که Perl انجام می‌دهد)، در حالی که دومی یک رشته هدف کوتاه‌شده را ارسال می‌کند. این امر در صورتی که الگو با یک ادعای پس‌نگاه (شامل \b یا \B) شروع شود، در فرآیند تطابق تفاوت ایجاد می‌کند.

اگر یک رشته خالی مطابقت داده شود، تطابق بعدی با تنظیم فلگ PCRE2_NOTEMPTY_ATSTART انجام می‌شود تا برای تطابق دیگری که غیرخالی باشد در همان نقطه از رشته هدف جستجو شود. این رفتار نحوه مدیریت چنین مواردی توسط Perl را هنگام استفاده از اصلاح‌کننده /g یا تابع split() تقلید می‌کند.

آزمودن توابع استخراج زیررشته

اصلاح‌کننده‌های copy و get را می‌توان برای آزمودن توابع pcre2_substring_copy_xxx() و pcre2_substring_get_xxx() استفاده کرد. آن‌ها می‌توانند بیش از یک بار مشخص شوند و هر کدام می‌توانند نام یا شماره یک گروه ضبط (capture group) را مشخص کنند، برای نمونه:

abcd\=copy=1,copy=3,get=G1

اگر از دستور #subject برای تنظیم فهرست‌های پیش‌فرض copy و/یا get استفاده شود، می‌توان آن‌ها را با تعیین یک عدد منفی برای لغو تمام گروه‌های شماره‌دار و یک نام خالی برای لغو تمام گروه‌های نام‌گذاری‌شده، بازنشانی (unset) کرد.

اصلاح‌کننده getall تابع pcre2_substring_list_get() را آزمایش می‌کند که تمام زیررشته‌های ضبط‌شده را استخراج می‌کند.

اگر خط رشته هدف با موفقیت تطابق یابد، زیررشته‌های استخراج‌شده توسط توابع کمکی با C، G، یا L پس از شماره رشته به جای دو نقطه خروجی داده می‌شوند. این علاوه بر فهرست کامل معمولی است. طول رشته (یعنی مقدار بازگشتی از تابع استخراج) در پرانتز پس از هر زیررشته آورده می‌شود و در صورتی که استخراج بر اساس نام بوده باشد، نام آن نیز در ادامه می‌آید.

آزمودن تابع جایگزینی (substitution)

اگر اصلاح‌کننده replace تنظیم شود، تابع pcre2_substitute() به جای یکی از توابع تطابق (یا پس از یک بار فراخوانی pcre2_match() در مورد PCRE2_SUBSTITUTE_MATCHED) فراخوانی می‌شود. توجه داشته باشید که رشته‌های جایگزین نمی‌توانند حاوی کاما باشند، زیرا کاما نشان‌دهنده پایان یک اصلاح‌کننده است. گمان نمی‌رود این موضوع در یک برنامه آزمایشی مشکلی ایجاد کند.

مشخص کردن یک رشته جایگزین کاملاً خالی این اصلاح‌کننده را غیرفعال می‌کند. با این حال، همان‌طور که در زیر شرح داده شده است، می‌توان با ارائه طول بافر برای یک جایگزینی که در غیر این صورت خالی است، یک جایگزینی خالی تعیین کرد.

برخلاف رشته‌های هدف، pcre2test رشته‌های جایگزین را برای توالی‌های گریز (escape sequences) پردازش نمی‌کند. در حالت UTF، بررسی می‌شود که آیا رشته جایگزین یک رشته معتبر UTF-8 است یا خیر. اگر چنین باشد، به درستی به یک رشته UTF با عرض واحد کد (code unit width) مناسب تبدیل می‌شود. اگر یک رشته UTF-8 معتبر نباشد، واحدهای کد به صورت مستقیم کپی می‌شوند. این روش راهکاری برای ارسال یک رشته نامعتبر UTF-8 برای اهداف آزمایشی فراهم می‌کند.

اصلاح‌کننده‌های زیر گزینه‌هایی را (علاوه بر گزینه‌های تطابق عادی) برای pcre2_substitute() تنظیم می‌کنند:

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

برای جزئیات این گزینه‌ها، مستندات pcre2api را ببینید.

پس از یک جایگزینی موفق، رشته تغییریافته که تعداد جایگزینی‌ها قبل از آن آمده است خروجی داده می‌شود. اگر تطابقی وجود نداشته باشد، این مقدار ممکن است صفر باشد. در اینجا نمونه‌ای ساده از یک آزمایش جایگزینی آمده است:

/abc/replace=xxx
=abc=abc=
1: =xxx=abc=
=abc=abc=\=global
2: =xxx=xxx=

رشته‌های هدف و جایگزین برای آزمایش‌های جایگزینی باید نسبتاً کوتاه نگه داشته شوند (کمتر از ۲۵۶ کاراکتر)، زیرا از بافرهای با اندازه ثابت استفاده می‌شود. برای تسهیل آزمایش سرریز بافر، اگر رشته جایگزین با یک عدد درون قلاب‌ها شروع شود، آن عدد به عنوان اندازه بافر خروجی به pcre2_substitute() ارسال می‌شود و رشته جایگزین از کاراکتر بعدی شروع می‌شود. در اینجا مثالی آمده است که این حالت حدی را آزمایش می‌کند:

/abc/
123abc123\=replace=[10]XYZ
1: 123XYZ123
123abc123\=replace=[9]XYZ
Failed: error -48: no more memory

رفتار پیش‌فرض pcre2_substitute() هنگامی که بافر خروجی بیش از حد کوچک است، بازگرداندن PCRE2_ERROR_NOMEMORY است. با این حال، اگر گزینه PCRE2_SUBSTITUTE_OVERFLOW_LENGTH (با استفاده از اصلاح‌کننده substitute_overflow_length) تنظیم شده باشد، pcre2_substitute() مراحل تطابق و جایگزینی را ادامه می‌دهد (اما هیچ کال‌اوتی انجام نمی‌دهد) تا اندازه بافر مورد نیاز را محاسبه کند. هنگامی که این اتفاق می‌افتد، pcre2test طول بافر مورد نیاز را (شامل فضا برای صفر انتهایی) به عنوان بخشی از پیام خطا نشان می‌دهد. برای نمونه:

/abc/substitute_overflow_length
123abc123\=replace=[9]XYZ
Failed: error -48: no more memory: 10 code units are needed

رشته جایگزین در تطابق POSIX و DFA نادیده گرفته می‌شود. تعیین تطابق جزئی باعث ایجاد یک خطای بازگشتی ("bad option value") از طرف pcre2_substitute() می‌شود.

اصلاح‌کننده substitute_subject ممکن است برای آزمودن استفاده از PCRE2 API به کار رود؛ حالتی که در آن کلاینت pcre2_match() و به دنبال آن pcre2_substitute() را با PCRE2_SUBSTITUTE_MATCHED فراخوانی می‌کند، اما در فاصله میان تطابق و جایگزینی، تغییری غیرمنتظره و پشتیبانی‌نشده را به صورت درجا روی بافر رشته هدف انجام می‌دهد.

آزمودن کال‌اوت‌های جایگزینی

اگر اصلاح‌کننده substitute_callout تنظیم شود، یک تابع کال‌اوت جایگزینی راه‌اندازی می‌شود. اصلاح‌کننده null_context نباید تنظیم شده باشد، زیرا آدرس تابع کال‌اوت در یک زمینه تطابق (match context) ارسال می‌شود. هنگامی که تابع کال‌اوت فراخوانی می‌شود (پس از هر جایگزینی)، جزئیات رشته‌های ورودی و خروجی چاپ می‌شوند. برای نمونه:

/abc/g,replace=<$0>,substitute_callout
abcdefabcpqr
1(1) Old 0 3 "abc" New 0 5 "<abc>"
2(1) Old 6 9 "abc" New 8 13 "<abc>"
2: <abc>def<abc>pqr

نخستین عدد در هر خط کال‌اوت، تعداد تطابق‌ها است. عدد داخل پرانتز تعداد جفت‌هایی است که در ovector تنظیم شده‌اند (یعنی یک عدد بیشتر از تعداد گروه‌های ضبط‌کننده‌ای که تنظیم شده بودند). سپس آفست‌های زیررشته قدیمی، محتویات آن و همین موارد برای جایگزین فهرست می‌شوند.

به‌طور پیش‌فرض، تابع کال‌اوت جایگزینی مقدار صفر را برمی‌گرداند که جایگزینی را می‌پذیرد و در صورت استفاده از /g باعث ادامه تطابق می‌شود. از دو اصلاح‌کننده دیگر می‌توان برای آزمودن مقادیر بازگشتی دیگر استفاده کرد. اگر substitute_skip روی مقداری بزرگتر از صفر تنظیم شود، تابع کال‌اوت برای تطابق آن شماره مقدار +1 را برمی‌گرداند و به طور مشابه substitute_stop مقدار -1 را برمی‌گرداند. این موارد باعث رد شدن جایگزینی می‌شوند و -1 باعث می‌شود که هیچ تطابق دیگری انجام نشود. در صورت تنظیم هر یک از آن‌ها، substitute_callout فرض می‌شود. برای نمونه:

/abc/g,replace=<$0>,substitute_skip=1
abcdefabcpqr
1(1) Old 0 3 "abc" New 0 5 "<abc> SKIPPED"
2(1) Old 6 9 "abc" New 6 11 "<abc>"
2: abcdef<abc>pqr
abcdefabcpqr\=substitute_stop=1
1(1) Old 0 3 "abc" New 0 5 "<abc> STOPPED"
1: abcdefabcpqr

اگر هر دو برای یک شماره تنظیم شوند، stop تقدم دارد. تنها یک skip یا stop تکی پشتیبانی می‌شود که برای آزمودن عملکرد این قابلیت کافی است.

آزمودن کال‌اوت‌های تغییر حالت حروف جایگزین

اگر اصلاح‌کننده substitute_case_callout تنظیم شود، یک تابع کال‌اوت تغییر حالت حروف (case) جایگزینی راه‌اندازی می‌شود. این تابع کال‌اوت برای هر بخش جایگزین‌شده‌ای که قرار است تغییر حالت حروف روی آن انجام شود فراخوانی می‌گردد.

تابع کال‌اوت ارائه‌شده یک تابع ثابت با پیاده‌سازی برای رفتارهای مشخصی است: ورودی‌هایی که هنگام تبدیل حالت حروف کوچک‌تر می‌شوند؛ ورودی‌هایی که بزرگ‌تر می‌شوند؛ و ورودی‌هایی با حالت‌های متمایز حروف بزرگ/کوچک/عنوان (upper/lower/titlecase). کاراکترهایی که برای اهداف آزمایشی مشمول حالت خاصی نشده‌اند، دست‌نخورده باقی می‌مانند، گویی کاراکترهای فاقد حالت حروف (caseless) هستند.

تنظیم اندازه پشته JIT

اصلاح‌کننده jitstack روشی برای تنظیم حداکثر اندازه پشته که توسط کد بهینه‌سازی درجا (just-in-time) استفاده می‌شود ارائه می‌دهد. در صورتی که از بهینه‌سازی JIT استفاده نشود، این مورد نادیده گرفته می‌شود. مقدار آن به صورت کیبی‌بایت (واحدهای ۱۰۲۴ بایتی) است. تنظیم آن روی صفر به مقدار پیش‌فرض 32KiB بازمی‌گردد. ارائه پشته‌ای بزرگتر از مقدار پیش‌فرض تنها برای الگوهای بسیار پیچیده ضروری است. اگر jitstack در یک خط رشته هدف روی مقداری غیرصفر تنظیم شود، هر مقداری را که روی الگو تنظیم شده بود بازنویسی (override) می‌کند.

تنظیم محدودیت‌های هیپ، تطابق و عمق

اصلاح‌کننده‌های heap_limit، match_limit و depth_limit محدودیت‌های مناسب را در زمینه تطابق (match context) تنظیم می‌کنند. این مقادیر هنگام مشخص شدن اصلاح‌کننده find_limits یا find_limits_noheap نادیده گرفته می‌شوند.

یافتن حداقل محدودیت‌ها

اگر اصلاح‌کننده find_limits در یک خط رشته هدف وجود داشته باشد، pcre2test تابع تطابق مربوطه را چندین بار فراخوانی می‌کند و مقادیر متفاوتی را در زمینه تطابق از طریق pcre2_set_heap_limit()، pcre2_set_match_limit() یا pcre2_set_depth_limit() تنظیم می‌کند تا زمانی که کوچک‌ترین مقدار برای هر پارامتر را بیابد که اجازه می‌دهد تطابق بدون خطای "limit exceeded" کامل شود. خود تطابق ممکن است موفق یا ناموفق باشد. یک اصلاح‌کننده جایگزین به نام find_limits_noheap محدودیت هیپ را حذف می‌کند. این مورد در آزمایش‌های استاندارد استفاده می‌شود، زیرا حداقل محدودیت هیپ بین سیستم‌ها متفاوت است. اگر از JIT استفاده شود، تنها محدودیت تطابق مرتبط است و دو مورد دیگر به طور خودکار حذف می‌شوند.

هنگام استفاده از این اصلاح‌کننده، الگو نباید حاوی هیچ‌گونه تنظیمات محدودیتی مانند (*LIMIT_MATCH=...) در درون خود باشد. اگر چنین تنظیمی وجود داشته باشد و کمتر از حداقل مقدار تطابق باشد، حداقل مقدار پیدا نمی‌شود زیرا pcre2_set_match_limit() و غیره تنها قادر به کاهش مقدار یک محدودیت درون الگو هستند؛ آن‌ها نمی‌توانند آن را افزایش دهند.

برای تطابق غیر DFA، حداقل عدد depth_limit معیاری است از میزان پس‌گرد (backtracking) تودرتویی که رخ می‌دهد (یعنی درخت الگو تا چه عمقی جستجو می‌شود). در مورد تطابق DFA، گزینه depth_limit عمق فراخوانی‌های بازگشتی تابع داخلی را کنترل می‌کند که برای مدیریت بازگشت الگو، ادعاهای پیرامون‌نگاه (lookaround assertions) و گروه‌های اتمی استفاده می‌شود.

برای تطابق غیر DFA، عدد match_limit معیاری برای میزان پس‌گردی است که صورت می‌گیرد و فهمیدن حداقل مقدار می‌تواند آموزنده باشد. برای اکثر تطابق‌های ساده، این عدد نسبتاً کوچک است، اما برای الگوهایی با تعداد بسیار زیاد احتمالات تطابق، با افزایش طول رشته هدف می‌تواند خیلی سریع بسیار بزرگ شود. در مورد تطابق DFA، گزینه match_limit تعداد کل فراخوانی‌ها (اعم از بازگشتی و غیربازگشتی) به تابع تطابق داخلی را کنترل می‌کند، و در نتیجه مقدار کلی منبع محاسباتی مورداستفاده را کنترل می‌نماید.

برای هر دو نوع تطابق، عدد heap_limit که به کیبی‌بایت (واحدهای ۱۰۲۴ بایتی) است، مقدار حافظه هیپ استفاده‌شده برای تطابق را محدود می‌کند.

نمایش نام‌های MARK

اصلاح‌کننده mark باعث می‌شود نام‌های حاصل از افعال کنترلی پس‌گرد (backtracking control verbs) که از فراخوانی‌های pcre2_match() بازگردانده می‌شوند، نمایش یابند. اگر یک mark برای یک تطابق، عدم تطابق یا تطابق جزئی بازگردانده شود، pcre2test آن را نشان می‌دهد. برای یک تطابق، در یک خط جداگانه قرار می‌گیرد و با "MK:" برچسب‌گذاری می‌شود. در غیر این صورت، به پیام عدم تطابق افزوده می‌شود.

نمایش مصرف حافظه

اصلاح‌کننده memory باعث می‌شود pcre2test اندازه تمام فراخوانی‌های تخصیص و آزادسازی حافظه هیپ را که در طول فراخوانی pcre2_match() یا pcre2_dfa_match() رخ می‌دهند، ثبت (log) کند. در حالت دوم، حافظه هیپ تنها زمانی استفاده می‌شود که یک تطابق به فضای کاری داخلی بیشتری نسبت به تخصیص پیش‌فرض روی پشته نیاز داشته باشد، بنابراین در بسیاری از موارد هیچ خروجی وجود نخواهد داشت. در طول تطابق با JIT هیچ حافظه هیپی تخصیص داده نمی‌شود. برای کارکرد این اصلاح‌کننده، اصلاح‌کننده null_context نباید روی هر دوی الگو و رشته هدف تنظیم شده باشد، هرچند می‌تواند روی یکی از آن‌ها تنظیم شود.

نمایش اندازه کلی بردار فریم‌های هیپ (heap frame)

اصلاح‌کننده heapframes_size برای تطابق‌هایی که از pcre2_match() بدون JIT استفاده می‌کنند مرتبط است. پس از اجرای یک تطابق (چه موفق و چه ناموفق)، اندازه (به بایت) بردار فریم‌های هیپ تخصیص‌یافته که به بلوک داده‌های تطابق متصل مانده است، نمایش داده می‌شود. اگر عمل تطابق شامل چندین فراخوانی برای pcre2_match() بود (برای نمونه، تطابق سراسری یا برای زمان‌سنجی)، تنها مقدار نهایی نشان داده می‌شود.

این اصلاح‌کننده برای تطابق POSIX یا DFA، همراه با یک هشدار نادیده گرفته می‌شود. تطابق JIT از بردار فریم‌های هیپ استفاده نمی‌کند، بنابراین اندازه همیشه صفر است، مگر اینکه تطابق قبلی بدون JIT وجود داشته باشد. توجه داشته باشید که تعیین اندازه صفر برای بردار خروجی (به زیر مراجعه کنید) باعث می‌شود pcre2test بلوک داده‌های تطابق خود (و بردار فریم‌های هیپ مرتبط با آن) را آزاد کند و یک بلوک جدید تخصیص دهد.

تنظیم آفست شروع

اصلاح‌کننده offset یک آفست را در رشته هدف تعیین می‌کند که تطابق از آنجا آغاز می‌شود. مقدار آن تعداد واحدهای کد است، نه کاراکترها.

تنظیم محدودیت آفست

اصلاح‌کننده offset_limit محدودیتی را برای تطابق‌های مهارنشده (unanchored) تعیین می‌کند. اگر تطابقی با شروع در این آفست یا قبل از آن در رشته هدف یافت نشود، بازگشت "no match" داده می‌شود. مقدار داده تعداد واحدهای کد است، نه کاراکترها. هنگامی که از این اصلاح‌کننده استفاده می‌شود، اصلاح‌کننده use_offset_limit باید برای الگو تنظیم شده باشد؛ در غیر این صورت، خطا ایجاد می‌شود.

تنظیم اندازه بردار خروجی

اصلاح‌کننده ovector تنها به خط رشته هدفی که در آن ظاهر می‌شود اعمال می‌گردد، هرچند طبیعتاً می‌توان از آن برای تنظیم پیش‌فرض در دستور #subject نیز استفاده کرد. این گزینه تعداد جفت‌های آفست موجود برای ذخیره اطلاعات تطابق را مشخص می‌کند. مقدار پیش‌فرض ۱۵ است.

مقدار صفر هنگام آزمودن POSIX API مفید است، زیرا باعث می‌شود regexec() با یک بردار ضبط NULL فراخوانی شود. هنگام عدم آزمودن POSIX API، از مقدار صفر استفاده می‌شود تا باعث فراخوانی pcre2_match_data_create_from_pattern() برای ایجاد یک بلوک تطابق جدید با اندازه دقیقاً مناسب برای الگو شود. (ایجاد یک بلوک تطابق با ovector با طول صفر امکان‌پذیر نیست؛ همیشه حداقل یک جفت آفست وجود دارد.) بلوک داده‌های تطابق قدیمی آزاد می‌شود.

ارسال رشته هدف به صورت خاتمه‌یافته با صفر

به‌طور پیش‌فرض، رشته هدف با طول صحیح خود به تابع تطابق API بومی ارسال می‌شود. به منظور آزمایش قابلیت ارسال رشته خاتمه‌یافته با صفر (zero-terminated)، اصلاح‌کننده zero_terminate ارائه شده است. این گزینه باعث می‌شود طول به عنوان PCRE2_ZERO_TERMINATED ارسال شود. هنگام تطابق از طریق رابط POSIX، این اصلاح‌کننده با یک هشدار نادیده گرفته می‌شود.

هنگام آزمودن pcre2_substitute()، این اصلاح‌کننده همچنین اثر ارسال رشته جایگزین به صورت خاتمه‌یافته با صفر را دارد.

ارسال زمینه، رشته هدف یا جایگزین NULL

به طور معمول، pcre2test یک بلوک زمینه را به pcre2_match()، pcre2_dfa_match()، pcre2_jit_match() یا pcre2_substitute() ارسال می‌کند. با این حال، اگر اصلاح‌کننده null_context تنظیم شده باشد، NULL ارسال می‌شود. این برای آزمودن این است که آیا توابع تطابق و جایگزینی در این حالت به درستی رفتار می‌کنند یا خیر (آن‌ها از مقادیر پیش‌فرض استفاده می‌کنند). این اصلاح‌کننده را نمی‌توان همراه با اصلاح‌کننده‌های find_limits، find_limits_noheap یا substitute_callout استفاده کرد.

به طور مشابه، برای اهداف آزمایشی، اگر اصلاح‌کننده null_subject یا null_replacement تنظیم شود، اشاره‌گرهای رشته هدف یا جایگزین به ترتیب به عنوان NULL به توابع مربوطه ارسال می‌شوند.

فراخوانی‌ها با آرگومان‌های عددی (Callouts with numerical arguments)

به‌طور پیش‌فرض، تابع فراخوانی شماره فراخوانی، موقعیت‌های شروع و فعلی در متن موضوع را در زمان فراخوانی، و مورد بعدی الگو را که باید آزمایش شود نمایش می‌دهد. برای مثال:

--->pqrabcdef
0 ^ ^ \d

این خروجی نشان می‌دهد که فراخوانی شماره 0 برای یک تلاش تطبیق رخ داده است که از چهارمین نویسه رشته موضوع شروع شده، زمانی که اشاره‌گر در هفتمین نویسه بوده و مورد بعدی الگو \d بوده است. اگر موقعیت شروع و موقعیت فعلی یکسان باشند، یا اگر موقعیت فعلی پیش از موقعیت شروع باشد (که در صورت قرار داشتن فراخوانی در یک ادعای پس‌نگری ممکن است رخ دهد)، تنها یک علامت هشتک (circumflex) خروجی داده می‌شود.

فراخوانی‌های شماره 255 به عنوان فراخوانی‌های خودکار در نظر گرفته می‌شوند که در نتیجه اصلاح‌کننده الگوی auto_callout درج شده‌اند. در این حالت، به جای نمایش شماره فراخوانی، آفست در الگو که با علامت مثبت پیشوند شده است، خروجی داده می‌شود. برای مثال:

re> /\d?[A-E]\*/auto_callout
data> E*
--->E*
+0 ^ \d?
+3 ^ [A-E]
+8 ^^ \*
+10 ^ ^
0: E*

اگر یک الگو شامل موارد (*MARK) باشد، هر زمان که تغییری در آخرین علامت (mark) به تابع فراخوانی ارسال شود، یک خط اضافی خروجی داده می‌شود. برای مثال:

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

علامت بین تطبیق "a" و "b" تغییر می‌کند، اما برای بقیه تطابق ثابت می‌ماند، بنابراین خروجی دیگری تولید نمی‌شود. اگر در نتیجه پس‌گرد (backtracking)، علامت به حالت مقداردهی‌نشده بازگردد، متن "<unset>" خروجی داده می‌شود.

فراخوانی‌ها با آرگومان‌های رشته‌ای (Callouts with string arguments)

خروجی برای یک فراخوانی با آرگومان رشته‌ای مشابه است، به جز اینکه به جای خروجی دادن شماره فراخوانی قبل از نشانگرهای موقعیت، رشته فراخوانی و آفست آن در رشته الگو قبل از بازتاب رشته موضوع خروجی داده می‌شوند، و رشته موضوع برای هر فراخوانی بازتاب می‌یابد. برای مثال:

re> /^ab(?C'first')cd(?C"second")ef/
data> abcdefg
Callout (7): 'first'
--->abcdefg
^ ^ c
Callout (20): "second"
--->abcdefg
^ ^ e
0: abcdef

اصلاح‌کننده‌های فراخوانی (Callout modifiers)

تابع فراخوانی در pcre2test به‌طور پیش‌فرض مقدار صفر (ادامه تطبیق) را بازمی‌گرداند، اما می‌توانید از یک اصلاح‌کننده callout_fail در یک خط موضوع برای تغییر این رفتار و سایر پارامترهای فراخوانی استفاده کنید (به زیر مراجعه کنید).

اگر اصلاح‌کننده callout_capture تنظیم شده باشد، گروه‌های ضبط‌شده فعلی هنگام وقوع یک فراخوانی خروجی داده می‌شوند. این مورد تنها برای تطبیق غیر DFA مفید است، زیرا pcre2_dfa_match() از ضبط پشتیبانی نمی‌کند، بنابراین هیچ گروه ضبط‌شده‌ای هرگز نمایش داده نمی‌شود.

خروجی عادی فراخوانی، که شماره فراخوانی یا آفست الگو را نشان می‌دهد (همان‌طور که در بالا شرح داده شد)، در صورتی که اصلاح‌کننده callout_no_where تنظیم شده باشد سرکوب می‌شود.

هنگام استفاده از تابع تطبیق تفسیری pcre2_match() بدون JIT، تنظیم اصلاح‌کننده callout_extra باعث می‌شود خروجی اضافی از تابع فراخوانی pcre2test تولید شود. برای اولین فراخوانی در یک تلاش تطبیق در موقعیت شروع جدید در موضوع، عبارت "New match attempt" خروجی داده می‌شود. اگر از زمان آخرین فراخوانی (یا شروع تطبیق اگر این اولین فراخوانی باشد) پس‌گرد (backtrack) رخ داده باشد، عبارت "Backtrack" خروجی داده می‌شود، و به دنبال آن در صورتی که پس‌گرد به تلاش قبلی تطبیق پایان داده باشد، عبارت "No other matching paths" می‌آید. برای مثال:

re> /(a+)b/auto_callout,no_start_optimize,no_auto_possess
data> aac\=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

توجه داشته باشید که اگر می‌خواهید تمام مسیرهای ممکن تطبیق بررسی شوند، بهینه‌سازی‌های مختلف باید خاموش شوند. اگر no_start_optimize استفاده نشود، یک "no match" فوری بدون هیچ فراخوانی رخ می‌دهد، زیرا بهینه‌سازی شروع نمی‌تواند "b" را در موضوع پیدا کند، که می‌داند برای هر تطابقی باید حضور داشته باشد. اگر no_auto_possess استفاده نشود، مورد "a+" به "a++" تبدیل می‌شود، که تعداد پس‌گردها را کاهش می‌دهد.

اصلاح‌کننده callout_extra در صورت استفاده با تابع تطبیق DFA یا با JIT هیچ تاثیری ندارد.

مقادیر بازگشتی از فراخوانی‌ها (Return values from callouts)

مقدار بازگشتی پیش‌فرض از تابع فراخوانی صفر است که به تطبیق اجازه می‌دهد ادامه یابد. به اصلاح‌کننده callout_fail می‌توان یک یا دو عدد اختصاص داد. اگر تنها یک عدد وجود داشته باشد، هنگامی که به فراخوانی آن شماره رسیده شود مقدار 1 به جای 0 بازگردانده می‌شود (که باعث پس‌گرد در تطبیق می‌گردد). اگر دو عدد (<n>:<m>) داده شود، هنگامی که به فراخوانی <n> رسیده شود و حداقل <m> فراخوانی وجود داشته باشد، مقدار 1 بازگردانده می‌شود. اصلاح‌کننده callout_error نیز مشابه است، با این تفاوت که مقدار PCRE2_ERROR_CALLOUT بازگردانده می‌شود و باعث می‌گردد کل فرآیند تطبیق لغو شود. اگر هر دوی این اصلاح‌کننده‌ها برای یک شماره فراخوانی تنظیم شوند، callout_error تقدم دارد. توجه داشته باشید که به فراخوانی‌های با آرگومان‌های رشته‌ای همیشه شماره صفر اختصاص داده می‌شود.

به اصلاح‌کننده callout_data می‌توان یک عدد بدون علامت یا منفی داد. این مقدار به عنوان "user data" تنظیم می‌شود که به تابع تطبیق ارسال می‌گردد و هنگام فراخوانی تابع callout برگردانده می‌شود. هر مقداری غیر از صفر به عنوان مقدار بازگشتی از تابع فراخوانی pcre2test استفاده می‌شود.

درج فراخوانی‌ها می‌تواند هنگام استفاده از pcre2test برای بررسی عبارت‌های منظم پیچیده مفید باشد. برای اطلاعات بیشتر درباره فراخوانی‌ها، به pcre2callout مستندات مراجعه کنید.