PCREGREP(1) General Commands Manual PCREGREP(1)

pcregrep - ابزار جستجوی متنی مبتنی بر عبارات باقاعده سازگار با پرل

pcregrep [گزینه‌ها] [گزینه‌های طولانی] [الگو] [مسیر۱ مسیر۲ ...]

دستور pcregrep همانند سایر دستورات grep فایل‌ها را برای الگوهای نویسه‌ای (کاراکتری) جستجو می‌کند، اما از کتابخانه عبارت‌های باقاعده PCRE برای پشتیبانی از الگوهای سازگار با عبارت‌های باقاعده پرل ۵ (Perl 5) بهره می‌برد. برای خلاصه‌ای مرجع و سریع از نحو نگارش الگوها، به pcresyntax(3) و برای شرح کامل نحو و معناشناسی عبارت‌های باقاعده‌ای که PCRE پشتیبانی می‌کند، به pcrepattern(3) مراجعه کنید.

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

pcregrep Thursday /etc/motd

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

نخستین آرگومانی که پس از تنظیمات گزینه‌ها می‌آید، در صورتی که هیچ‌یک از گزینه‌های -e یا -f وجود نداشته باشد، به عنوان تک‌الگوی مورد تطبیق در نظر گرفته می‌شود. برعکس، هنگامی که از یک یا هر دوی این گزینه‌ها برای تعیین الگوها استفاده می‌شود، با تمام آرگومان‌ها به عنوان نام مسیر رفتار می‌شود. حداقل یکی از گزینه‌های -e، -f یا یک آرگومان الگو باید ارائه شود.

اگر هیچ فایلی مشخص نشود، pcregrep ورودی استاندارد را می‌خواند. ورودی استاندارد همچنین می‌تواند با نامی متشکل از یک خط تیره منفرد ارجاع داده شود. برای مثال:

pcregrep some-pattern /file1 - /file3

به‌طور پیش‌فرض، هر خطی که با یک الگو مطابقت داشته باشد در خروجی استاندارد کپی می‌شود، و اگر بیش از یک فایل وجود داشته باشد، نام فایل در ابتدای هر خط ظاهر شده و به دنبال آن یک دونقطه (:) قرار می‌گیرد. با این حال، گزینه‌هایی وجود دارند که می‌توانند نحوه رفتار pcregrep را تغییر دهند. به‌ویژه، گزینه -M جستجو برای الگوهایی را که فراتر از مرزهای خط گسترش می‌یابند امکان‌پذیر می‌سازد. آنچه که مرز خط را تعریف می‌کند توسط گزینه -N (--newline) کنترل می‌شود.

مقدار حافظه مورد استفاده برای بافر کردن فایل‌هایی که اسکن می‌شوند، توسط پارامتری کنترل می‌شود که با گزینه --buffer-size قابل تنظیم است. مقدار پیش‌فرض این پارامتر هنگام ساخت pcregrep مشخص می‌شود و پیش‌فرض اولیه آن 20K است. یک بلوک حافظه به اندازه سه برابر این مقدار استفاده می‌شود (برای امکان بافر کردن خطوط «قبل» و «بعد»). اگر یک خط از بافر سرریز کند، خطایی رخ می‌دهد.

طول الگوها نمی‌تواند بیشتر از 8K یا مقدار بایت‌های BUFSIZ (هر کدام که بزرگ‌تر باشد) باشد. مقدار BUFSIZ در <stdio.h> تعریف شده است. هنگامی که بیش از یک الگو وجود دارد (که با استفاده از -e و/یا -f مشخص شده‌اند)، هر الگو به همان ترتیبی که تعریف شده است بر روی هر خط اعمال می‌شود، به جز اینکه تمام الگوهای -e پیش از الگوهای -f آزمایش می‌شوند.

به‌طور پیش‌فرض، به محض اینکه یک الگو با خطی مطابقت پیدا کند، الگوهای بعدی در نظر گرفته نمی‌شوند. با این حال، اگر از --colour (یا --color) برای رنگی کردن زیررشته‌های منطبق استفاده شود، یا اگر از --only-matching، --file-offsets یا --line-offsets برای نمایش تنها بخشی از خط که مطابقت داشته (خواه به صورت متنی یا به عنوان یک آفست) استفاده شود، اسکن بلافاصله پس از بخش منطبق از سر گرفته می‌شود تا تطابق‌های بیشتری در همان خط پیدا شوند. اگر چندین الگو وجود داشته باشد، همه آنها بر روی بخش باقیمانده خط آزمایش می‌شوند، اما الگوهایی که پس از الگوی منطبق قرار دارند، روی بخش قبلی خط آزمایش نخواهند شد.

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

الگوهایی که می‌توانند با یک رشته خالی مطابقت داشته باشند پذیرفته می‌شوند، اما تطابق‌های رشته خالی هرگز شناسایی نمی‌شوند. یک مثال، الگوی "(super)?(man)?" است که در آن تمام مؤلفه‌ها اختیاری هستند. این الگو تمام رخدادهای هر دو عبارت "super" و "man" را پیدا می‌کند؛ خروجی این الگو با تطبیق با "super|man" هنگامی که تنها زیررشته‌های منطبق نمایش داده می‌شوند، متفاوت است.

اگر متغیر محیطی LC_ALL یا LC_CTYPE مقداردهی شده باشد، pcregrep هنگام فراخوانی کتابخانه PCRE از این مقدار برای تنظیم یک محلی (locale) استفاده می‌کند. گزینه --locale می‌تواند برای بازنویسی این مقدار به کار رود.

امکان کامپایل pcregrep به‌گونه‌ای وجود دارد که از libz یا libbz2 برای خواندن فایل‌هایی که نام آنها به ترتیب به .gz یا .bz2 ختم می‌شود استفاده کند. با اجرای برنامه همراه با گزینه --help می‌توانید دریابید که آیا فایل اجرایی (باینری) شما از یک یا هر دوی این نوع فایل‌ها پشتیبانی می‌کند یا خیر. اگر پشتیبانی مناسب وجود نداشته باشد، با فایل‌ها به عنوان متن ساده رفتار می‌شود. با ورودی استاندارد همواره به همین شیوه رفتار می‌شود.

به‌طور پیش‌فرض، فایلی که در میان ۱۰۲۴ بایت اول خود حاوی یک بایت صفر دودویی (null byte) باشد، به عنوان یک فایل دودویی شناسایی شده و به صورت ویژه پردازش می‌شود. (GNU grep نیز فایل‌های دودویی را به همین شیوه شناسایی می‌کند.) برای روش‌های تغییر نحوه مدیریت فایل‌های دودویی، به گزینه --binary-files مراجعه کنید.

ترتیبی که برخی از گزینه‌ها ظاهر می‌شوند می‌تواند بر خروجی تأثیر بگذارد. برای مثال، هر دو گزینه -h و -l بر چاپ نام فایل‌ها تأثیر می‌گذارند. هر کدام که در خط فرمان دیرتر بیاید، گزینه‌ای خواهد بود که اعمال می‌شود. به طور مشابه، به جز مواردی که در زیر قید شده است، اگر گزینه‌ای دو بار داده شود، تنظیم متأخرتر اعمال خواهد شد. مقادیر عددی گزینه‌ها می‌توانند با کاراکترهای K یا M دنبال شوند تا به ترتیب ضرب در ۱۰۲۴ یا ۱۰۲۴*۱۰۲۴ را مشخص کنند.

--
این گزینه فهرست گزینه‌ها را خاتمه می‌دهد. در صورتی که مورد بعدی در خط فرمان با یک خط تیره آغاز شود اما گزینه نباشد، مفید است. این کار پردازش الگوها و نام فایل‌هایی را که با خط تیره شروع می‌شوند امکان‌پذیر می‌سازد.
چاپ تعداد خط از متن زمینه پس از هر خط منطبق. اگر نام فایل‌ها و/یا شماره خطوط در حال چاپ باشند، به جای دونقطه از یک جداکننده خط تیره برای خطوط زمینه استفاده می‌شود. خطی حاوی "--" بین هر گروه از خطوط چاپ می‌شود، مگر اینکه آنها در واقع در فایل ورودی به صورت متوالی و پیوسته باشند. انتظار می‌رود مقدار تعداد نسبتاً کوچک باشد. با این حال، pcregrep تضمین می‌کند که تا 8K از متن پسین برای خروجی زمینه در دسترس باشد.
با فایل‌های دودویی مانند متن رفتار شود. این معادل با --binary-files=text است.
چاپ تعداد خط از متن زمینه پیش از هر خط منطبق. اگر نام فایل‌ها و/یا شماره خطوط در حال چاپ باشند، به جای دونقطه از یک جداکننده خط تیره برای خطوط زمینه استفاده می‌شود. خطی حاوی "--" بین هر گروه از خطوط چاپ می‌شود، مگر اینکه آنها در واقع در فایل ورودی به صورت متوالی و پیوسته باشند. انتظار می‌رود مقدار تعداد نسبتاً کوچک باشد. با این حال، pcregrep تضمین می‌کند که تا 8K از متن پیشین برای خروجی زمینه در دسترس باشد.
مشخص کردن نحوه پردازش فایل‌های دودویی. اگر کلمه "binary" باشد (پیش‌فرض)، تطبیق الگو روی فایل‌های دودویی انجام می‌شود، اما در صورت موفقیت تطابق، تنها خروجی عبارت "Binary file <name> matches" خواهد بود. اگر کلمه "text" باشد، که معادل گزینه -a یا --text است، با فایل‌های دودویی به همان شیوه سایر فایل‌ها رفتار می‌شود. در این حالت، هنگامی که تطابق موفق شود، ممکن است خروجی حاوی داده‌های نامفهوم دودویی باشد که ارسال آن به یک ترمینال می‌تواند اثرات ناخوشایندی داشته باشد. اگر کلمه "without-match" باشد، که معادل گزینه -I است، فایل‌های دودویی اصلاً پردازش نمی‌شوند و فرض می‌شود که مورد نظر کاربر نیستند.
تنظیم پارامتری که مقدار حافظه مورد استفاده برای بافر کردن فایل‌های در حال اسکن را کنترل می‌کند.
چاپ تعداد خط از متن زمینه هم پیش از و هم پس از هر خط منطبق. این معادل تنظیم همزمان -A و -B بر روی مقداری یکسان است.
خطوط منفرد را از فایل‌های در حال اسکن چاپ نکن؛ در عوض تعداد خطوطی را چاپ کن که در غیر این صورت نمایش داده می‌شدند. اگر هیچ خطی انتخاب نشود، عدد صفر چاپ می‌شود. اگر چندین فایل در حال اسکن باشند، یک شمارش برای هر یک از آنها چاپ می‌شود. با این حال، اگر از گزینه --files-with-matches نیز استفاده شود، تنها فایل‌هایی فهرست می‌شوند که تعداد تطابق آنها بزرگ‌تر از صفر باشد. هنگامی که از -c استفاده می‌شود، گزینه‌های -A، -B و -C نادیده گرفته می‌شوند.
اگر این گزینه بدون داده‌ای مشخص شود، معادل "--colour=auto" است. اگر داده مورد نیاز باشد، باید در همان بخش خط فرمان و با یک علامت مساوی جدا شود.
این گزینه شرایطی را مشخص می‌کند که در آن بخش‌هایی از خط که با الگو مطابقت دارند باید در خروجی رنگی شوند. به‌طور پیش‌فرض، خروجی رنگی نیست. مقدار (که اختیاری است، بالا را ببینید) می‌تواند "never"، "always" یا "auto" باشد. در حالت آخر، رنگ‌آمیزی تنها در صورتی رخ می‌دهد که خروجی استاندارد به یک ترمینال متصل باشد. هنگامی که رنگ‌آمیزی فعال باشد منابع بیشتری مصرف می‌شود، زیرا pcregrep برای رنگ‌آمیزی همه آنها باید به جای فقط یک مورد، تمام تطابق‌های ممکن را در یک خط جستجو کند.

رنگ مورد استفاده را می‌توان با مقداردهی به متغیر محیطی PCREGREP_COLOUR یا PCREGREP_COLOR مشخص کرد. مقدار این متغیر باید رشته‌ای از دو عدد باشد که با یک سمی‌کولن از هم جدا شده‌اند. این اعداد مستقیماً درون رشته کنترلی تنظیم رنگ ترمینال کپی می‌شوند، بنابراین اطمینان از معنادار بودن آنها بر عهده شماست. اگر هیچ‌یک از متغیرهای محیطی مقداردهی نشده باشند، پیش‌فرض "1;31" است که رنگ قرمز را مشخص می‌کند.

اگر یک مسیر ورودی یک فایل معمولی یا یک دایرکتوری نباشد، "اقدام" نحوه پردازش آن را مشخص می‌کند. مقادیر معتبر "read" (پیش‌فرض) یا "skip" (صرف‌نظر کردن بی‌صدا از مسیر) هستند.
اگر یک مسیر ورودی یک دایرکتوری باشد، "اقدام" نحوه پردازش آن را مشخص می‌کند. مقادیر معتبر عبارتند از "read" (پیش‌فرض در محیط‌های غیرویندوزی، برای سازگاری با GNU grep)، "recurse" (معادل با گزینه -r)، یا "skip" (صرف‌نظر کردن بی‌صدا از مسیر، پیش‌فرض در محیط‌های ویندوزی). در حالت "read"، با دایرکتوری‌ها طوری رفتار می‌شود که گویی فایل‌های معمولی هستند و خوانده می‌شوند. در برخی سیستم‌عامل‌ها اثر خواندن دایرکتوری به این شکل، پایان فوری فایل (EOF) است؛ در برخی دیگر ممکن است باعث بروز خطا شود.
مشخص کردن الگویی برای تطبیق. این گزینه می‌تواند چندین بار برای تعیین چندین الگو استفاده شود. همچنین می‌تواند روشی برای تعیین یک الگوی منفرد باشد که با خط تیره آغاز می‌شود. هنگامی که از -e استفاده می‌شود، هیچ الگویی به عنوان آرگومان از خط فرمان گرفته نمی‌شود؛ با تمام آرگومان‌ها به عنوان نام فایل رفتار می‌شود. هیچ محدودیتی برای تعداد الگوها وجود ندارد. آنها به ترتیبی که تعریف شده‌اند بر روی هر خط اعمال می‌شوند تا زمانی که یکی مطابقت پیدا کند.

اگر -f همراه با -e استفاده شود، مستقل از ترتیبی که این گزینه‌ها مشخص شده‌اند، ابتدا الگوهای خط فرمان تطبیق داده می‌شوند و به دنبال آن الگوهای فایل(ها). توجه داشته باشید که استفاده مکرر از -e همانند یک الگوی منفرد با گزینه‌های جایگزین نیست. برای مثال، X|Y اولین نویسه‌ای را در یک خط پیدا می‌کند که X یا Y باشد، در حالی که اگر دو الگو به طور جداگانه داده شوند و X اول باشد، pcregrep در صورت وجود X آن را پیدا می‌کند، حتی اگر پس از Y در خط آمده باشد. این دستور تنها در صورتی Y را پیدا می‌کند که هیچ Xای در خط نباشد. این موضوع تنها در صورتی اهمیت دارد که از -o یا --colo(u)r برای نمایش بخش(های) منطبق خط استفاده کنید.

فایل‌هایی (نه دایرکتوری‌ها) که نام آنها با الگو مطابقت داشته باشد بدون پردازش نادیده گرفته می‌شوند. این امر برای تمام فایل‌ها اعمال می‌شود، خواه در خط فرمان فهرست شده باشند، از --file-list به دست آمده باشند یا با اسکن یک دایرکتوری. الگو یک عبارت باقاعده PCRE است و در برابر آخرین مؤلفه نام فایل تطبیق داده می‌شود، نه کل مسیر. گزینه‌های -F، -w و -x برای این الگو اعمال نمی‌شوند. این گزینه را می‌توان به هر تعداد بار برای تعیین چندین الگو مشخص کرد. اگر یک نام فایل هم با یک الگوی --include و هم با یک الگوی --exclude مطابقت داشته باشد، مستثنی می‌شود (نادیده گرفته می‌شود). هیچ فرم کوتاهی برای این گزینه وجود ندارد.
با هر خط غیرخالی فایل به عنوان داده‌ای برای یک گزینه --exclude رفتار شود. آنچه که هنگام خواندن فایل یک خط جدید را تشکیل می‌دهد، پیش‌فرض سیستم‌عامل است. گزینه --newline هیچ تأثیری بر این گزینه ندارد. این گزینه می‌تواند بیش از یک بار مشخص شود تا چندین فایل برای خواندن تعیین گردند.
دایرکتوری‌هایی که نام آنها با الگو مطابقت دارد، صرف‌نظر از مقدار تنظیم گزینه --recursive، بدون پردازش نادیده گرفته می‌شوند. این امر برای تمام دایرکتوری‌ها اعمال می‌شود، خواه در خط فرمان فهرست شده باشند، از --file-list به دست آمده باشند یا با اسکن یک دایرکتوری والد پیدا شوند. الگو یک عبارت باقاعده PCRE است و در برابر آخرین مؤلفه نام دایرکتوری تطبیق داده می‌شود، نه کل مسیر. گزینه‌های -F، -w و -x برای این الگو اعمال نمی‌شوند. این گزینه می‌تواند به هر تعداد بار برای تعیین بیش از یک الگو مشخص شود. اگر یک دایرکتوری هم با یک الگوی --include-dir و هم با یک الگوی --exclude-dir مطابقت داشته باشد، مستثنی می‌شود. هیچ فرم کوتاهی برای این گزینه وجود ندارد.
تفسیر هر الگوی تطبیق داده به عنوان فهرستی از رشته‌های ثابت که با خطوط جدید از هم جدا شده‌اند، به جای یک عبارت باقاعده. آنچه برای این منظور یک خط جدید را تشکیل می‌دهد توسط گزینه --newline کنترل می‌شود. گزینه‌های -w (تطبیق به عنوان یک کلمه) و -x (تطبیق کل خط) می‌توانند همراه با -F استفاده شوند. آنها بر روی هر یک از رشته‌های ثابت اعمال می‌شوند. یک خط در صورتی انتخاب می‌شود که هر یک از رشته‌های ثابت در آن یافت شود (مشروط به -w یا -x در صورت وجود). این گزینه تنها برای الگوهایی اعمال می‌شود که در برابر محتوای فایل‌ها تطبیق داده می‌شوند؛ برای الگوهای مشخص‌شده توسط هر یک از گزینه‌های --include یا --exclude اعمال نمی‌شود.
خواندن الگوها از فایل، هر الگو در یک خط، و تطبیق آنها در برابر هر خط ورودی. آنچه که هنگام خواندن فایل یک خط جدید را تشکیل می‌دهد پیش‌فرض سیستم‌عامل است. گزینه --newline هیچ تأثیری بر این گزینه ندارد. فاصله‌های سفید انتهایی از هر خط حذف شده و خطوط خالی نادیده گرفته می‌شوند. یک فایل خالی فاقد هرگونه الگو است و بنابراین با هیچ‌چیز مطابقت ندارد. همچنین به توضیحات مربوط به چندین الگو در برابر یک الگوی منفرد با گزینه‌های جایگزین در شرح -e در بالا مراجعه کنید.

اگر این گزینه بیش از یک بار داده شود، تمام فایل‌های مشخص‌شده خوانده می‌شوند. اگر هر یک از الگوها با یک خط داده مطابقت داشته باشد، آن خط در خروجی چاپ می‌شود. نام فایل می‌تواند به صورت "-" داده شود تا به ورودی استاندارد ارجاع دهد. هنگامی که از -f استفاده می‌شود، الگوهای مشخص‌شده در خط فرمان با استفاده از -e نیز می‌توانند حضور داشته باشند؛ آنها پیش از الگوهای فایل آزمایش می‌شوند. با این حال، هیچ الگوی دیگری از خط فرمان گرفته نمی‌شود؛ با تمام آرگومان‌ها به عنوان نام مسیرهای مورد جستجو رفتار می‌شود.

خواندن فهرستی از فایل‌ها و/یا دایرکتوری‌هایی که باید اسکن شوند از فایل داده‌شده، هر مسیر در یک خط. فاصله‌های سفید انتهایی از هر خط حذف شده و خطوط خالی نادیده گرفته می‌شوند. این مسیرها پیش از هر مسیری که در خط فرمان فهرست شده است پردازش می‌شوند. نام فایل می‌تواند به صورت "-" داده شود تا به ورودی استاندارد ارجاع دهد. اگر هر دو گزینه --file و --file-list به صورت "-" مشخص شوند، الگوها ابتدا خوانده می‌شوند. این تنها زمانی کاربرد دارد که ورودی استاندارد یک ترمینال باشد که خطوط بعدی (فهرست فایل‌ها) پس از نشانه پایان فایل (EOF) از آن قابل خواندن باشند. اگر این گزینه بیش از یک بار داده شود، تمام فایل‌های مشخص‌شده خوانده می‌شوند.
به جای نمایش خطوط یا بخش‌هایی از خطوط که مطابقت دارند، هر تطابق به صورت یک آفست از ابتدای فایل و یک طول، که با کاما از هم جدا شده‌اند نشان داده شود. در این حالت، هیچ زمینه‌ای نمایش داده نمی‌شود. به این معنی که گزینه‌های -A، -B و -C نادیده گرفته می‌شوند. اگر بیش از یک تطابق در یک خط وجود داشته باشد، هر یک از آنها به طور جداگانه نمایش داده می‌شود. این گزینه با --line-offsets و --only-matching مانعة‌الجمع است.
هنگام جستجوی یک تک‌فایل، درج نام فایل در ابتدای خطوط خروجی را اجباری کن. به‌طور پیش‌فرض در این حالت نام فایل نمایش داده نمی‌شود. برای خطوط منطبق، نام فایل با یک دونقطه (:) دنبال می‌شود؛ برای خطوط زمینه، از یک خط تیره جداکننده استفاده می‌شود. اگر شماره خط نیز چاپ شود، پس از نام فایل قرار می‌گیرد.
هنگام جستجوی چندین فایل، از چاپ نام فایل‌ها در خروجی جلوگیری کن. به‌طور پیش‌فرض هنگامی که چندین فایل جستجو می‌شوند، نام فایل‌ها نمایش داده می‌شود. برای خطوط منطبق، نام فایل با یک دونقطه دنبال می‌شود؛ برای خطوط زمینه، از جداکننده خط تیره استفاده می‌شود. اگر شماره خط نیز چاپ شود، پس از نام فایل قرار می‌گیرد.
چاپ یک پیام راهنما که جزئیات مختصری درباره گزینه‌های دستور و پشتیبانی از انواع فایل ارائه می‌دهد، و سپس خروج. هر چیز دیگری در خط فرمان نادیده گرفته می‌شود.
با فایل‌های دودویی طوری رفتار کن که گویی هرگز مطابقت ندارند. این معادل با --binary-files=without-match است.
نادیده گرفتن تمایز حروف کوچک و بزرگ در طول مقایسه‌ها.
اگر هرگونه الگوی --include مشخص شده باشد، تنها فایل‌هایی پردازش می‌شوند که با یکی از الگوها مطابقت داشته باشند (و با یک الگوی --exclude مطابقت نداشته باشند). این گزینه روی دایرکتوری‌ها تأثیری ندارد، اما برای تمام فایل‌ها اعمال می‌شود، خواه در خط فرمان فهرست شده باشند، از --file-list به دست آمده باشند یا با اسکن یک دایرکتوری پیدا شوند. الگو یک عبارت باقاعده PCRE است و در برابر آخرین مؤلفه نام فایل تطبیق داده می‌شود، نه کل مسیر. گزینه‌های -F، -w و -x برای این الگو اعمال نمی‌شوند. این گزینه را می‌توان به هر تعداد بار مشخص کرد. اگر نام یک فایل هم با یک الگوی --include و هم با یک الگوی --exclude مطابقت داشته باشد، مستثنی می‌شود. هیچ فرم کوتاهی برای این گزینه وجود ندارد.
با هر خط غیرخالی فایل به عنوان داده‌ای برای یک گزینه --include رفتار شود. آنچه که برای این منظور یک خط جدید را تشکیل می‌دهد، پیش‌فرض سیستم‌عامل است. گزینه --newline هیچ تأثیری بر این گزینه ندارد. این گزینه می‌تواند به هر تعداد بار مشخص شود؛ تمام فایل‌ها خوانده می‌شوند.
اگر هرگونه الگوی --include-dir مشخص شده باشد، تنها دایرکتوری‌هایی پردازش می‌شوند که با یکی از الگوها مطابقت داشته باشند (و با یک الگوی --exclude-dir مطابقت نداشته باشند). این امر برای تمام دایرکتوری‌ها اعمال می‌شود، خواه در خط فرمان فهرست شده باشند، از --file-list به دست آمده باشند یا با اسکن یک دایرکتوری والد پیدا شوند. الگو یک عبارت باقاعده PCRE است و در برابر آخرین مؤلفه نام دایرکتوری تطبیق داده می‌شود، نه کل مسیر. گزینه‌های -F، -w و -x برای این الگو اعمال نمی‌شوند. این گزینه می‌تواند به هر تعداد بار مشخص شود. اگر یک دایرکتوری هم با یک الگوی --include-dir و هم با یک الگوی --exclude-dir مطابقت داشته باشد، مستثنی می‌شود. هیچ فرم کوتاهی برای این گزینه وجود ندارد.
به جای چاپ خطوط از فایل‌ها، فقط نام فایل‌هایی را چاپ کن که حاوی هیچ خطی نیستند که در صورت تطابق چاپ می‌شد. هر نام فایل یک بار و در یک خط جداگانه چاپ می‌شود.
به جای چاپ خطوط از فایل‌ها، فقط نام فایل‌هایی را چاپ کن که حاوی خطوط منطبق هستند. هر نام فایل یک بار و در یک خط جداگانه چاپ می‌شود. جستجو معمولاً به محض یافتن یک خط منطبق در فایل متوقف می‌شود. با این حال، اگر از گزینه -c (شمارش) نیز استفاده شود، تطبیق برای به دست آوردن تعداد صحیح ادامه می‌یابد، و آن دسته از فایل‌هایی که حداقل یک تطابق دارند همراه با تعدادشان فهرست می‌شوند. استفاده از این گزینه با -c روشی برای جلوگیری از فهرست شدن فایل‌های بدون تطابق است.
این گزینه نامی را برای استفاده به عنوان ورودی استاندارد در هنگام چاپ نام فایل‌ها ارائه می‌دهد. اگر مشخص نشود، از "(standard input)" استفاده می‌شود. هیچ فرم کوتاهی برای این گزینه وجود ندارد.
هنگامی که این گزینه داده شود، ورودی خط به خط خوانده و پردازش می‌شود و خروجی پس از هر نوشتن تخلیه (flush) می‌شود. به‌طور پیش‌فرض، ورودی در تکه‌های بزرگ خوانده می‌شود، مگر اینکه pcregrep بتواند تشخیص دهد که در حال خواندن از یک ترمینال است (که در حال حاضر فقط در محیط‌های شبه‌یونیکس امکان‌پذیر است). خروجی ترمینال معمولاً به طور خودکار توسط سیستم‌عامل تخلیه می‌شود. این گزینه می‌تواند زمانی مفید باشد که ورودی یا خروجی به یک لوله (pipe) متصل است و نمی‌خواهید pcregrep مقادیر زیادی از داده را بافر کند. با این حال، استفاده از آن بر کارایی اثر می‌گذارد و گزینه -M (چندخطی) دیگر کار نخواهد کرد.
به جای نمایش خطوط یا بخش‌هایی از خطوط که مطابقت دارند، هر تطابق به صورت یک شماره خط، آفست از ابتدای خط و یک طول نشان داده شود. شماره خط با یک دونقطه خاتمه می‌یابد (طبق معمول؛ گزینه -n را ببینید)، و آفست و طول با کاما از هم جدا می‌شوند. در این حالت، هیچ زمینه‌ای نمایش داده نمی‌شود. به این معنی که گزینه‌های -A، -B و -C نادیده گرفته می‌شوند. اگر بیش از یک تطابق در یک خط وجود داشته باشد، هر یک از آنها به طور جداگانه نمایش داده می‌شود. این گزینه با --file-offsets و --only-matching مانعة‌الجمع است.
این گزینه یک محلی (locale) را برای استفاده در تطبیق الگو مشخص می‌کند. این گزینه مقدار متغیرهای محیطی LC_ALL یا LC_CTYPE را بازنویسی می‌کند. اگر هیچ محلی مشخص نشود، پیش‌فرض کتابخانه PCRE (معمولاً محلی "C") استفاده می‌شود. هیچ فرم کوتاهی برای این گزینه وجود ندارد.
پردازش برخی از الگوهای عبارات باقاعده می‌تواند به مقدار بسیار زیادی حافظه نیاز داشته باشد، که در برخی موارد اگر حافظه کافی در دسترس نباشد منجر به از کار افتادن برنامه (crash) می‌شود. الگوهای دیگر ممکن است زمان بسیار زیادی را برای جستجوی تمامی رشته‌های منطبق ممکن صرف کنند. تابع pcre_exec() که توسط pcregrep برای انجام تطبیق فراخوانی می‌شود، دارای دو پارامتر است که می‌توانند منابع مورد استفاده آن را محدود کنند.

گزینه --match-limit روشی برای محدود کردن مصرف منابع در هنگام پردازش الگوهایی فراهم می‌کند که قرار نیست مطابقت داشته باشند، اما تعداد بسیار زیادی احتمال در درخت‌های جستجوی خود دارند. مثال کلاسیک، الگویی است که از تکرارهای نامحدود تو در تو استفاده می‌کند. در درون، PCRE از تابعی به نام match() استفاده می‌کند که آن را مکرراً (گاهی به صورت بازگشتی) فراخوانی می‌نماید. محدودیتی که توسط --match-limit تنظیم می‌شود بر تعداد دفعات فراخوانی این تابع در طول یک تطابق اعمال می‌شود، که این کار اثر محدود کردن میزان پس‌گرد (backtracking) ممکن را به همراه دارد.

گزینه --recursion-limit شبیه به --match-limit است، اما به جای محدود کردن تعداد کل دفعاتی که match() فراخوانی می‌شود، عمق فراخوانی‌های بازگشتی را محدود می‌کند که به نوبه خود میزان حافظه قابل استفاده را محدود می‌سازد. عمق بازگشت عدد کوچک‌تری نسبت به تعداد کل فراخوانی‌ها است، زیرا همه فراخوانی‌های match() بازگشتی نیستند. این محدودیت تنها در صورتی کاربرد دارد که کوچک‌تر از --match-limit تنظیم شود.

هیچ فرم کوتاهی برای این گزینه‌ها وجود ندارد. تنظیمات پیش‌فرض هنگام کامپایل کتابخانه PCRE مشخص می‌شوند که پیش‌فرض اولیه آن ۱۰ میلیون است.

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

هنگامی که این گزینه تنظیم شود، کتابخانه PCRE در حالت «چندخطی» (multiline) فراخوانی می‌شود. محدودیتی در تعداد خطوطی که می‌توانند مطابقت داده شوند وجود دارد که ناشی از نحوه بافر کردن فایل ورودی توسط pcregrep در زمان اسکن آن است. با این حال، pcregrep تضمین می‌کند که حداقل 8K کاراکتر یا بقیه سند (هر کدام که کوتاه‌تر باشد) برای تطبیق رو به جلو در دسترس باشد، و به طور مشابه 8K کاراکتر قبلی (یا تمامی کاراکترهای قبلی، اگر کمتر از 8K باشند) تضمین می‌شوند که برای تطابق‌های پس‌نگر (lookbehind assertions) در دسترس باشند. این گزینه زمانی که ورودی خط به خط خوانده می‌شود کار نمی‌کند (به --line-buffered مراجعه کنید).

کتابخانه PCRE از پنج قرارداد مختلف برای نشان دادن انتهای خطوط پشتیبانی می‌کند. آنها عبارتند از توالی‌های تک‌کاراکتری CR (بازگشت مکان‌نما) و LF (تغذیه خط)، توالی دوکاراکتری CRLF، قرارداد "anycrlf" که هر یک از سه نوع قبلی را شناسایی می‌کند، و قرارداد "any" که در آن هر توالی انتهای خط یونیکد برای پایان دادن به یک خط فرض می‌شود. توالی‌های یونیکد عبارتند از سه مورد ذکر شده، به‌علاوه VT (تب عمودی، U+000B)، FF (تغذیه فرم، U+000C)، NEL (خط بعدی، U+0085)، LS (جداکننده خط، U+2028) و PS (جداکننده پاراگراف، U+2029).

هنگام ساخت کتابخانه PCRE، یک توالی پیش‌فرض برای انتهای خط مشخص می‌شود. این توالی معمولاً توالی استاندارد برای سیستم‌عامل است. مگر اینکه توسط این گزینه خلاف آن مشخص شود، pcregrep از پیش‌فرض کتابخانه استفاده می‌کند. مقادیر ممکن برای این گزینه عبارتند از CR، LF، CRLF، ANYCRLF یا ANY. این گزینه امکان می‌دهد از pcregrep برای اسکن فایل‌هایی که از محیط‌های دیگر آمده‌اند بدون نیاز به تغییر پایانه‌های خطوط آنها استفاده شود. اگر داده‌هایی که اسکن می‌شوند با قرارداد تعیین‌شده توسط این گزینه مطابقت نداشته باشند، pcregrep ممکن است رفتارهای ناهنجار و عجیبی نشان دهد. توجه داشته باشید که این گزینه برای فایل‌های مشخص‌شده توسط گزینه‌های -f، --exclude-from یا --include-from که انتظار می‌رود از توالی استاندارد خط جدید سیستم‌عامل استفاده کنند اعمال نمی‌شود.

در ابتدای هر خط خروجی، شماره خط آن در فایل درج شود، که برای خطوط منطبق با یک دونقطه (:) یا برای خطوط زمینه با یک خط تیره (-) دنبال می‌شود. اگر نام فایل نیز در خروجی چاپ شود، قبل از شماره خط قرار می‌گیرد. در صورت استفاده از --line-offsets، این گزینه اجباری می‌شود.
اگر کتابخانه PCRE همراه با پشتیبانی از کامپایل درست‌درزمان (JIT - Just-In-Time) ساخته شده باشد (که سرعت تطبیق را افزایش می‌دهد)، pcregrep به طور خودکار از آن استفاده می‌کند، مگر اینکه در زمان ساخت صراحتاً غیرفعال شده باشد. این گزینه می‌تواند برای غیرفعال کردن استفاده از JIT در زمان اجرا به کار رود. این گزینه برای آزمایش و دور زدن مشکلات در نظر گرفته شده است. در استفاده عادی هرگز نباید به آن نیازی باشد.
به جای کل خط، تنها بخشی از خط را که با یک الگو مطابقت دارد نشان بده. در این حالت، هیچ زمینه‌ای نمایش داده نمی‌شود. یعنی گزینه‌های -A، -B و -C نادیده گرفته می‌شوند. اگر بیش از یک تطابق در یک خط وجود داشته باشد، هر یک از آنها به طور جداگانه نشان داده می‌شوند. اگر -o با -v ترکیب شود (معکوس کردن منطق تطبیق برای یافتن خطوط غیرمنطبق)، هیچ خروجی تولید نمی‌شود، اما کد بازگشتی به طور مناسب تنظیم می‌شود. اگر بخش منطبق خط خالی باشد، چیزی در خروجی چاپ نمی‌شود مگر اینکه نام فایل یا شماره خط در حال چاپ باشند، که در این صورت آنها در یک خط که در غیر این صورت خالی می‌بود نمایش داده می‌شوند. این گزینه با --file-offsets و --line-offsets مانعة‌الجمع است.
تنها بخشی از خط را نشان بده که با پرانتزهای گیرنده (capturing parentheses) با شماره داده‌شده مطابقت دارد. حداکثر تا ۳۲ پرانتز گیرنده پشتیبانی می‌شود، و -o0 معادل -o بدون شماره است. از آنجا که این گزینه‌ها می‌توانند بدون آرگومان داده شوند (بالا را ببینید)، در صورت وجود آرگومان، باید در همان بخش خط فرمان داده شود، به عنوان مثال -o3 یا --only-matching=2. نکاتی که در بالا برای حالت بدون آرگومان ذکر شد برای این حالت نیز اعمال می‌شود. اگر پرانتزهای گیرنده مشخص‌شده در الگو وجود نداشته باشند، یا در تطابق تنظیم نشده باشند، چیزی چاپ نمی‌شود مگر اینکه نام فایل یا شماره خط در حال چاپ باشند.

اگر این گزینه چندین بار داده شود، چندین زیررشته به همان ترتیبی که گزینه‌ها داده شده‌اند چاپ می‌شوند. برای مثال، -o3 -o1 -o3 باعث می‌شود زیررشته‌های منطبق با پرانتزهای گیرنده ۳ و ۱ و سپس مجدداً ۳ خروجی داده شوند. به‌طور پیش‌فرض، هیچ جداکننده‌ای وجود ندارد (اما گزینه بعدی را ببینید).

مشخص کردن یک رشته جداکننده برای رخدادهای چندگانه -o. پیش‌فرض یک رشته خالی است. رشته‌های جداکننده هرگز رنگی نمی‌شوند.
کار بدون خروجی متنی (ساکت)، به این معنی که هیچ‌چیز جز پیام‌های خطا نمایش داده نشود. وضعیت خروج نشان می‌دهد که آیا تطابقی پیدا شده است یا خیر.
اگر هر مسیر داده‌شده یک دایرکتوری باشد، فایل‌های درون آن را به صورت بازگشتی اسکن کن و به هرگونه تنظیمات --include و --exclude توجه نما. به‌طور پیش‌فرض، یک دایرکتوری به عنوان یک فایل معمولی خوانده می‌شود؛ در برخی سیستم‌عامل‌ها این امر بلافاصله پایان فایل (EOF) را ایجاد می‌کند. این گزینه خلاصه و معادل با تنظیم گزینه -d بر روی "recurse" است.
توضیحات مربوط به --match-limit در بالا را ببینید.
جلوگیری از نمایش پیام‌های خطا درباره فایل‌های ناموجود یا غیرقابل خواندن. از این‌گونه فایل‌ها به طور بی‌صدا صرف‌نظر می‌شود. با این حال، کد بازگشتی همچنان ۲ است، حتی اگر تطابق‌هایی در فایل‌های دیگر پیدا شده باشد.
کار در حالت UTF-8. این گزینه تنها در صورتی در دسترس است که PCRE همراه با پشتیبانی از UTF-8 کامپایل شده باشد. تمامی الگوها (شامل الگوهای مربوط به هر یک از گزینه‌های --exclude و --include) و تمام خطوط ورودی که اسکن می‌شوند باید رشته‌هایی معتبر از کاراکترهای UTF-8 باشند.
چاپ شماره نسخه pcregrep و کتابخانه PCRE در خروجی استاندارد و سپس خروج. هر چیز دیگری در خط فرمان نادیده گرفته می‌شود.
معکوس کردن منطق تطبیق، به‌طوری که خطوطی که با هیچ‌یک از الگوها مطابقت ندارند، مواردی باشند که پیدا می‌شوند.
اجبار الگوها به تطبیق تنها با کل کلمات. این معادل با داشتن \b در ابتدا و انتهای الگو است. این گزینه تنها برای الگوهایی اعمال می‌شود که با محتوای فایل‌ها تطبیق داده می‌شوند؛ برای الگوهای مشخص‌شده با هر یک از گزینه‌های --include یا --exclude اعمال نمی‌شود.
اجبار الگوها به مهار شدن (هر الگو باید تطبیق را از ابتدای خط آغاز کند) و علاوه بر آن، الزام آنها به تطابق با کل خطوط. این معادل با قرار دادن نویسه‌های ^ و $ در ابتدا و انتهای هر شاخه جایگزین در هر الگو است. این گزینه فقط برای الگوهایی اعمال می‌شود که در برابر محتوای فایل‌ها تطبیق داده می‌شوند؛ برای الگوهای مشخص‌شده با هر یک از گزینه‌های --include یا --exclude اعمال نمی‌شود.

متغیرهای محیطی LC_ALL و LC_CTYPE به همین ترتیب برای یافتن یک محلی (locale) بررسی می‌شوند. نخستین متغیری که تنظیم شده باشد استفاده می‌شود. این مقدار می‌تواند توسط گزینه --locale بازنویسی شود. اگر هیچ محلی تنظیم نشده باشد، پیش‌فرض کتابخانه PCRE (معمولاً محلی "C") استفاده می‌شود.

گزینه -N (--newline) به pcregrep اجازه می‌دهد تا فایل‌ها را با قراردادهای خط جدید متفاوتی نسبت به حالت پیش‌فرض اسکن کند. هر بخشی از فایل‌های ورودی که در خروجی استاندارد نوشته می‌شود، با هر توالی خط جدیدی که در ورودی داشته است عیناً کپی می‌شود. با این حال، تنظیم این گزینه بر تفسیر فایل‌های مشخص‌شده با گزینه‌های -f، --exclude-from یا --include-from که فرض می‌شود از توالی خط جدید استاندارد سیستم‌عامل استفاده می‌کنند تأثیری ندارد، و همچنین بر نحوه نوشتن پیام‌های اطلاعاتی توسط pcregrep در جریان‌های خروجی استاندارد و خطای استاندارد تأثیری نمی‌گذارد. برای این پیام‌ها، این ابزار از رشته "\n" برای نشان دادن خطوط جدید استفاده می‌کند و برای تبدیل آن به یک توالی مناسب به کتابخانه ورودی/خروجی C متکی است.

بسیاری از فرم‌های کوتاه و طولانی گزینه‌های pcregrep همانند برنامه GNU grep هستند. هر گزینه طولانی به فرم --xxx-regexp (اصطلاحات GNU) به صورت --xxx-regex (اصطلاحات PCRE) نیز در دسترس است. با این حال، گزینه‌های --file-list، --file-offsets، --include-dir، --line-offsets، --locale، --match-limit، -M، --multiline، -N، --newline، --om-separator، --recursion-limit، -u و --utf-8 مختص pcregrep هستند، همان‌طور که استفاده از گزینه --only-matching با شماره پرانتزهای گیرنده مختص آن است.

اگرچه بیشتر گزینه‌های رایج به همان روش کار می‌کنند، تعداد کمی در pcregrep متفاوت هستند. برای مثال، آرگومان گزینه --include در GNU grep یک تطابق الگو (glob) است، اما در pcregrep یک عبارت باقاعده است. اگر هر دو گزینه -c و -l داده شوند، GNU grep فقط نام فایل‌ها را بدون شمارش فهرست می‌کند، اما pcregrep شمارش را نیز چاپ می‌نماید.

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

-f/some/file
-f /some/file

استثنا گزینه -o است که ممکن است با یا بدون داده ظاهر شود. به همین دلیل، اگر داده وجود داشته باشد، باید بلافاصله در همان بخش بیاید، برای مثال -o3.

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

--file=/some/file
--file /some/file

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

استثناهای موارد فوق گزینه‌های --colour (یا --color) و --only-matching هستند که داده برای آنها اختیاری است. اگر یکی از این گزینه‌ها داده داشته باشد، باید در فرم اول و با استفاده از علامت مساوی ارائه شود. در غیر این صورت pcregrep فرض می‌کند که داده‌ای ندارد.

امکان ارائه یک عبارت باقاعده وجود دارد که شکست آن در تطابق با خطوطی خاص، زمان بسیار زیادی ببرد. چنین الگوهایی معمولاً شامل تکرارهای نامحدود تو در تو هستند، برای مثال: (a+)*\d هنگامی که در برابر خطی از aها بدون هیچ رقم پایانی مطابقت داده شود. تابع تطبیق PCRE دارای یک محدودیت منابع است که باعث می‌شود در این شرایط عملیات متوقف شود. اگر این اتفاق بیفتد، pcregrep یک پیام خطا و خطی را که باعث بروز مشکل شده است در جریان خطای استاندارد چاپ می‌کند. اگر بیش از ۲۰ مورد از این خطاها رخ دهد، pcregrep تسلیم شده و متوقف می‌شود.

گزینه --match-limit از pcregrep می‌تواند برای تنظیم محدودیت کلی منابع استفاده شود؛ گزینه دومی به نام --recursion-limit وجود دارد که محدودیتی را بر مقدار حافظه مورد استفاده (معمولاً پشته یا stack) تنظیم می‌کند (به بررسی این گزینه‌ها در بالا مراجعه کنید).

وضعیت خروج در صورت یافتن هرگونه تطابق ۰، در صورتی که هیچ تطابقی پیدا نشود ۱، و برای خطاهای نحوی، خطوط بیش از حد طولانی، فایل‌های ناموجود یا غیرقابل دسترسی (حتی اگر در فایل‌های دیگر تطابق پیدا شده باشد) یا خطاهای تطبیق بسیار زیاد، ۲ است. استفاده از گزینه -s برای جلوگیری از نمایش پیام‌های خطا درباره فایل‌های غیرقابل دسترسی، تأثیری بر کد بازگشتی ندارد.

pcrepattern(3), pcresyntax(3), pcretest(1).

Philip Hazel
University Computing Service
Cambridge CB2 3QH, England.

Last updated: 03 April 2014
Copyright (c) 1997-2014 University of Cambridge.
03 April 2014 PCRE 8.35