PDFGREP(1) Pdfgrep Manual PDFGREP(1)

pdfgrep - جستجوی عبارات باقاعده در فایل‌های PDF

pdfgrep [OPTION...] PATTERN FILE...
pdfgrep [OPTION...] {-e PATTERN|-f FILE}... FILE...
pdfgrep [OPTION...] -r|-R PATTERN [FILE|DIR...]
pdfgrep [OPTION...] -r|-R {-e PATTERN|-f FILE}... [FILE|DIR...]

در هر FILE از نوع PDF به دنبال PATTERN می‌گردد و خطوط منطبق را چاپ می‌کند. به‌طور پیش‌فرض، PATTERN یک عبارت باقاعده گسترش‌یافته (extended regular expression) است.

برنامهٔ pdfgrep تلاش می‌کند تا حد امکان با GNU grep سازگار باشد، با این تفاوت که برخی تمایزها و گزینه‌های اضافی مختص به PDF دارد. از همه قابل‌توجه‌تر اینکه گزینهٔ -n به جای شماره خط، شماره صفحه را چاپ می‌کند.

--help

خلاصه‌ای کوتاه از گزینه‌ها را چاپ می‌کند.

-V, --version

اطلاعات نسخه را نمایش می‌دهد.

-F, --fixed-strings

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

-P, --perl-regexp

الگوی PATTERN را به عنوان یک عبارت باقاعده سازگار با پرل (PCRE2) تفسیر می‌کند. برای یک مرور اجمالی، pcre2syntax(3) را ببینید.

-e PATTERN, --regexp=PATTERN

از PATTERN به عنوان الگوی جستجو استفاده می‌کند. اگر این گزینه چندین بار مشخص شود یا با --file ترکیب گردد، همهٔ الگوها به نوبت امتحان می‌شوند تا زمانی که یکی از آن‌ها تطابق یابد.

-f FILE, --file=FILE

الگوها را از FILE، یک مورد در هر خط، می‌خواند. اگر FILE حاوی چندین الگو باشد یا این گزینه چندین بار اعمال شده یا با -e ترکیب شود، همهٔ الگوها به نوبت امتحان می‌شوند تا یکی از آن‌ها مطابقت یابد. یک فهرست الگوی خالی با هیچ چیز مطابقت نخواهد داشت.

-i, --ignore-case

تمایز بین حروف بزرگ و کوچک را هم در PATTERN و هم در فایل‌های ورودی نادیده می‌گیرد.

-c, --count

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

-p, --page-count

مانند -c، اما تعداد تطابق‌ها را در هر صفحه چاپ می‌کند. به‌طور ضمنی -n را فعال می‌کند.

--color WHEN

نام‌های فایل، شماره‌های صفحه و متن تطبیق‌یافته را با توالی‌های گریز احاطه می‌کند تا در ترمینال به‌صورت رنگی نمایش داده شوند. WHEN می‌تواند یکی از مقادیر زیر باشد:
always همیشه از رنگ‌ها استفاده کن، حتی زمانی که stdout یک ترمینال نباشد.
never از رنگ‌ها استفاده نکن.
auto تنها زمانی از رنگ‌ها استفاده کن که stdout یک ترمینال باشد (این حالت پیش‌فرض است).

-L, --files-without-match

خروجی عادی را بازداری می‌کند. به‌جای آن نام هر فایل ورودی را که حاوی هیچ تطابقی نیست چاپ می‌کند. این گزینه به‌خوبی با -Z کار می‌کند، اما در صورت مشخص شدن -L، بسیاری از گزینه‌های خروجی دیگر مانند -n یا -c نادیده گرفته می‌شوند.

-l, --files-with-matches

خروجی عادی را بازداری می‌کند. به‌جای آن نام هر فایل ورودی را که حاوی تطابق است چاپ می‌کند. این گزینه به‌خوبی با -Z کار می‌کند، اما در صورت مشخص شدن -l، بسیاری از گزینه‌های خروجی دیگر مانند -n یا -c نادیده گرفته می‌شوند.

-m, --max-count NUM

خواندن یک فایل را پس از NUM تطابق متوقف می‌کند. هنگامی که گزینه -c یا --count نیز استفاده شود، pdfgrep عددی بزرگ‌تر از NUM را در خروجی چاپ نخواهد کرد.

-o, --only-matching

تنها بخش تطبیق‌یافته از یک سطر را بدون بافت پیرامونی آن چاپ می‌کند.

-q, --quiet

تمام خروجی‌های عادی به stdout را بازداری می‌کند. در صورت یافتن تطابق، حتی در صورت بروز خطا، بلافاصله با وضعیت خروج 0 خارج می‌شود. اگر تنها وجود تطابق‌ها برای شما اهمیت دارد، نه تعداد یا محتوای آن‌ها، از این گزینه استفاده کنید.

-H, --with-filename

چاپ نام فایل برای هر تطابق. این تنظیم پیش‌فرض در حالتی است که بیش از یک فایل برای جست‌وجو وجود داشته باشد.

-h, --no-filename

جلوگیری از درج نام فایل به عنوان پیشوند در خروجی. این تنظیم پیش‌فرض در حالتی است که تنها یک فایل برای جست‌وجو وجود داشته باشد.

-n, --page-number[=TYPE]

افزودن شمارهٔ صفحه‌ای که تطابق در آن یافت شده به عنوان پیشوند به هر تطابق.

آرگومان اختیاری TYPE نحوهٔ تعیین شماره‌های صفحه را کنترل می‌کند. در صورت استفاده، می‌تواند یکی از مقادیر زیر باشد:

index اندیس صفحه در PDF، شروع از ۱ برای صفحهٔ نخست. این مقدار پیش‌فرض است.
label برچسب صفحهٔ PDF. این مقدار می‌تواند یک رشتهٔ دلخواه برای هر صفحه باشد که توسط سازندهٔ PDF تنظیم شده است (برای نمونه، ارقام رومی برای چند صفحهٔ اول).

-Z, --null

خروجی دادن یک بایت تهی (که در NUL در ASCII و '\0' در C نامیده می‌شود) به جای دونقطه‌ای که معمولاً نام فایل را از بقیهٔ سطر جدا می‌کند. این گزینه خروجی را در صورت وجود دونقطه، فاصله یا خطوط جدید در نام فایل بدون ابهام می‌سازد. می‌تواند در ترکیب با دستورهایی مانند xargs -0 یا perl -0 استفاده شود.

--match-prefix-separator SEP

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

-A NUM, --after-context=NUM

چاپ NUM سطر از زمینه پس از سطرهای منطبق. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی -- از هم جدا می‌شوند. با -o، این گزینه هیچ اثری ندارد.

-B NUM, --before-context=NUM

چاپ NUM سطر از زمینه پیش از سطرهای منطبق. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی -- از هم جدا می‌شوند. با -o، این گزینه هیچ اثری ندارد.

-C NUM, --context=NUM

چاپ NUM سطر از زمینه پیش و پس از سطرهای منطبق. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی -- از هم جدا می‌شوند. با -o، این گزینه هیچ اثری ندارد.

-r, --recursive

جستجوی بازگشتی در تمام فایل‌های زیر هر دایرکتوری (محدودشده توسط --include و --exclude)؛ پیوندهای نمادین (symlinks) تنها در صورتی دنبال می‌شوند که در خط فرمان مشخص شده باشند.

-R, --dereference-recursive

همانند -r، اما تمام پیوندهای نمادین را دنبال می‌کند.

--exclude=GLOB

نادیده‌گرفتن فایل‌هایی که نام پایه (base name) آن‌ها با GLOB تطابق دارد. برای نویسه‌های عامی که می‌توانید استفاده کنید به glob(7) مراجعه کنید. می‌توانید از این گزینه چندین بار برای مستثنی‌کردن الگوهای بیشتر استفاده کنید. این گزینه بر --include اولویت دارد. توجه داشته باشید که include و exclude تنها برای فایل‌های یافته‌شده از طریق --recursive اعمال می‌شوند و بر فهرست آرگومان‌ها اثر ندارند.

--include=GLOB

فقط جستجوی فایل‌هایی که نام پایه آن‌ها با GLOB تطابق دارد. برای جزئیات به --exclude مراجعه کنید. مقدار پیش‌فرض *.[Pp][Dd][Ff] است.

--cache

استفاده از حافظه موقت (cache) برای متن پردازش‌شده جهت افزایش سرعت عملیات روی فایل‌های حجیم.

--password=PASSWORD

استفاده از PASSWORD برای رمزگشایی فایل‌های PDF. می‌تواند چندین بار مشخص شود؛ تمام گذرواژه‌ها روی تمامی PDFها آزمایش خواهند شد. توجه داشته باشید که این گذرواژه در تاریخچه فرمان‌ها و در خروجی ps(1) نمایش داده خواهد شد. بنابراین در صورتی که امنیت PASSWORD اهمیت دارد، لطفاً از این گزینه استفاده نکنید.

--page-range=RANGE

محدود کردن جستجو به مجموعه‌ای مشخص از صفحه‌ها. RANGE فهرستی جداشده با کاما از شماره یک صفحه یا عبارت بازه‌ای به شکل PAGE1-PAGE2 است. مثال: 2-3,5,7-10.

--debug

فعال‌سازی خروجی اشکال‌زدایی (debug). نکته: به دلیل محدودیت‌های poppler قبل از نسخه 0.30.0، هنگام استفاده از چنین نسخه‌ای از poppler، برخی از خروجی‌های اشکال‌زدایی حتی بدون --debug نیز چاپ می‌شوند.

--warn-empty

چاپ هشدار در stderr اگر یک فایل PDF حاوی هیچ متن قابل جستجویی نباشد. این حالت برای PDFهایی رخ می‌دهد که تنها از تصویر تشکیل شده‌اند، مانند اسناد اسکن‌شده.

--unac

حذف اکسان‌ها، اعراب و ادغام حروف (ligatures) از هر دو الگوی جستجو و اسناد PDF. این گزینه زمانی مفید است که می‌خواهید کلمه‌ای حاوی «ae» را جستجو کنید، اما در PDF به جای آن از نویسه تکی «æ» استفاده شده است. برای جزئیات به unac(3) و unaccent(1) مراجعه کنید.

این گزینه آزمایشی است و تنها در صورتی در دسترس است که pdfgrep با پشتیبانی از unac کامپایل شده باشد.

به‌طور معمول، اگر دست‌کم یک مورد منطبق پیدا شود وضعیت خروج 0 است، اگر هیچ موردی یافت نشود 1 است و در صورت بروز خطا 2 است. اما اگر گزینهٔ --quiet یا -q به کار رود و موردی پیدا شده باشد، pdfgrep صرف‌نظر از خطاها 0 را برمی‌گرداند.

رفتار pdfgrep تحت تأثیر متغیر محیطی زیر قرار می‌گیرد.

GREP_COLORS

رنگ‌ها و دیگر ویژگی‌های به‌کاررفته برای برجسته‌سازی بخش‌های گوناگون خروجی را مشخص می‌کند. ساختار و مقادیر آن مانند GREP_COLORS در grep است. برای جزئیات بیشتر به grep(1) مراجعه کنید. در حال حاضر تنها قابلیت‌های mt، ms، mc، fn، ln و se توسط pdfgrep استفاده می‌شوند، که در این میان mt، ms و mc تأثیر یکسانی دارند.

${XDG_CACHE_HOME}/pdfgrep/*

فایل‌های حافظهٔ موقت (کَش) که هنگام فعال بودن --cache نوشته و استفاده می‌شوند. حداکثر ۲۰۰ مدخل کَش با قدمت بیش از یک روز نگهداری می‌شوند.

چاپ ده سطر نخست منطبق با pattern و چاپ شمارهٔ صفحهٔ آن‌ها:

pdfgrep -n --max-count 10 pattern foo.pdf

جست‌وجوی بازگشتی همهٔ فایل‌های .pdf که نام آن‌ها با foo آغاز می‌شود در دایرکتوری جاری:

pdfgrep -r --include "foo*.pdf" pattern

جست‌وجوی همهٔ فایل‌های PDF در دایرکتوری جاری برای foo که شامل bar نیز باشند:

pdfgrep -Z --files-with-matches "bar" *.pdf | xargs -0 pdfgrep -H foo

جست‌وجوی بازگشتی همهٔ فایل‌های .pdf با اندازهٔ کوچک‌تر از 12M در دایرکتوری جاری:

find . -name "*.pdf" -size -12M -print0 | xargs -0 pdfgrep pattern

توجه داشته باشید که برخلاف مثال‌های پیشین، این کار را نمی‌شد تنها با pdfgrep انجام داد، بلکه باید از ابزارهای یونیکس find(1) و xargs(1) استفاده می‌شد. دلیل این امر آن است که pdfgrep خودش گزینه‌هایی برای مستثنی کردن فایل‌ها بر اساس اندازه‌شان ندارد. اما همان‌طور که می‌بینید، نیازی هم به آن ندارد!

جست‌وجوی همهٔ فایل‌های .pdf در دایرکتوری جاری به‌صورت موازی روی یک پردازندهٔ چند‌هسته‌ای

find . -name "*.pdf" -print0 | parallel -q0 pdfgrep -H foobar

این دستور از GNU parallel(1) علاوه بر find(1) برای جست‌وجوی چندین فایل به‌طور موازی روی پردازنده‌های چند‌هسته‌ای استفاده می‌کند. در صورتی که چندین فایل برای جست‌وجو و یک پردازنده با ظرفیت استفاده‌نشده داشته باشید، انجام این کار می‌تواند به بهبود سرعت قابل‌توجهی منجر شود.

باگ‌ها را می‌توان به فهرست پستی (pdfgrep-users@pdfgrep.org) یا به ردیاب باگ در gitlab (https://gitlab.com/pdfgrep/pdfgrep/issues) گزارش کرد.

pdfgrep توسط Hans-Peter Deifel نگهداری می‌شود.

برای فهرست کامل مشارکت‌کنندگان، فایل AUTHORS را در کد منبع ببینید.

grep(1), pcre2(3), regex(7)

برای اطلاعات بیشتر، بارگیری‌ها، مخزن git و موارد دیگر، وبگاه pdfgrep به نشانی https://pdfgrep.org را مشاهده کنید.

03/15/2024 Pdfgrep 2.1.2