.TH PCRETEST 1 "10 February 2020" "PCRE 8.44" .SH "نام (NAME)" pcretest \- برنامه آزمون برای کتابخانه عبارت باقاعده PCRE .SH "خلاصه دستور (SYNOPSIS)" .rs .sp .B pcretest "[options] [input file [output file]]" .sp \fBpcretest\fP به عنوان یک برنامه آزمایشی برای خود کتابخانه عبارات باقاعده PCRE نوشته شده است، اما همچنین می‌تواند برای آزمایش و تجربه کار با عبارات باقاعده مورد استفاده قرار گیرد. این سند ویژگی‌های این برنامه آزمایشی را توصیف می‌کند؛ برای جزئیات در مورد خود عبارات باقاعده، به مستندات .\" HREF \fBpcrepattern\fP .\" مراجعه کنید. برای جزئیات در مورد فراخوانی‌های توابع کتابخانه PCRE و گزینه‌های آن‌ها، به مستندات .\" HREF \fBpcreapi\fP .\" ، .\" HREF \fBpcre16\fP و .\" HREF \fBpcre32\fP .\" مراجعه نمایید. .P ورودی \fBpcretest\fP دنباله‌ای از الگوهای عبارت باقاعده و رشته‌هایی است که باید با آن‌ها تطبیق داده شوند، همان‌طور که در ادامه شرح داده شده است. خروجی نتیجه هر تطابق را نمایش می‌دهد. گزینه‌ها در خط فرمان و الگوها گزینه‌های PCRE و دقیقاً آنچه را که در خروجی ظاهر می‌شود کنترل می‌کنند. .P همان‌طور که PCRE تکامل یافته است، ویژگی‌های مختلف بسیاری را به دست آورده و در نتیجه، \fBpcretest\fP اکنون دارای گزینه‌های نسبتاً مبهم و تخصصی فراوانی برای آزمایش هر ویژگی ممکن است. برخی از این گزینه‌ها مشخصاً برای استفاده همراه با اسکریپت آزمون و فایل‌های داده که به عنوان بخشی از PCRE توزیع می‌شوند طراحی شده‌اند، و بعید است در موارد دیگر کاربرد داشته باشند. همه آن‌ها در اینجا مستند شده‌اند، اما بدون توجیه و استدلال چندان. . . .SH "فرمت دادههای ورودی (INPUT DATA FORMAT)" .rs .sp ورودی \fBpcretest\fP خط به خط پردازش می‌شود، چه با فراخوانی تابع \fBfgets()\fP کتابخانه C و چه از طریق کتابخانه \fBlibreadline\fP (به پایین مراجعه کنید). در محیط‌های شبه یونیکس، \fBfgets()\fP با هر بایتی غیر از خط جدید به عنوان کاراکتر داده رفتار می‌کند. با این حال، در برخی از محیط‌های ویندوز کاراکتر ۲۶ (هگز 1A) باعث پایان فوری فایل (EOF) می‌شود و داده دیگری خوانده نخواهد شد. برای حداکثر سازگاری و قابلیت حمل، بنابراین امن‌ترین کار استفاده تنها از کاراکترهای اسکی (ASCII) در فایل‌های ورودی \fBpcretest\fP است. .P ورودی با استفاده از توابع رشته‌ای C پردازش می‌شود، بنابراین نباید حاوی صفرهای باینری باشد، حتی با اینکه در محیط‌های شبه یونیکس، \fBfgets()\fP با هر بایتی غیر از خط جدید به عنوان کاراکتر داده رفتار می‌کند. . . .SH "کتابخانه‌های ۸ بیتی، ۱۶ بیتی و ۳۲ بیتی PCRE (PCRE's 8-BIT, 16-BIT AND 32-BIT LIBRARIES)" .rs .sp از نگارش 8.30، دو کتابخانه مجزای PCRE می‌توانند ساخته شوند. نگارش اصلی از رشته‌های کاراکتری ۸ بیتی پشتیبانی می‌کند، در حالی که کتابخانه جدیدتر ۱۶ بیتی از رشته‌های کاراکتری کدگذاری‌شده در واحدهای ۱۶ بیتی پشتیبانی می‌کند. از نگارش 8.32، کتابخانه سومی می‌تواند ساخته شود که از رشته‌های کاراکتری با کدگذاری در واحدهای ۳۲ بیتی پشتیبانی می‌کند. برنامه \fBpcretest\fP می‌تواند برای آزمایش هر سه کتابخانه مورد استفاده قرار گیرد. با این حال، خود این برنامه همچنان یک برنامه ۸ بیتی است که ورودی ۸ بیتی می‌خواند و خروجی ۸ بیتی می‌نویسد. هنگام آزمایش کتابخانه ۱۶ بیتی یا ۳۲ بیتی، الگوها و رشته‌های داده پیش از ارسال به توابع کتابخانه PCRE، به فرمت ۱۶ بیتی یا ۳۲ بیتی تبدیل می‌شوند. نتایج برای نمایش خروجی به فرمت ۸ بیتی تبدیل می‌شوند. .P اشاره به توابع و ساختارهایی به شکل \fBpcre[16|32]_xx\fP در ادامه به این معنی است: «\fBpcre_xx\fP هنگام استفاده از کتابخانه ۸ بیتی، \fBpcre16_xx\fP هنگام استفاده از کتابخانه ۱۶ بیتی، یا \fBpcre32_xx\fP هنگام استفاده از کتابخانه ۳۲ بیتی». . . .SH "گزینههای خط فرمان (COMMAND LINE OPTIONS)" .rs .TP 10 \fB-8\fP اگر کتابخانه ۸ بیتی ساخته شده باشد، این گزینه باعث می‌شود از آن استفاده شود (این حالت پیش‌فرض است). اگر کتابخانه ۸ بیتی ساخته نشده باشد، این گزینه موجب خطا می‌شود. .TP 10 \fB-16\fP اگر کتابخانه ۱۶ بیتی ساخته شده باشد، این گزینه باعث می‌شود از آن استفاده شود. اگر فقط کتابخانه ۱۶ بیتی ساخته شده باشد، این حالت پیش‌فرض است. اگر کتابخانه ۱۶ بیتی ساخته نشده باشد، این گزینه موجب خطا می‌شود. .TP 10 \fB-32\fP اگر کتابخانه ۳۲ بیتی ساخته شده باشد، این گزینه باعث می‌شود از آن استفاده شود. اگر فقط کتابخانه ۳۲ بیتی ساخته شده باشد، این حالت پیش‌فرض است. اگر کتابخانه ۳۲ بیتی ساخته نشده باشد، این گزینه موجب خطا می‌شود. .TP 10 \fB-b\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/B\fP (نمایش بایت‌کد) است؛ فرم داخلی پس از کامپایل در خروجی چاپ می‌شود. .TP 10 \fB-C\fP شماره نسخه کتابخانه PCRE و تمام اطلاعات موجود درباره ویژگی‌های اختیاری گنجانده‌شده را نمایش داده و سپس با کد خروج صفر خارج می‌شود. تمام گزینه‌های دیگر نادیده گرفته می‌شوند. .TP 10 \fB-C\fP \fIoption\fP اطلاعات مربوط به یک گزینه خاص زمان ساخت را چاپ کرده و سپس خارج می‌شود. این قابلیت برای استفاده در اسکریپت‌هایی مانند \fBRunTest\fP در نظر گرفته شده است. گزینه‌های زیر مقدار را در خروجی چاپ کرده و کد خروج را همان‌طور که مشخص شده تنظیم می‌کنند: .sp .nf ebcdic-nl کد برای LF (= NL) در محیط EBCDIC: 0x15 یا 0x25 0 در صورت استفاده در محیط ASCII کد خروج همیشه 0 است linksize اندازه پیوند داخلی پیکربندی‌شده (2، 3 یا 4) کد خروج بر روی اندازه پیوند تنظیم می‌شود newline تنظیم پیش‌فرض خط جدید: CR, LF, CRLF, ANYCRLF, یا ANY کد خروج همیشه 0 است bsr تنظیم پیش‌فرض برای آنچه \eR تطبیق می‌دهد: ANYCRLF یا ANY کد خروج همیشه 0 است .fi .sp گزینه‌های زیر مقدار 1 را برای درست یا 0 را برای نادرست در خروجی چاپ کرده و کد خروج را به همان مقدار تنظیم می‌کنند: .sp .nf ebcdic کامپایل‌شده برای محیط EBCDIC jit پشتیبانی Just-In-Time در دسترس است pcre16 کتابخانه ۱۶ بیتی ساخته شده است pcre32 کتابخانه ۳۲ بیتی ساخته شده است pcre8 کتابخانه ۸ بیتی ساخته شده است ucp پشتیبانی از خصوصیات یونیکد در دسترس است utf پشتیبانی از UTF-8 و/یا UTF-16 و/یا UTF-32 در دسترس است .fi .sp اگر گزینه ناشناخته‌ای داده شود، پیام خطا در خروجی نمایش داده می‌شود؛ کد خروج 0 است. .TP 10 \fB-d\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/D\fP (اشکال‌زدایی) است؛ فرم داخلی و اطلاعات مربوط به الگوی کامپایل‌شده پس از کامپایل در خروجی نمایش داده می‌شوند؛ گزینه \fB-d\fP معادل \fB-b -i\fP است. .TP 10 \fB-dfa\fP طوری عمل می‌کند که گویی هر خط داده حاوی دنباله گریز \eD است؛ این امر باعث می‌شود تابع تطبیق جایگزین، یعنی \fBpcre[16|32]_dfa_exec()\fP، به جای تابع استاندارد \fBpcre[16|32]_exec()\fP استفاده شود (جزئیات بیشتر در ادامه آمده است). .TP 10 \fB-help\fP خلاصه‌ای کوتاه از این گزینه‌ها را در خروجی چاپ کرده و سپس خارج می‌شود. .TP 10 \fB-i\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/I\fP است؛ اطلاعات مربوط به الگوی کامپایل‌شده پس از کامپایل ارائه می‌شود. .TP 10 \fB-M\fP طوری عمل می‌کند که گویی هر خط داده حاوی دنباله گریز \eM است؛ این امر باعث می‌شود PCRE با فراخوانی مکرر \fBpcre[16|32]_exec()\fP با محدودیت‌های مختلف، حداقل تنظیمات MATCH_LIMIT و MATCH_LIMIT_RECURSION را کشف کند. .TP 10 \fB-m\fP اندازه هر الگوی کامپایل‌شده را پس از کامپایل شدن در خروجی چاپ می‌کند. این معادل افزودن \fB/M\fP به هر عبارت باقاعده است. اندازه برای هر دو کتابخانه بر حسب بایت ارائه می‌شود. .TP 10 \fB-O\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/O\fP است، یعنی auto-possessification را برای تمام الگوها غیرفعال می‌کند. .TP 10 \fB-o\fP \fIosize\fP تعداد عناصر موجود در بردار خروجی را که هنگام فراخوانی \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP استفاده می‌شود بر روی \fIosize\fP تنظیم می‌کند. مقدار پیش‌فرض 45 است که برای 14 زیرعبارت ضبط‌کننده برای \fBpcre[16|32]_exec()\fP یا 22 تطابق مختلف برای \fBpcre[16|32]_dfa_exec()\fP کافی است. اندازه بردار می‌تواند برای فراخوانی‌های تطبیق فردی با گنجاندن \eO در خط داده تغییر داده شود (به پایین مراجعه کنید). .TP 10 \fB-p\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/P\fP است؛ از رابط کاربری برنامه‌نویسی پوششی POSIX برای فراخوانی PCRE استفاده می‌شود. زمانی که \fB-p\fP تنظیم شده باشد هیچ‌یک از گزینه‌های دیگر هیچ اثری ندارند. این گزینه فقط با کتابخانه ۸ بیتی قابل استفاده است. .TP 10 \fB-q\fP شماره نسخه \fBpcretest\fP را در ابتدای اجرا نمایش نمی‌دهد. .TP 10 \fB-S\fP \fIsize\fP در سیستم‌های شبه یونیکس، اندازه پشته زمان اجرا را به \fIsize\fP مگابایت تنظیم می‌کند. .TP 10 \fB-s\fP یا \fB-s+\fP طوری عمل می‌کند که گویی هر الگو دارای تغییردهنده \fB/S\fP است؛ به بیان دیگر، هر الگو را مجبور به مطالعه می‌کند. اگر از \fB-s+\fP استفاده شود، تمام گزینه‌های کامپایل JIT به \fBpcre[16|32]_study()\fP ارسال می‌شوند که در صورت در دسترس بودن، باعث راه‌اندازی بهینه‌سازی Just-In-Time برای هر دو تطابق کامل و جزئی می‌شود. گزینه‌های خاص کامپایل JIT را می‌توان با قرار دادن یک رقم در محدوده 1 تا 7 پس از \fB-s+\fP انتخاب کرد که حالت‌های کامپایل JIT را به شرح زیر تعیین می‌کند: .sp .nf 1 فقط تطابق عادی 2 فقط تطابق جزئی ملایم (soft partial) 3 تطابق عادی و تطابق جزئی ملایم 4 فقط تطابق جزئی سخت (hard partial) 6 تطابق جزئی ملایم و سخت 7 هر سه حالت (پیش‌فرض) .fi .sp اگر به جای \fB-s+\fP از \fB-s++\fP استفاده شود (با یا بدون رقم بعدی)، هنگامی که کد کامپایل‌شده JIT در عمل استفاده شده باشد، متن "(JIT)" به اولین خط خروجی پس از یک تطابق یا عدم تطابق اضافه می‌شود. .sp توجه داشته باشید که گزینه‌های الگو می‌توانند \fB-s\fP را لغو و بازنویسی کنند، چه با مشخص کردن عدم مطالعه و چه با متوقف کردن کامپایل JIT. .sp اگر گزینه \fB/I\fP یا \fB/D\fP روی یک الگو وجود داشته باشد (درخواست خروجی درباره الگوی کامپایل‌شده)، اطلاعات مربوط به نتیجه مطالعه در صورتی که مطالعه تنها ناشی از \fB-s\fP بوده و نه \fB-i\fP و نه \fB-d\fP در خط فرمان وجود نداشته باشند، گنجانده نمی‌شود. این رفتار به این معنی است که خروجی آزمون‌هایی که با و بدون \fB-s\fP اجرا می‌شوند باید یکسان باشد، مگر زمانی که گزینه‌هایی که اطلاعات مربوط به اجرای واقعی یک تطابق را چاپ می‌کنند تنظیم شده باشند. .sp گزینه‌های \fB-M\fP، \fB-t\fP و \fB-tm\fP که اطلاعاتی درباره منابع استفاده‌شده ارائه می‌دهند، احتمالاً خروجی متفاوتی با و بدون \fB-s\fP تولید می‌کنند. خروجی همچنین ممکن است در صورتی که گزینه \fB/C\fP روی یک الگوی فردی وجود داشته باشد متفاوت باشد. این گزینه از فراخوانی‌ها برای ردگیری فرآیند تطبیق استفاده می‌کند و این ممکن است بین الگوهای مطالعه‌شده و مطالعه‌نشده متفاوت باشد. اگر الگو حاوی آیتم‌های (*MARK) باشد نیز ممکن است به همین دلیل تفاوت‌هایی وجود داشته باشد. گزینه خط فرمان \fB-s\fP می‌تواند برای الگوهای خاصی که هرگز نباید مطالعه شوند لغو شود (به تغییردهنده الگوی \fB/S\fP در ادامه مراجعه کنید). .TP 10 \fB-t\fP هر فرآیند کامپایل، مطالعه و تطبیق را چندین بار با یک زمان‌سنج اجرا کرده و زمان‌های حاصل را برای هر کامپایل، مطالعه یا تطبیق (بر حسب میلی‌ثانیه) در خروجی چاپ می‌کند. گزینه \fB-m\fP را همراه با \fB-t\fP تنظیم نکنید، زیرا در این صورت خروجی اندازه را بارها و بارها دریافت خواهید کرد و زمان‌بندی مخدوش خواهد شد. شما می‌توانید با قرار دادن یک عدد پس از \fB-t\fP (به عنوان یک آیتم جداگانه در خط فرمان)، تعداد تکرارهای استفاده‌شده برای زمان‌گیری را کنترل کنید. برای مثال، "-t 1000" تعداد 1000 بار تکرار می‌کند. پیش‌فرض 500000 بار تکرار است. .TP 10 \fB-tm\fP این مانند \fB-t\fP است با این تفاوت که تنها مرحله تطبیق را زمان‌گیری می‌کند، نه مراحل کامپایل یا مطالعه را. .TP 10 \fB-T\fP \fB-TM\fP این گزینه‌ها مانند \fB-t\fP و \fB-tm\fP عمل می‌کنند، اما علاوه بر آن، در پایان اجرا، زمان‌های کل برای تمام کامپایل‌ها، مطالعه‌ها و تطابق‌ها در خروجی چاپ می‌شوند. . . .SH "توضیحات (DESCRIPTION)" .rs .sp اگر به \fBpcretest\fP دو آرگومان نام فایل داده شود، از اولی می‌خواند و در دومی می‌نویسد. اگر فقط یک آرگومان نام فایل به آن داده شود، از آن فایل می‌خواند و در stdout می‌نویسد. در غیر این صورت، از stdin خوانده و در stdout می‌نویسد، و برای هر خط ورودی اعلان (prompt) نمایش می‌دهد، با استفاده از "re>" برای اعلان عبارات باقاعده و "data>" برای اعلان خطوط داده. .P هنگام ساخت \fBpcretest\fP، یک گزینه پیکربندی می‌تواند مشخص کند که این برنامه باید با کتابخانه \fBlibreadline\fP پیوند داده شود. هنگامی که این کار انجام شود، اگر ورودی از یک ترمینال باشد، با استفاده از تابع \fBreadline()\fP خوانده می‌شود. این کار امکانات ویرایش خط و تاریخچه را فراهم می‌آورد. خروجی گزینه \fB-help\fP بیان می‌کند که آیا از \fBreadline()\fP استفاده خواهد شد یا خیر. .P این برنامه هر تعداد مجموعه ورودی را روی یک فایل ورودی واحد پردازش می‌کند. هر مجموعه با یک عبارت باقاعده شروع می‌شود، و با هر تعداد خط داده که باید در برابر آن الگو تطبیق داده شوند ادامه می‌یابد. .P هر خط داده به طور جداگانه و مستقل تطبیق داده می‌شود. اگر می‌خواهید تطابق‌های چندخطی انجام دهید، باید از دنباله گریز \en (یا \er یا \er\en و غیره، بسته به تنظیم خط جدید) در یک خط واحد از ورودی برای کدگذاری دنباله‌های خط جدید استفاده کنید. هیچ محدودیتی برای طول خطوط داده وجود ندارد؛ بافر ورودی در صورتی که خیلی کوچک باشد به طور خودکار گسترش می‌یابد. .P یک خط خالی پایان خطوط داده را نشان می‌دهد که در این نقطه، یک عبارت باقاعده جدید خوانده می‌شود. عبارات باقاعده محصور در هر جداکننده غیرحرفی-عددی غیر از بک‌اسلش وارد می‌شوند، برای مثال: .sp .nf /(a|bc)x+yz/ .fi .sp فاصله خالی پیش از جداکننده ابتدایی نادیده گرفته می‌شود. یک عبارت باقاعده ممکن است روی چندین خط ورودی ادامه یابد، که در این حالت کاراکترهای خط جدید درون آن گنجانده می‌شوند. گنجاندن جداکننده درون الگو از طریق اسکیپ کردن آن امکان‌پذیر است، برای مثال: .sp .nf /abc\e/def/ .fi .sp اگر چنین کنید، کاراکتر گریز و جداکننده بخشی از الگو را تشکیل می‌دهند، اما از آنجا که جداکننده‌ها همیشه غیرحرفی-عددی هستند، این امر بر تفسیر آن اثری نمی‌گذارد. اگر بلافاصله پس از جداکننده پایانی یک بک‌اسلش بیاید، به عنوان مثال: .sp .nf /abc/\e .fi .sp آنگاه یک بک‌اسلش به انتهای الگو اضافه می‌شود. این کار برای فراهم کردن راهی جهت آزمایش شرایط خطایی انجام شده است که در صورت خاتمه یافتن یک الگو با بک‌اسلش رخ می‌دهد، زیرا: .sp .nf /abc\e/ .fi .sp به عنوان خط اول الگویی تفسیر می‌شود که با "abc/" شروع می‌شود و باعث می‌شود pcretest خط بعدی را به عنوان ادامه عبارت باقاعده بخواند. . . .SH "تغییردهنده‌های الگو (PATTERN MODIFIERS)" .rs .sp یک الگو می‌تواند با هر تعداد تغییردهنده دنبال شود، که بیشتر آن‌ها تک‌کاراکتری هستند، هرچند برخی از آن‌ها می‌توانند با کاراکترهای بعدی توصیف شوند. به پیروی از کاربرد پرل (Perl)، در ادامه از این‌ها به عنوان مثال با عنوان «تغییردهنده \fB/i\fP» یاد می‌شود، حتی با وجود اینکه جداکننده الگو لزوماً نباید همیشه یک اسلش باشد و هیچ اسلشی نیز هنگام نوشتن تغییردهنده‌ها استفاده نمی‌شود. فاصله خالی ممکن است بین جداکننده نهایی الگو و اولین تغییردهنده، و بین خود تغییردهنده‌ها ظاهر شود. برای ارجاع، در اینجا فهرستی کامل از تغییردهنده‌ها آورده شده است. آن‌ها در چندین گروه قرار می‌گیرند که در بخش‌های بعدی به تفصیل شرح داده شده‌اند. .sp .nf \fB/8\fP تنظیم حالت UTF \fB/9\fP تنظیم PCRE_NEVER_UTF (مسدود کردن حالت UTF) \fB/?\fP غیرفعال کردن بررسی اعتبار UTF \fB/+\fP نمایش باقیمانده رشته هدف پس از تطابق \fB/=\fP نمایش تمام موارد ضبط‌شده (نه فقط مواردی که مقدار دارند) \fB/A\fP تنظیم PCRE_ANCHORED \fB/B\fP نمایش کد کامپایل‌شده \fB/C\fP تنظیم PCRE_AUTO_CALLOUT \fB/D\fP همان \fB/B\fP به علاوه \fB/I\fP \fB/E\fP تنظیم PCRE_DOLLAR_ENDONLY \fB/F\fP معکوس کردن ترتیب بایت‌ها در الگوی کامپایل‌شده \fB/f\fP تنظیم PCRE_FIRSTLINE \fB/G\fP یافتن تمام تطابق‌ها (کوتاه کردن رشته) \fB/g\fP یافتن تمام تطابق‌ها (استفاده از startoffset) \fB/I\fP نمایش اطلاعات درباره الگو \fB/i\fP تنظیم PCRE_CASELESS \fB/J\fP تنظیم PCRE_DUPNAMES \fB/K\fP نمایش نام‌های کنترل پس‌گرد \fB/L\fP تنظیم محلی‌سازی (locale) \fB/M\fP نمایش اندازه حافظه کامپایل‌شده \fB/m\fP تنظیم PCRE_MULTILINE \fB/N\fP تنظیم PCRE_NO_AUTO_CAPTURE \fB/O\fP تنظیم PCRE_NO_AUTO_POSSESS \fB/P\fP استفاده از پوشش POSIX \fB/Q\fP آزمایش تابع خارجی بررسی پشته \fB/S\fP مطالعه الگو پس از کامپایل \fB/s\fP تنظیم PCRE_DOTALL \fB/T\fP انتخاب جداول کاراکتری \fB/U\fP تنظیم PCRE_UNGREEDY \fB/W\fP تنظیم PCRE_UCP \fB/X\fP تنظیم PCRE_EXTRA \fB/x\fP تنظیم PCRE_EXTENDED \fB/Y\fP تنظیم PCRE_NO_START_OPTIMIZE \fB/Z\fP عدم نمایش طول‌ها در خروجی \fB/B\fP \fB/\fP تنظیم PCRE_NEWLINE_ANY \fB/\fP تنظیم PCRE_NEWLINE_ANYCRLF \fB/\fP تنظیم PCRE_NEWLINE_CR \fB/\fP تنظیم PCRE_NEWLINE_CRLF \fB/\fP تنظیم PCRE_NEWLINE_LF \fB/\fP تنظیم PCRE_BSR_ANYCRLF \fB/\fP تنظیم PCRE_BSR_UNICODE \fB/\fP تنظیم PCRE_JAVASCRIPT_COMPAT .fi .sp . . .SS "تغییردهنده‌های سازگار با پرل (Perl-compatible modifiers)" .rs .sp تغییردهنده‌های \fB/i\fP، \fB/m\fP، \fB/s\fP و \fB/x\fP هنگام فراخوانی \fBpcre[16|32]_compile()\fP به ترتیب گزینه‌های PCRE_CASELESS، PCRE_MULTILINE، PCRE_DOTALL یا PCRE_EXTENDED را تنظیم می‌کنند. این چهار حرف تغییردهنده همان تأثیری را دارند که در پرل دارند. برای مثال: .sp .nf /caseless/i .fi .sp . . .SS "تغییردهنده‌ها برای سایر گزینه‌های PCRE (Modifiers for other PCRE options)" .rs .sp جدول زیر تغییردهنده‌های اضافی را برای تنظیم گزینه‌های زمان کامپایل PCRE نشان می‌دهد که با موردی در پرل مطابقت ندارند: .sp .nf \fB/8\fP PCRE_UTF8 ) هنگام استفاده از کتابخانه \fB/?\fP PCRE_NO_UTF8_CHECK ) ۸ بیتی \fB/8\fP PCRE_UTF16 ) هنگام استفاده از کتابخانه \fB/?\fP PCRE_NO_UTF16_CHECK ) ۱۶ بیتی \fB/8\fP PCRE_UTF32 ) هنگام استفاده از کتابخانه \fB/?\fP PCRE_NO_UTF32_CHECK ) ۳۲ بیتی \fB/9\fP PCRE_NEVER_UTF \fB/A\fP PCRE_ANCHORED \fB/C\fP PCRE_AUTO_CALLOUT \fB/E\fP PCRE_DOLLAR_ENDONLY \fB/f\fP PCRE_FIRSTLINE \fB/J\fP PCRE_DUPNAMES \fB/N\fP PCRE_NO_AUTO_CAPTURE \fB/O\fP PCRE_NO_AUTO_POSSESS \fB/U\fP PCRE_UNGREEDY \fB/W\fP PCRE_UCP \fB/X\fP PCRE_EXTRA \fB/Y\fP PCRE_NO_START_OPTIMIZE \fB/\fP PCRE_NEWLINE_ANY \fB/\fP PCRE_NEWLINE_ANYCRLF \fB/\fP PCRE_NEWLINE_CR \fB/\fP PCRE_NEWLINE_CRLF \fB/\fP PCRE_NEWLINE_LF \fB/\fP PCRE_BSR_ANYCRLF \fB/\fP PCRE_BSR_UNICODE \fB/\fP PCRE_JAVASCRIPT_COMPAT .fi .sp تغییردهنده‌هایی که در براکت‌های گوشه‌دار محصور شده‌اند رشته‌های لفظی هستند همان‌طور که نشان داده شده است، از جمله خود براکت‌ها، اما حروف درون آن‌ها می‌تواند با هر دو حالت کوچک یا بزرگ باشد. این مثال تطابق چندخطی را با CRLF به عنوان دنباله پایان خط تنظیم می‌کند: .sp .nf /^abc/m .fi .sp علاوه بر فعال کردن گزینه PCRE_UTF8/16/32، تغییردهنده \fB/8\fP باعث می‌شود تمام کاراکترهای غیرقابل چاپ در رشته‌های خروجی با استفاده از نمادگذاری \ex{hh...} چاپ شوند. در غیر این صورت، موارد کمتر از 0x100 در مبنای شانزده بدون براکت‌های کروشه‌ای چاپ می‌شوند. .P جزئیات کامل گزینه‌های PCRE در مستندات .\" HREF \fBpcreapi\fP .\" آمده است. . . .SS "یافتن همه تطابق‌ها در یک رشته (Finding all matches in a string)" .rs .sp جستجو برای تمام تطابق‌های ممکن در هر رشته هدف می‌تواند با تغییردهنده \fB/g\fP یا \fB/G\fP درخواست شود. پس از یافتن یک تطابق، PCRE مجدداً فراخوانی می‌شود تا باقیمانده رشته هدف را جستجو کند. تفاوت بین \fB/g\fP و \fB/G\fP در این است که اولی از آرگومان \fIstartoffset\fP به \fBpcre[16|32]_exec()\fP برای شروع جستجو در یک نقطه جدید در کل رشته استفاده می‌کند (که در عمل کاری است که پرل انجام می‌دهد)، در حالی که دومی یک زیررشته کوتاه‌شده را ارسال می‌کند. این امر در صورتی که الگو با یک بررسی به عقب (از جمله \eb یا \eB) شروع شود، در فرآیند تطبیق تفاوت ایجاد می‌کند. .P اگر هر فراخوانی به \fBpcre[16|32]_exec()\fP در یک دنباله \fB/g\fP یا \fB/G\fP با یک رشته خالی تطبیق یابد، فراخوانی بعدی با فلگ‌های PCRE_NOTEMPTY_ATSTART و PCRE_ANCHORED تنظیم‌شده انجام می‌شود تا به دنبال تطابق دیگری و غیرخالی در همان نقطه بگردد. اگر این تطابق دوم ناموفق باشد، آفست شروع به جلو رانده می‌شود و تطابق عادی مجدداً تلاش می‌شود. این امر شیوه مدیریت چنین مواردی توسط پرل هنگام استفاده از تغییردهنده \fB/g\fP یا تابع \fBsplit()\fP را تقلید می‌کند. به طور عادی، آفست شروع به اندازه یک کاراکتر جلو برده می‌شود، اما اگر قرارداد خط جدید CRLF را به عنوان یک خط جدید بشناسد و کاراکتر فعلی CR و به دنبال آن LF باشد، پیشروی به اندازه دو کاراکتر استفاده می‌شود. . . .SS "سایر تغییردهنده‌ها (Other modifiers)" .rs .sp تغییردهنده‌های بیشتری نیز برای کنترل شیوه عملکرد \fBpcretest\fP وجود دارند. .P تغییردهنده \fB/+\fP درخواست می‌کند که علاوه بر چاپ زیررشته‌ای که با کل الگو تطبیق یافته است، \fBpcretest\fP باید علاوه بر آن باقیمانده رشته هدف را نیز در خروجی نمایش دهد. این برای آزمون‌هایی که در آن‌ها رشته هدف شامل چندین نسخه از همان زیررشته است مفید است. اگر تغییردهنده \fB+\fP دو بار ظاهر شود، همین عمل برای زیررشته‌های ضبط‌شده نیز انجام می‌گیرد. در هر مورد، باقیمانده در خط بعدی با یک کاراکتر مثبت به دنبال شماره ضبط چاپ می‌شود. توجه داشته باشید که این تغییردهنده نباید بلافاصله پس از تغییردهنده /S بیاید زیرا /S+ و /S++ معانی دیگری دارند. .P تغییردهنده \fB/=\fP درخواست می‌کند که مقادیر تمام پرانتزهای بالقوه ضبط‌شده پس از یک تطابق در خروجی چاپ شوند. به طور پیش‌فرض، تنها مواردی که تا بالاترین موردی که واقعاً در تطابق استفاده شده است در خروجی نمایش داده می‌شوند (مربوط به کد برگشتی از \fBpcre[16|32]_exec()\fP). مقادیر در بردار آفست‌ها مربوط به شماره‌های بالاتر باید روی -1 تنظیم شوند، و این موارد به عنوان "" در خروجی نمایش می‌یابند. این تغییردهنده روشی برای بررسی اینکه آیا این اتفاق می‌افتد فراهم می‌کند. .P تغییردهنده \fB/B\fP یک ویژگی اشکال‌زدایی است. این تغییردهنده درخواست می‌کند که \fBpcretest\fP نمایشی از کد کامپایل‌شده را پس از کامپایل در خروجی چاپ کند. به طور معمول این اطلاعات شامل مقادیر طول و آفست است؛ با این حال، اگر \fB/Z\fP نیز وجود داشته باشد، این داده‌ها با فاصله‌ها جایگزین می‌شوند. این یک ویژگی ویژه برای استفاده در اسکریپت‌های آزمون خودکار است؛ این ویژگی اطمینان می‌دهد که خروجی یکسانی برای اندازه‌های مختلف پیوند داخلی تولید می‌شود. .P تغییردهنده \fB/D\fP یک ویژگی اشکال‌زدایی PCRE است و معادل \fB/BI\fP است، یعنی هر دو تغییردهنده \fB/B\fP و \fB/I\fP. .P تغییردهنده \fB/F\fP باعث می‌شود که \fBpcretest\fP ترتیب بایت‌های فیلدهای ۲ بایتی و ۴ بایتی را در الگوی کامپایل‌شده معکوس کند. این قابلیت برای آزمایش قابلیتی در PCRE است که به آن اجازه می‌دهد الگوهایی را که در میزبانی با اندیاننس (ترتیب بایت) متفاوت کامپایل شده‌اند اجرا کند. این قابلیت زمانی که از رابط POSIX برای PCRE استفاده می‌شود، یعنی زمانی که تغییردهنده الگوی \fB/P\fP مشخص شده باشد، در دسترس نیست. همچنین به بخش مربوط به ذخیره و بارگذاری مجدد الگوهای کامپایل‌شده در زیر مراجعه کنید. .P تغییردهنده \fB/I\fP درخواست می‌کند که \fBpcretest\fP اطلاعات مربوط به الگوی کامپایل‌شده را چاپ کند (اینکه آیا مهار شده است، دارای یک کاراکتر اول ثابت است، و غیره). این کار را با فراخوانی \fBpcre[16|32]_fullinfo()\fP پس از کامپایل یک الگو انجام می‌دهد. اگر الگو مطالعه شده باشد، نتایج آن نیز در خروجی نمایش داده می‌شوند. در این خروجی، کلمه "char" به معنای یک کاراکتر غیر UTF است، یعنی مقدار یک آیتم داده واحد (۸ بیتی، ۱۶ بیتی یا ۳۲ بیتی، بسته به کتابخانه‌ای که آزمایش می‌شود). .P تغییردهنده \fB/K\fP از \fBpcretest\fP می‌خواهد نام‌های حاصل از افعال کنترلی پس‌گرد را که از فراخوانی‌های \fBpcre[16|32]_exec()\fP بازگردانده می‌شوند نمایش دهد. این امر باعث می‌شود \fBpcretest\fP یک بلوک \fBpcre[16|32]_extra\fP ایجاد کند اگر قبلاً توسط فراخوانی به \fBpcre[16|32]_study()\fP ایجاد نشده باشد، و فلگ PCRE_EXTRA_MARK و فیلد \fBmark\fP درون آن را در هر بار فراخوانی \fBpcre[16|32]_exec()\fP تنظیم نماید. اگر متغیری که فیلد \fBmark\fP به آن اشاره می‌کند برای یک تطابق، عدم تطابق یا تطابق جزئی غیر NULL باشد، \fBpcretest\fP رشته‌ای را که به آن اشاره می‌کند چاپ می‌کند. برای یک تطابق، این در یک خط جداگانه با برچسب "MK:" نمایش داده می‌شود. برای یک عدم تطابق، به پیام اضافه می‌شود. .P تغییردهنده \fB/L\fP باید مستقیماً با نام یک محلی‌سازی دنبال شود، برای مثال: .sp .nf /pattern/Lfr_FR .fi .sp به همین دلیل، باید آخرین تغییردهنده باشد. محلی‌سازی داده‌شده تنظیم می‌شود، \fBpcre[16|32]_maketables()\fP برای ساخت مجموعه‌ای از جداول کاراکتری برای آن محلی‌سازی فراخوانی می‌شود، و سپس هنگام کامپایل عبارت باقاعده به \fBpcre[16|32]_compile()\fP ارسال می‌گردد. بدون تغییردهنده \fB/L\fP (یا \fB/T\fP)، مقدار NULL به عنوان اشاره‌گر جداول ارسال می‌شود؛ یعنی \fB/L\fP فقط برای عبارتی که روی آن ظاهر می‌شود اعمال می‌گردد. .P تغییردهنده \fB/M\fP باعث می‌شود اندازه بر حسب بایت بلوک حافظه استفاده‌شده برای نگهداری الگوی کامپایل‌شده در خروجی چاپ شود. این شامل اندازه بلوک \fBpcre[16|32]\fP نمی‌شود؛ تنها داده‌های کامپایل‌شده واقعی است. اگر الگو با موفقیت با گزینه PCRE_STUDY_JIT_COMPILE مطالعه شود، اندازه کد کامپایل‌شده JIT نیز نمایش داده می‌شود. .P تغییردهنده \fB/Q\fP برای آزمایش استفاده از \fBpcre_stack_guard\fP استفاده می‌شود. این تغییردهنده باید با '0' یا '1' دنبال شود که کد برگشتی داده‌شده از یک تابع خارجی را مشخص می‌کند که به PCRE ارسال شده و برای بررسی پشته در طول کامپایل استفاده می‌شود (برای جزئیات به مستندات .\" HREF \fBpcreapi\fP .\" مراجعه کنید). .P تغییردهنده \fB/S\fP باعث می‌شود \fBpcre[16|32]_study()\fP پس از کامپایل شدن عبارت فراخوانی شود و نتایج هنگام تطبیق عبارت مورد استفاده قرار گیرند. تعدادی کاراکتر توصیف‌کننده وجود دارد که ممکن است پس از \fB/S\fP بیایند. آن‌ها می‌توانند به هر ترتیبی ظاهر شوند. .P اگر \fB/S\fP با یک علامت تعجب دنبال شود، \fBpcre[16|32]_study()\fP با گزینه PCRE_STUDY_EXTRA_NEEDED فراخوانی می‌شود و باعث می‌شود همیشه یک بلوک \fBpcre_extra\fP برگرداند، حتی زمانی که مطالعه اطلاعات مفیدی را کشف نکند. .P اگر \fB/S\fP با یک کاراکتر دوم S دنبال شود، مطالعه را متوقف می‌کند، حتی اگر از خارج توسط گزینه خط فرمان \fB-s\fP درخواست شده باشد. این امر مشخص کردن اینکه الگوهای خاصی همیشه مطالعه شوند و بقیه هرگز مطالعه نشوند را مستقل از \fB-s\fP ممکن می‌سازد. این ویژگی در فایل‌های آزمون در چند مورد که خروجی هنگام مطالعه الگو متفاوت است، استفاده می‌شود. .P اگر تغییردهنده \fB/S\fP با یک کاراکتر + دنبال شود، فراخوانی به \fBpcre[16|32]_study()\fP با تمام گزینه‌های مطالعه JIT انجام می‌شود و در صورت در دسترس بودن، پشتیبانی بهینه‌سازی Just-In-Time را برای هر دو تطابق عادی و جزئی درخواست می‌کند. اگر می‌خواهید حالت‌های کامپایل JIT را محدود کنید، می‌توانید پس از \fB/S+\fP یک رقم در محدوده 1 تا 7 قرار دهید: .sp .nf 1 فقط تطابق عادی 2 فقط تطابق جزئی ملایم 3 تطابق عادی و تطابق جزئی ملایم 4 فقط تطابق جزئی سخت 6 تطابق جزئی ملایم و سخت 7 هر سه حالت (پیش‌فرض) .fi .sp اگر به جای \fB/S+\fP از \fB/S++\fP استفاده شود (با یا بدون رقم بعدی)، هنگامی که کد کامپایل‌شده JIT واقعاً استفاده شده باشد، متن "(JIT)" به اولین خط خروجی پس از یک تطابق یا عدم تطابق اضافه می‌شود. .P توجه داشته باشید که یک تغییردهنده مستقل \fB/+\fP نیز وجود دارد؛ این نباید بلافاصله پس از \fB/S\fP یا \fB/S+\fP قرار گیرد زیرا دچار تفسیر نادرست خواهد شد. .P اگر مطالعه JIT موفقیت‌آمیز باشد، کد کامپایل‌شده JIT به طور خودکار هنگام اجرای \fBpcre[16|32]_exec()\fP استفاده خواهد شد، به جز مواردی که گزینه‌های زمان اجرای ناسازگار مشخص شده باشند. برای جزئیات بیشتر، به مستندات .\" HREF \fBpcrejit\fP .\" مراجعه فرمایید. همچنین به دنباله گریز \fB\eJ\fP در زیر برای روشی جهت تعیین اندازه پشته JIT نگاه کنید. .P در نهایت، اگر \fB/S\fP با یک کاراکتر منها دنبال شود، کامپایل JIT متوقف می‌شود، حتی اگر از خارج توسط گزینه خط فرمان \fB-s\fP درخواست شده باشد. این امر مشخص کردن اینکه JIT هرگز نباید برای الگوهای خاصی استفاده شود را ممکن می‌سازد. .P تغییردهنده \fB/T\fP باید با یک رقم منفرد دنبال شود. این امر باعث می‌شود مجموعه خاصی از جداول کاراکتری توکار به \fBpcre[16|32]_compile()\fP ارسال شود. این در آزمون‌های استاندارد PCRE برای بررسی رفتار با جداول کاراکتری مختلف استفاده می‌شود. این رقم جداول را به شرح زیر مشخص می‌کند: .sp .nf 0 جداول پیش‌فرض ASCII، همان‌طور که در pcre_chartables.c.dist توزیع شده است 1 مجموعه‌ای از جداول که کاراکترهای ISO 8859 را تعریف می‌کنند .fi .sp در جدول 1، برخی از کاراکترهایی که کدهای آن‌ها بزرگتر از 128 است به عنوان حروف، ارقام، فاصله‌ها و غیره شناسایی می‌شوند. . . .SS "استفاده از رابط کاربری برنامه‌نویسی پوششی POSIX (Using the POSIX wrapper API)" .rs .sp تغییردهنده \fB/P\fP باعث می‌شود \fBpcretest\fP کتابخانه PCRE را به جای رابط برنامه‌نویسی بومی آن، از طریق رابط کاربری برنامه‌نویسی پوششی POSIX فراخوانی کند. این تنها از کتابخانه ۸ بیتی پشتیبانی می‌کند. هنگامی که \fB/P\fP تنظیم شده باشد، تغییردهنده‌های زیر گزینه‌ها را برای تابع \fBregcomp()\fP تنظیم می‌کنند: .sp .nf /i REG_ICASE /m REG_NEWLINE /N REG_NOSUB /s REG_DOTALL ) /U REG_UNGREEDY ) این گزینه‌ها بخشی از /W REG_UCP ) استاندارد POSIX نیستند /8 REG_UTF8 ) .fi .sp تغییردهنده \fB/+\fP همان‌طور که در بالا شرح داده شد کار می‌کند. تمام تغییردهنده‌های دیگر نادیده گرفته می‌شوند. . . .SS "مسدود کردن برخی تغییردهنده‌ها (Locking out certain modifiers)" .rs .sp کتابخانه PCRE می‌تواند با یا بدون پشتیبانی از ویژگی‌های خاصی مانند UTF-8/16/32 یا خصوصیات یونیکد کامپایل شود. بر این اساس، آزمون‌های استاندارد به تعدادی فایل مختلف تقسیم می‌شوند که برای اجرا بر اساس ویژگی‌های در دسترس انتخاب می‌شوند. هنگام به‌روزرسانی آزمون‌ها، بسیار آسان است که یک آزمون جدید به اشتباه در فایل نادرستی قرار داده شود؛ به عنوان مثال، قرار دادن آزمونی که نیاز به پشتیبانی UTF دارد در فایلی که در صورت عدم در دسترس بودن آن استفاده می‌شود. برای کمک به تشخیص زودهنگام چنین اشتباهاتی، قابلیتی برای مسدود کردن تغییردهنده‌های خاص وجود دارد. اگر یک خط ورودی برای \fBpcretest\fP با رشته "< forbid " شروع شود، دنباله کاراکترهای بعدی به عنوان فهرستی از تغییردهنده‌های ممنوعه در نظر گرفته می‌شود. به عنوان مثال، در فایل‌های آزمونی که نباید از پشتیبانی UTF یا خصوصیات یونیکد استفاده کنند، این خط ظاهر می‌شود: .sp .nf < forbid 8W .fi .sp این امر تغییردهنده‌های /8 و /W را مسدود می‌کند. اگر در ادامه با آن‌ها مواجه شود، بلافاصله یک خطا رخ می‌دهد. اگر رشته کاراکتری حاوی < باشد اما > نداشته باشد، تمام تغییردهنده‌های چندکاراکتری که با < شروع می‌شوند مسدود می‌شوند. در غیر این صورت، چنین تغییردهنده‌هایی باید به طور صریح فهرست شوند، برای مثال: .sp .nf < forbid .fi .sp باید یک فاصله منفرد بین < و "forbid" وجود داشته باشد تا این قابلیت شناسایی شود. اگر وجود نداشته باشد، خط یا به عنوان درخواستی برای بارگذاری مجدد یک الگوی از پیش کامپایل‌شده تفسیر می‌شود (به بخش "ذخیره و بارگذاری مجدد الگوهای کامپایل‌شده" در زیر مراجعه کنید) یا اگر کاراکتر < دیگری وجود داشته باشد، به عنوان الگویی تفسیر می‌شود که از < به عنوان جداکننده خود استفاده می‌کند. . . .SH "خطوط داده (DATA LINES)" .rs .sp قبل از اینکه هر خط داده به \fBpcre[16|32]_exec()\fP ارسال شود، فاصله‌های خالی ابتدایی و انتهایی حذف شده و سپس برای دنباله‌های گریز \e اسکن می‌شود. برخی از این‌ها ویژگی‌های بسیار تخصصی هستند که برای بررسی برخی از ویژگی‌های پیچیده‌تر PCRE در نظر گرفته شده‌اند. اگر فقط در حال آزمایش عبارات باقاعده "عادی" هستید، احتمالاً به هیچ‌یک از این‌ها نیاز ندارید. دنباله‌های گریز زیر شناسایی می‌شوند: .sp .nf \ea زنگ اخطار (BEL, \ex07) \eb فاصله‌برگردان (backspace, \ex08) \ee گریز (escape, \ex27) \ef برگه‌بر (form feed, \ex0c) \en خط جدید (newline, \ex0a) .\" JOIN \eqdd تنظیم محدودیت PCRE_MATCH_LIMIT به dd (هر تعداد رقم) \er بازگشت به ابتدای سطر (carriage return, \ex0d) \et تب افقی (tab, \ex09) \ev تب عمودی (vertical tab, \ex0b) \ennn کاراکتر در مبنای هشت (تا 3 رقم هشت‌هشتی)؛ همیشه یک بایت مگر در صورت بزرگتر از 255 بودن در حالت UTF-8 یا ۱۶ بیتی یا ۳۲ بیتی \eo{dd...} کاراکتر در مبنای هشت (هر تعداد رقم هشت‌هشتی) \exhh بایت در مبنای شانزده (تا 2 رقم هگزادسیمال) \ex{hh...} کاراکتر در مبنای شانزده (هر تعداد رقم هگزادسیمال) .\" JOIN \eA ارسال گزینه PCRE_ANCHORED به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \eB ارسال گزینه PCRE_NOTBOL به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \eCdd فراخوانی pcre[16|32]_copy_substring() برای زیررشته dd پس از یک تطابق موفق (عدد کمتر از 32) .\" JOIN \eCname فراخوانی pcre[16|32]_copy_named_substring() برای زیررشته "name" پس از یک تطابق موفق (نام با کاراکتر غیر حرفی-عددی بعدی خاتمه می‌یابد) .\" JOIN \eC+ نمایش زیررشته‌های ضبط‌شده فعلی در زمان فراخوانی \eC- عدم ارائه تابع فراخوانی .\" JOIN \eC!n بازگرداندن 1 به جای 0 هنگام رسیدن به فراخوانی شماره n .\" JOIN \eC!n!m بازگرداندن 1 به جای 0 هنگام رسیدن به فراخوانی شماره n برای mامین بار .\" JOIN \eC*n ارسال عدد n (می‌تواند منفی باشد) به عنوان داده فراخوانی؛ این به عنوان مقدار بازگشتی فراخوانی استفاده می‌شود \eD استفاده از تابع تطبیق \fBpcre[16|32]_dfa_exec()\fP \eF فقط کوتاه‌ترین تطابق برای \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \eGdd فراخوانی pcre[16|32]_get_substring() برای زیررشته dd پس از یک تطابق موفق (عدد کمتر از 32) .\" JOIN \eGname فراخوانی pcre[16|32]_get_named_substring() برای زیررشته "name" پس از یک تطابق موفق (نام با کاراکتر غیر حرفی-عددی بعدی خاتمه می‌یابد) .\" JOIN \eJdd راه‌اندازی پشته JIT حداکثر با dd کیلوبایت (هر تعداد رقم) .\" JOIN \eL فراخوانی pcre[16|32]_get_substringlist() پس از یک تطابق موفق .\" JOIN \eM کشف حداقل تنظیمات MATCH_LIMIT و MATCH_LIMIT_RECURSION .\" JOIN \eN ارسال گزینه PCRE_NOTEMPTY به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP؛ در صورت استفاده دو بار، ارسال گزینه PCRE_NOTEMPTY_ATSTART .\" JOIN \eOdd تنظیم اندازه بردار خروجی ارسالی به \fBpcre[16|32]_exec()\fP به dd (هر تعداد رقم) .\" JOIN \eP ارسال گزینه PCRE_PARTIAL_SOFT به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP؛ در صورت استفاده دو بار، ارسال گزینه PCRE_PARTIAL_HARD .\" JOIN \eQdd تنظیم محدودیت PCRE_MATCH_LIMIT_RECURSION به dd (هر تعداد رقم) \eR ارسال گزینه PCRE_DFA_RESTART به \fBpcre[16|32]_dfa_exec()\fP \eS نمایش جزئیات فراخوانی‌های get/free حافظه در طول تطبیق .\" JOIN \eY ارسال گزینه PCRE_NO_START_OPTIMIZE به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \eZ ارسال گزینه PCRE_NOTEOL به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e? ارسال گزینه PCRE_NO_UTF[8|16|32]_CHECK به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e>dd شروع تطابق در آفست dd (اختیاری "-"؛ سپس هر تعداد رقم)؛ این آرگومان \fIstartoffset\fP را برای \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP تنظیم می‌کند .\" JOIN \e ارسال گزینه PCRE_NEWLINE_CR به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e ارسال گزینه PCRE_NEWLINE_LF به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e ارسال گزینه PCRE_NEWLINE_CRLF به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e ارسال گزینه PCRE_NEWLINE_ANYCRLF به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .\" JOIN \e ارسال گزینه PCRE_NEWLINE_ANY به \fBpcre[16|32]_exec()\fP یا \fBpcre[16|32]_dfa_exec()\fP .fi .sp استفاده از \ex{hh...} وابسته به استفاده از تغییردهنده \fB/8\fP روی الگو نیست. این دنباله همیشه شناخته می‌شود. ممکن است هر تعداد رقم هگزادسیمال درون براکت‌ها وجود داشته باشد؛ مقادیر نامعتبر پیام خطا ایجاد می‌کنند. .P توجه داشته باشید که \exhh به جای یک کاراکتر، یک بایت را در حالت UTF-8 مشخص می‌کند؛ این امر ساخت دنباله‌های نامعتبر UTF-8 را برای اهداف آزمایشی امکان‌پذیر می‌سازد. از سوی دیگر، \ex{hh} در حالت UTF-8 به عنوان یک کاراکتر UTF-8 تفسیر می‌شود، و اگر مقدار آن بزرگتر از 127 باشد بیش از یک بایت تولید می‌کند. هنگام آزمایش کتابخانه ۸ بیتی در حالتی غیر از UTF-8، دنباله \ex{hh} برای مقادیر کمتر از 256 یک بایت تولید می‌کند و برای مقادیر بزرگتر منجر به خطا می‌شود. .P در حالت UTF-16، تمام مقادیر ۴ رقمی \ex{hhhh} پذیرفته می‌شوند. این امر ساخت دنباله‌های نامعتبر UTF-16 را برای اهداف آزمایشی ممکن می‌سازد. .P در حالت UTF-32، تمام مقادیر ۴ تا ۸ رقمی \ex{...} پذیرفته می‌شوند. این امر ساخت دنباله‌های نامعتبر UTF-32 را برای اهداف آزمایشی ممکن می‌سازد. .P دنباله‌های گریزی که دنباله‌های پایان خط را مشخص می‌کنند، دقیقاً همان‌طور که نشان داده شده رشته‌های لفظی هستند. نباید بیش از یک تنظیم خط جدید در هیچ خط داده‌ای وجود داشته باشد. .P یک بک‌اسلش که به دنبال آن هر چیز دیگری بیاید، فقط آن چیز دیگر را اسکیپ می‌کند. اگر آخرین کاراکتر یک بک‌اسلش باشد، نادیده گرفته می‌شود. این امر راهی برای ارسال یک خط خالی به عنوان داده فراهم می‌کند، زیرا یک خط واقعاً خالی به ورودی داده پایان می‌دهد. .P دنباله گریز \fB\eJ\fP روشی برای تنظیم حداکثر اندازه پشته که توسط کد بهینه‌سازی Just-In-Time استفاده می‌شود فراهم می‌کند. در صورتی که بهینه‌سازی JIT استفاده نشود نادیده گرفته می‌شود. فراهم کردن پشته‌ای بزرگتر از پیش‌فرض 32K فقط برای الگوهای بسیار پیچیده ضروری است. .P اگر \eM وجود داشته باشد، \fBpcretest\fP تابع \fBpcre[16|32]_exec()\fP را چندین بار، با مقادیر مختلف در فیلدهای \fImatch_limit\fP و \fImatch_limit_recursion\fP ساختار داده \fBpcre[16|32]_extra\fP فراخوانی می‌کند، تا زمانی که حداقل اعداد را برای هر پارامتر بیابد که اجازه دهد \fBpcre[16|32]_exec()\fP بدون خطا کامل شود. از آنجا که این ویژگی خاصی از اجرای عادی و تفسیری \fBpcre[16|32]_exec()\fP را آزمایش می‌کند، استفاده از هرگونه بهینه‌سازی JIT که ممکن است توسط توصیف‌کننده \fB/S+\fP از گزینه \fB-s+\fP تنظیم شده باشد غیرفعال می‌شود. .P عدد \fImatch_limit\fP معیاری از مقدار پس‌گرد (backtracking) است که رخ می‌دهد، و بررسی آن می‌تواند آموزنده باشد. برای بیشتر تطابق‌های ساده، این عدد بسیار کوچک است، اما برای الگوهایی با تعداد بسیار زیادی از احتمالات تطبیق، می‌تواند با افزایش طول رشته هدف به سرعت بسیار بزرگ شود. عدد \fImatch_limit_recursion\fP معیاری است از اینکه چه مقدار حافظه پشته (یا در صورتی که PCRE با NO_RECURSE کامپایل شده باشد، حافظه هیپ) برای تکمیل تلاش تطبیق نیاز است. .P هنگامی که \eO استفاده می‌شود، مقدار مشخص‌شده ممکن است بیشتر یا کمتر از اندازه تنظیم‌شده توسط گزینه خط فرمان \fB-O\fP (یا پیش‌فرض 45) باشد؛ دنباله \eO تنها برای فراخوانی \fBpcre[16|32]_exec()\fP برای خطی که در آن ظاهر شده است اعمال می‌شود. .P اگر تغییردهنده \fB/P\fP روی الگو وجود داشته باشد و باعث استفاده از رابط کاربری پوششی POSIX شود، تنها دنباله‌های تنظیم گزینه که دارای اثر هستند \eB، \eN و \eZ هستند که باعث می‌شوند به ترتیب REG_NOTBOL، REG_NOTEMPTY و REG_NOTEOL به \fBregexec()\fP ارسال شوند. . . .SH "تابع تطبیق جایگزین (THE ALTERNATIVE MATCHING FUNCTION)" .rs .sp به طور پیش‌فرض، \fBpcretest\fP از تابع تطبیق استاندارد PCRE، یعنی \fBpcre[16|32]_exec()\fP برای تطبیق هر خط داده استفاده می‌کند. کتابخانه PCRE همچنین از یک تابع تطبیق جایگزین به نام \fBpcre[16|32]_dfa_exec()\fP پشتیبانی می‌کند که به شیوه‌ای متفاوت عمل کرده و دارای برخی محدودیت‌ها است. تفاوت‌های بین این دو تابع در مستندات .\" HREF \fBpcrematching\fP .\" شرح داده شده است. .P اگر یک خط داده حاوی دنباله گریز \eD باشد، یا اگر خط فرمان حاوی گزینه \fB-dfa\fP باشد، تابع تطبیق جایگزین استفاده می‌شود. این تابع تمام تطابق‌های ممکن را در یک نقطه معین پیدا می‌کند. با این حال، اگر دنباله گریز \eF در خط داده وجود داشته باشد، پس از یافتن اولین تطابق متوقف می‌شود. این همیشه کوتاه‌ترین تطابق ممکن است. . . .SH "خروجی پیش‌فرض از PCRETEST (DEFAULT OUTPUT FROM PCRETEST)" .rs .sp این بخش خروجی را زمانی که تابع تطبیق عادی، یعنی \fBpcre[16|32]_exec()\fP استفاده می‌شود توصیف می‌کند. .P هنگامی که یک تطابق با موفقیت انجام می‌شود، \fBpcretest\fP فهرست زیررشته‌های ضبط‌شده‌ای را که \fBpcre[16|32]_exec()\fP برمی‌گرداند چاپ می‌کند، که با شماره 0 برای رشته‌ای که با کل الگو تطبیق یافته است آغاز می‌شود. در غیر این صورت، در صورتی که مقدار بازگشتی PCRE_ERROR_NOMATCH باشد عبارت "No match" را چاپ می‌کند، و هنگامی که \fBpcre[16|32]_exec()\fP مقدار PCRE_ERROR_PARTIAL را بازگرداند عبارت "Partial match:" به همراه زیررشته‌ای که به طور جزئی تطبیق یافته است را نمایش می‌دهد. (توجه داشته باشید که این کل زیررشته‌ای است که در طول تطابق جزئی بررسی شده است؛ در صورتی که یک بررسی به عقب، \eK، \eb یا \eB درگیر بوده باشد، ممکن است شامل کاراکترهایی قبل از شروع واقعی تطابق باشد). برای هر بازگشت دیگر، \fBpcretest\fP شماره خطای منفی PCRE و یک عبارت توصیفی کوتاه را چاپ می‌کند. اگر خطا ناشی از شکست در بررسی رشته UTF باشد، آفست ابتدای کاراکتر ناموفق و کد دلیل نیز چاپ می‌شوند، مشروط بر اینکه اندازه بردار خروجی حداقل دو باشد. در اینجا نمونه‌ای از یک اجرای تعاملی \fBpcretest\fP آورده شده است: .sp .nf $ pcretest PCRE version 8.13 2011-04-30 re> /^abc(\ed+)/ data> abc123 0: abc123 1: 123 data> xyz No match .fi .sp زیررشته‌های ضبط‌کننده‌ای که مقداردهی نشده‌اند و با زیررشته‌ای که مقداردهی شده است دنبال نمی‌شوند، توسط \fBpcre[16|32]_exec()\fP بازگردانده نمی‌شوند و توسط \fBpcretest\fP نمایش داده نخواهند شد. در مثال زیر، دو زیررشته ضبط‌کننده وجود دارد، اما هنگامی که اولین خط داده تطبیق می‌یابد، زیررشته دوم که مقداردهی نشده است نشان داده نمی‌شود. یک زیررشته مقداردهی‌نشده "داخلی" همانند خط دوم داده به عنوان "" نمایش داده می‌شود: .sp .nf re> /(a)|(b)/ data> a 0: a 1: a data> b 0: b 1: 2: b .fi .sp اگر رشته‌ها حاوی هرگونه کاراکتر غیرقابل چاپ باشند، در صورتی که مقدار کمتر از 256 باشد و حالت UTF تنظیم نشده باشد، به صورت دنباله‌های گریز \exhh نمایش می‌یابند. در غیر این صورت به عنوان دنباله‌های گریز \ex{hh...} چاپ می‌شوند. برای تعریف کاراکترهای غیرقابل چاپ به ادامه مراجعه کنید. اگر الگو دارای تغییردهنده \fB/+\fP باشد، خروجی برای زیررشته 0 با باقیمانده رشته هدف دنبال می‌شود که با "0+" مشخص می‌شود، به این صورت: .sp .nf re> /cat/+ data> cataract 0: cat 0+ aract .fi .sp اگر الگو دارای تغییردهنده \fB/g\fP یا \fB/G\fP باشد، نتایج تلاش‌های متوالی برای تطابق به ترتیب چاپ می‌شوند، مانند این: .sp .nf re> /\eBi(\ew\ew)/g data> Mississippi 0: iss 1: ss 0: iss 1: ss 0: ipp 1: pp .fi .sp عبارت "No match" تنها در صورتی چاپ می‌شود که اولین تلاش برای تطابق ناموفق باشد. در اینجا نمونه‌ای از یک پیام شکست آورده شده است (آفست 4 که توسط \e>4 مشخص شده است فراتر از انتهای رشته هدف است): .sp .nf re> /xyz/ data> xyz\e>4 Error -24 (bad offset value) .fi .P اگر هر یک از دنباله‌های \fB\eC\fP، \fB\eG\fP یا \fB\eL\fP در یک خط داده که با موفقیت تطبیق یافته است وجود داشته باشد، زیررشته‌های استخراج‌شده توسط توابع کمکی به جای دونقطه با C، G یا L پس از شماره رشته در خروجی چاپ می‌شوند. این علاوه بر فهرست کامل عادی است. طول رشته (یعنی مقدار برگشتی از تابع استخراج) در پرانتز پس از هر رشته برای \fB\eC\fP و \fB\eG\fP آورده می‌شود. .P توجه داشته باشید در حالی که الگوها می‌توانند روی چندین خط ادامه یابند (یک اعلان ساده ">" برای ادامه‌ها استفاده می‌شود)، خطوط داده نمی‌توانند چنین باشند. با این حال خطوط جدید می‌توانند با استفاده از دنباله گریز \en (یا \er، \er\en و غیره، بسته به تنظیم دنباله خط جدید) در داده‌ها گنجانده شوند. . . .SH "خروجی از تابع تطبیق جایگزین (OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION)" .rs .sp هنگامی که تابع تطبیق جایگزین، یعنی \fBpcre[16|32]_dfa_exec()\fP استفاده می‌شود (از طریق دنباله گریز \eD یا گزینه خط فرمان \fB-dfa\fP)، خروجی شامل فهرستی از تمام تطابق‌هایی است که از اولین نقطه در رشته هدف که حداقل یک تطابق در آن وجود دارد شروع می‌شوند. برای مثال: .sp .nf re> /(tang|tangerine|tan)/ data> yellow tangerine\eD 0: tangerine 1: tang 2: tan .fi .sp (استفاده از تابع تطبیق عادی روی این داده تنها "tang" را پیدا می‌کند). طولانی‌ترین رشته تطبیق‌یافته همیشه در ابتدا آورده می‌شود (و شماره صفر به آن اختصاص می‌یابد). پس از یک بازگشت PCRE_ERROR_PARTIAL، خروجی عبارت "Partial match:" به همراه زیررشته‌ای است که به طور جزئی تطبیق یافته است. (توجه داشته باشید که این کل زیررشته‌ای است که در طول تطابق جزئی بررسی شده است؛ در صورتی که یک بررسی به عقب، \eK، \eb یا \eB درگیر بوده باشد، ممکن است شامل کاراکترهایی قبل از شروع واقعی تطابق باشد). .P اگر \fB/g\fP روی الگو وجود داشته باشد، جستجو برای تطابق‌های بیشتر در انتهای طولانی‌ترین تطابق از سر گرفته می‌شود. برای مثال: .sp .nf re> /(tang|tangerine|tan)/g data> yellow tangerine and tangy sultana\eD 0: tangerine 1: tang 2: tan 0: tang 1: tan 0: tan .fi .sp از آنجا که تابع تطبیق از ضبط زیررشته پشتیبانی نمی‌کند، دنباله‌های گریزی که مربوط به زیررشته‌های ضبط‌شده هستند کاربردی ندارند. . . .SH "شروع مجدد پس از تطابق جزئی (RESTARTING AFTER A PARTIAL MATCH)" .rs .sp هنگامی که تابع تطبیق جایگزین بازگشت PCRE_ERROR_PARTIAL را ارائه داده است، که نشان می‌دهد رشته هدف به طور جزئی با الگو تطبیق یافته است، می‌توانید با استفاده از دنباله گریز \eR تطابق را با داده‌های هدف اضافی از سر بگیرید. برای مثال: .sp .nf re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ data> 23ja\eP\eD Partial match: 23ja data> n05\eR\eD 0: n05 .fi .sp برای اطلاعات بیشتر درباره تطابق جزئی، به مستندات .\" HREF \fBpcrepartial\fP .\" مراجعه فرمایید. . . .SH "فراخوانی‌ها (CALLOUTS)" .rs .sp اگر الگو حاوی هرگونه درخواست فراخوانی باشد، تابع فراخوانی \fBpcretest\fP در طول تطبیق فراخوانی می‌شود. این با هر دو تابع تطبیق کار می‌کند. به طور پیش‌فرض، تابع فراخوانی‌شده شماره فراخوانی، موقعیت‌های شروع و فعلی در متن در زمان فراخوانی، و آیتم بعدی الگو را که باید آزمایش شود نمایش می‌دهد. برای مثال: .sp .nf --->pqrabcdef 0 ^ ^ \ed .fi .sp این خروجی نشان می‌دهد که فراخوانی شماره 0 برای تلاش تطبیقی رخ داده است که از چهارمین کاراکتر رشته هدف شروع شده، زمانی که نشانگر در هفتمین کاراکتر داده بود، و زمانی که آیتم بعدی الگو \ed بود. اگر موقعیت‌های شروع و فعلی یکسان باشند، تنها یک علامت هشتک (^) چاپ می‌شود. .P فراخوانی‌های شماره‌گذاری‌شده به عنوان 255 به عنوان فراخوانی‌های خودکار فرض می‌شوند که در نتیجه تغییردهنده الگوی \fB/C\fP درج شده‌اند. در این حالت، به جای نمایش شماره فراخوانی، آفست در الگو با علامت مثبت قبل از آن نمایش داده می‌شود. برای مثال: .sp .nf re> /\ed?[A-E]\e*/C data> E* --->E* +0 ^ \ed? +3 ^ [A-E] +8 ^^ \e* +10 ^ ^ 0: E* .fi .sp اگر الگویی حاوی آیتم‌های (*MARK) باشد، هر زمان که تغییری در جدیدترین علامت به تابع فراخوانی ارسال شود یک خط اضافی در خروجی نمایش داده می‌شود. برای مثال: .sp .nf re> /a(*MARK:X)bc/C data> abc --->abc +0 ^ a +1 ^^ (*MARK:X) +10 ^^ b Latest Mark: X +11 ^ ^ c +12 ^ ^ 0: abc .fi .sp علامت بین تطبیق "a" و "b" تغییر می‌کند، اما برای بقیه تطابق یکسان باقی می‌ماند، بنابراین خروجی دیگری نمایش داده نمی‌شود. اگر در نتیجه پس‌گرد، علامت به حالت تنظیم‌نشده بازگردد، متن "" در خروجی چاپ می‌شود. .P تابع فراخوانی در \fBpcretest\fP به طور پیش‌فرض صفر برمی‌گرداند (تطبیق را ادامه بده)، اما شما می‌توانید از یک آیتم \eC در یک خط داده (همان‌طور که در بالا شرح داده شد) برای تغییر این مورد و سایر پارامترهای فراخوانی استفاده کنید. .P درج فراخوانی‌ها می‌تواند هنگام استفاده از \fBpcretest\fP برای بررسی عبارات باقاعده پیچیده مفید باشد. برای اطلاعات بیشتر درباره فراخوانی‌ها، به مستندات .\" HREF \fBpcrecallout\fP .\" مراجعه فرمایید. . . .SH "کاراکترهای غیرقابل چاپ (NON-PRINTING CHARACTERS)" .rs .sp هنگامی که \fBpcretest\fP متنی را در نسخه کامپایل‌شده یک الگو چاپ می‌کند، بایت‌هایی غیر از 32-126 همیشه به عنوان کاراکترهای غیرقابل چاپ در نظر گرفته می‌شوند و بنابراین به عنوان دنباله‌های گریز در مبنای شانزده نمایش داده می‌شوند. .P هنگامی که \fBpcretest\fP متنی را چاپ می‌کند که بخشی تطبیق‌یافته از یک رشته هدف است، به همان روش عمل می‌کند، مگر اینکه محلی‌سازی متفاوتی برای الگو تنظیم شده باشد (با استفاده از تغییردهنده \fB/L\fP). در این حالت، از تابع \fBisprint()\fP برای تشخیص کاراکترهای چاپی و غیرقابل چاپ استفاده می‌شود. . . .SH "ذخیره و بارگذاری مجدد الگوهای کامپایل‌شده (SAVING AND RELOADING COMPILED PATTERNS)" .rs .sp امکانات شرح داده شده در این بخش زمانی که از رابط POSIX برای PCRE استفاده می‌شود، یعنی هنگامی که تغییردهنده الگوی \fB/P\fP مشخص شده باشد، در دسترس نیستند. .P هنگامی که رابط POSIX در حال استفاده نیست، می‌توانید با قرار دادن > و یک نام فایل پس از تغییردهنده‌ها، باعث شوید \fBpcretest\fP یک الگوی کامپایل‌شده را در یک فایل بنویسد. برای مثال: .sp .nf /pattern/im >/some/file .fi .sp برای بحث و گفتگو درباره ذخیره و استفاده مجدد از الگوهای کامپایل‌شده، به مستندات .\" HREF \fBpcreprecompile\fP .\" مراجعه نمایید. توجه داشته باشید که اگر الگو با موفقیت با بهینه‌سازی JIT مطالعه شده باشد، داده‌های JIT قابل ذخیره نیستند. .P داده‌هایی که نوشته می‌شوند باینری (دودویی) هستند. هشت بایت اول طول داده‌های الگوی کامپایل‌شده و به دنبال آن طول داده‌های مطالعه اختیاری است، که هر یک به صورت چهار بایت با ترتیب big-endian (بایتی با بیشترین ارزش در ابتدا) نوشته می‌شوند. اگر داده مطالعه‌ای وجود نداشته باشد (یا الگو مطالعه نشده باشد یا مطالعه داده‌ای بازنگردانده باشد)، طول دوم صفر است. به دنبال طول‌ها، یک کپی دقیق از الگوی کامپایل‌شده می‌آید. اگر داده‌های مطالعه اضافی وجود داشته باشد، این داده‌ها (به استثنای هرگونه داده JIT) بلافاصله پس از الگوی کامپایل‌شده قرار می‌گیرند. پس از نوشتن فایل، \fBpcretest\fP انتظار دارد یک الگوی جدید را بخواند. .P یک الگوی ذخیره‌شده را می‌توان با تعیین < و یک نام فایل به جای یک الگو، مجدداً در \fBpcretest\fP بارگذاری کرد. نباید هیچ فاصله‌ای بین < و نام فایل وجود داشته باشد، و نام فایل نباید شامل کاراکتر < باشد، زیرا در غیر این صورت \fBpcretest\fP خط را به عنوان الگویی که با کاراکترهای < احاطه شده است تفسیر می‌کند. برای مثال: .sp .nf re>