نام (NAME)

rgr - ابزاری تعاملی برای جایگزینی در ripgrep جهت یافتن و جایگزین کردن آسان متن میان فایل‌ها در خط فرمان.

توضیحات (DESCRIPTION)

برای استفاده از این ابزار، ابتدا باید rg (معروف به ripgrep) را نصب کرده باشید. ببینید: https://github.com/BurntSushi/ripgrep#installation.

نحوه استفاده (USAGE)

استفاده معمول

هنگام شروع، تمام آرگومان‌های خط فرمان به rg منتقل می‌شوند (با افزودن --json و --no-config). سپس خروجی JSON تجزیه شده و یک رابط خط فرمانی (که در ادامه توضیح داده شده) در اختیارتان قرار می‌گیرد.

توجه داشته باشید از آنجا که از گزینهٔ --json استفاده می‌شود، تعدادی از گزینه‌های rg در دسترس نخواهند بود. برای مشاهده فهرستی از گزینه‌های پشتیبانی‌شده که به ripgrep ارسال خواهند شد، rgr --help را ببینید.

گروه‌های تطبیق (Capturing Groups)

می‌توانید هنگام استفاده از rgr از گروه‌های تطبیق استفاده کنید، به عنوان مثال rgr "foo (\w+)". در صورت استفاده از آن‌ها، می‌توان با ارجاع به نامشان به صورت $name یا اندیس آنها به صورت $1 از موارد مطابقت‌یافته در جایگزینی استفاده کرد. این نحو از کریت regex به ارث رسیده است، ببینید: https://docs.rs/regex/1.8.4/regex/struct.Captures.html#method.expand

هنگام استفاده از گروه‌های تطبیق تنها یک الگو می‌تواند به صورت هم‌زمان ارسال شود (یعنی استفاده از چند گزینهٔ -e <pat> مجاز نیست).

جایگزینی خودکار

برای جایگزین کردن هر مورد مطابقت‌یافته بدون باز کردن رابط تعاملی، -y یا --autoreplace را به همراه -r یا --replace ارسال کنید. برای مثال، rgr -y "old_name" -r "new_name".

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

خواندن نتایج از یک فایل

این ابزار همچنین از خواندن نتایج از یک فایل JSON با در نظر گرفتن سناریوی کاربردی زیر پشتیبانی می‌کند:

•کاربر دستور "rg --json <args> > rg-results.json" را اجرا می‌کند

•اکنون این ابزار می‌تواند با استفاده از آن نتایج از طریق "RGR_JSON_FILE=./rg-results.json rgr" اجرا شود

برای مشاهدهٔ فهرست کلیدهای میانبر، هنگامی که در حالت SELECT هستید، کلید ? را فشار دهید. چند حالت مختلف وجود دارد:

SELECT

•این حالت نخستین حالتی است که پس از اجرای rgr نمایش داده می‌شود.

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

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

REPLACE

•در این حالت کاربر متن جایگزین مورد نظر را تایپ می‌کند و تطابق‌ها به‌صورت بی‌درنگ به‌روزرسانی می‌شوند.

•توجه داشته باشید که این حالت صرفاً یک پیش‌نمایش است و هیچ تغییری روی دیسک نوشته نمی‌شود.

•در این حالت بایت‌های غیر UTF-8 موجود در تطابق‌ها با نویسهٔ جایگزینِ UTF-8 نشان داده می‌شوند.

•فشردن control+s باعث می‌شود تمام تطابق‌های انتخاب‌شده با متن واردشده جایگزین شوند.

CONFIRM

•پیش از نوشتن جایگزینی‌ها روی دیسک، تأیید کاربر درخواست می‌شود.

•جایگزینی‌ها روی دیسک نوشته می‌شوند و تمام تلاش‌ها برای استفاده از کدگذاری صحیح فایل انجام می‌پذیرد (بخش FILE ENCODING را ببینید).

•توجه داشته باشید که rgr برشی از بایت‌ها به جز آنچه rg در خروجی خود گزارش کرده است را جایگزین نخواهد کرد (بخش FILE ENCODING را ببینید).

HELP

•این حالت اطلاعاتی دربارهٔ rgr و کلیدهای میانبر آن ارائه می‌دهد.

کاربر می‌تواند نحوهٔ نمایش نویسه‌های کنترلی در رابط کاربری را با فشردن control+v تغییر دهد. حالت‌های مختلف عبارتند از:

•C: نمایش نویسه‌های کنترلی رایج

•c: نمایش نویسه‌های کنترلی رایج (یک خطی)

•A: نمایش تمام نویسه‌های کنترلی

•a: نمایش تمام نویسه‌های کنترلی (یک خطی)

•H: نمایش نویسه‌های کنترلی رایج به عنوان فاصله و حذف سایر موارد (مخفی)

کدگذاری فایل (FILE ENCODING)

مدیریت کدگذاری فایل در دو مرحله رخ می‌دهد: در حالت SELECT و هنگام نوشتن جایگزینی‌ها روی دیسک.

در حالت SELECT، بایت‌های غیر UTF-8 با نویسهٔ جایگزین UTF-8 نشان داده می‌شوند. این اتفاق به این دلیل رخ می‌دهد که خود فایل‌ها هنوز خوانده نشده‌اند (اطلاعات مستقیماً از ripgrep می‌آید) و بنابراین کدگذاری فایل نامشخص است.

در حین جایگزینی کدگذاری به شیوهٔ زیر مدیریت می‌شود:

•اگر یک نشانگر ترتیب بایت (BOM) پیدا شود، از آن کدگذاری استفاده می‌شود؛ در غیر این صورت

•اگر یک کدگذاری به ripgrep ارسال شده باشد، از آن کدگذاری استفاده می‌شود؛ در غیر این صورت

•از کتابخانهٔ chardet ( https://github.com/thuleqaid/rust-chardet) برای تشخیص کدگذاری استفاده می‌شود

•اگر آن هم ناموفق باشد، کدگذاری UTF8 فرض می‌شود

توجه داشته باشید که rgr هرگز تطابقی را که انتظار ندارد، جایگزین نخواهد کرد. اگر در حین جایگزینی یک تطابق، بایت‌های جایگزین‌شونده با موارد تطبیق‌یافته توسط ripgrep یکسان نباشند، ابزار عملیات را لغو کرده و فایل روی دیسک نوشته نخواهد شد. (خطاها به STDERR گزارش می‌شوند.).SH "صفحه خانگی (HOMEPAGE)"

https://github.com/acheronfail/repgrep

باگ‌ها و قابلیت‌ها (BUGS AND FEATURES)

لطفاً باگ‌ها و درخواست‌های قابلیت‌ها را در سامانهٔ پیگیری مشکلات گزارش دهید. تمام تلاش خود را به کار گیرید تا یک نمونه آزمایشی قابل بازتولید برای باگ‌ها فراهم کنید. همچنین لطفاً نسخهٔ rgr و rg را نیز درج نمایید.