# Edit

يُنفِّذ استبدال سلسلة نصية دقيق داخل ملف قائم. هي الطريقة المفضلة لتعديل الملفات لأن ما يُرسَل هو الفارق فقط، ما يُبقي التعديلات دقيقة وقابلة للتدقيق.

## متى يُستخدم

- إصلاح علة في دالة واحدة دون إعادة كتابة الملف المحيط
- تحديث قيمة إعداد أو سلسلة إصدار أو مسار استيراد
- إعادة تسمية رمز عبر ملف باستخدام `replace_all`
- إدراج كتلة قرب علامة مرجعية (وسِّع `old_string` ليشمل سياقاً قريباً، ثم قدِّم الاستبدال)
- تطبيق تعديلات صغيرة محددة النطاق ضمن إعادة هيكلة متعددة الخطوات

## المعاملات

- `file_path` (سلسلة، مطلوب): المسار المطلق للملف المراد تعديله.
- `old_string` (سلسلة، مطلوب): النص المضبوط المطلوب البحث عنه. يجب أن يتطابق حرفاً حرفاً، بما في ذلك المسافات البيضاء والمسافة البادئة.
- `new_string` (سلسلة، مطلوب): نص الاستبدال. يجب أن يختلف عن `old_string`.
- `replace_all` (قيمة منطقية، اختياري): عندما تكون `true`، يستبدل كل ورود لـ `old_string`. الافتراضي `false`، ويتطلب أن يكون التطابق فريداً.

## أمثلة

### مثال 1: إصلاح موقع استدعاء واحد
اضبط `old_string` على السطر الدقيق `const port = 3000;` و`new_string` على `const port = process.env.PORT ?? 3000;`. التطابق فريد لذا يمكن إبقاء `replace_all` على قيمته الافتراضية.

### مثال 2: إعادة تسمية رمز عبر ملف
لإعادة تسمية `getUser` إلى `fetchUser` في كل مكان داخل `api.ts`، اضبط `old_string: "getUser"` و`new_string: "fetchUser"` و`replace_all: true`.

### مثال 3: إزالة الالتباس في مقتطف متكرر
إذا ظهر `return null;` في عدة فروع، فوسِّع `old_string` ليشمل سياقاً محيطاً (مثل سطر `if` السابق) حتى يكون التطابق فريداً. وإلا ستُصدر الأداة خطأً بدلاً من التخمين.

## ملاحظات

- يجب عليك استدعاء `Read` على الملف مرة واحدة على الأقل في الجلسة الحالية قبل أن يقبل `Edit` التغييرات. بادئات أرقام الأسطر من مخرجات `Read` ليست جزءاً من محتوى الملف؛ لا تُضمنها في `old_string` أو `new_string`.
- يجب أن تتطابق المسافات البيضاء تماماً. انتبه للتبويبات مقابل المسافات والمسافات الزائدة في النهاية، خاصةً في YAML وMakefiles وPython.
- إذا لم يكن `old_string` فريداً وكان `replace_all` هو `false`، يفشل التعديل. إما أن توسِّع السياق أو أن تُفعِّل `replace_all`.
- فضِّل `Edit` على `Write` كلما كان الملف موجوداً فعلاً؛ إذ يُعيد `Write` كتابة الملف بأكمله ويفقد المحتوى غير المرتبط إن لم تكن حذراً.
- لإجراء عدة تعديلات غير مترابطة في الملف نفسه، أصدر عدة استدعاءات `Edit` بالتعاقب بدلاً من استبدال واحد كبير وهش.
- تجنَّب إدخال الرموز التعبيرية أو النصوص التسويقية أو كتل التوثيق غير المطلوبة عند تعديل ملفات المصدر.
