editorconfig-format(5) File Formats Manual editorconfig-format(5)

editorconfig-format - قالب فایل پیکربندی EditorConfig

فایل‌های EditorConfig از قالب INI استفاده می‌کنند که با قالب مورد استفاده توسط کتابخانه ConfigParser پایتون سازگار است، اما استفاده از [ و ] نیز در نام بخش‌ها مجاز است. نام بخش‌ها الگوهای تطبیق مسیر فایل (filepath globs) هستند که مشابه قالب پذیرفته‌شده توسط gitignore می‌باشند. اسلش‌های رو به جلو (/) به عنوان جداکننده مسیر استفاده می‌شوند و از نقطه‌ویرگول (;) یا علامت مربع/هشتگ (#) برای نوشتن توضیحات (کامنت‌ها) استفاده می‌شود. توضیحات باید در خطوط جداگانه قرار گیرند. فایل‌های EditorConfig باید دارای کدگذاری UTF-8 باشند و از جداکننده‌های خط CRLF یا LF استفاده کنند.

الگوهای تطبیق نام فایل (Filename globs) که شامل جداکننده‌های مسیر (/) هستند، دقیقاً به همان روش الگوهای تطبیق نام فایل استفاده‌شده در فایل‌های .gitignore با مسیرهای فایل مطابقت داده می‌شوند. استفاده از بک‌اسلش (\) به عنوان جداکننده مسیر مجاز نیست.

کاراکتر نقطه‌ویرگول (;) یک توضیح (کامنت) خطی را آغاز می‌کند که در انتهای همان خط پایان می‌یابد. خطوط توضیح و خطوط خالی هنگام تجزیه نادیده گرفته می‌شوند. توضیحات همچنین می‌توانند به انتهای خطوط غیرخالی اضافه شوند. به جای نقطه‌ویرگول می‌توان از کاراکتر هشتگ (#) نیز برای نشان دادن آغاز یک توضیح استفاده کرد.

هنگامی که یک نام فایل به EditorConfig داده می‌شود، جستجویی در دایرکتوری آن فایل و تمامی دایرکتوری‌های والد برای یافتن فایل EditorConfig (که به صورت پیش‌فرض ".editorconfig" نام دارد) انجام می‌گیرد. تمام فایل‌های EditorConfig یافت‌شده برای بخش‌هایی که نام آن‌ها با نام فایل مشخص‌شده مطابقت دارد جستجو می‌شوند. در صورتی که یک فایل EditorConfig پیدا شود که ویژگی root آن برابر با true تنظیم شده باشد یا جستجو به دایرکتوری ریشه سیستم‌فایل برسد، جستجو متوقف خواهد شد.

فایل‌ها از بالا به پایین خوانده می‌شوند و جدیدترین قوانین یافت‌شده اولویت دارند. اگر چند فایل EditorConfig دارای بخش‌های منطبق باشند، قوانین فایلی که به فایل مربوطه نزدیک‌تر است دیرتر خوانده می‌شوند؛ بنابراین ویژگی‌های موجود در فایل‌های نزدیک‌تر اولویت خواهند داشت.

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

* با هر رشته‌ای از نویسه‌ها، به جز جداکننده‌های مسیر (/)، مطابقت دارد

** با هر رشته‌ای از نویسه‌ها مطابقت دارد

? با هر تک‌نویسه‌ای مطابقت دارد

[seq] با هر تک‌نویسه‌ای در seq مطابقت دارد

[!seq] با هر تک‌نویسه‌ای که در seq نباشد مطابقت دارد

{s1,s2,s3} با هر یک از رشته‌های ارائه‌شده مطابقت دارد (با کاما از هم جدا می‌شوند، می‌توانند تودرتو باشند)

{num1..num2} با هر عدد صحیحی بین num1 و num2 مطابقت دارد، که در آن num1 و num2 می‌توانند مثبت یا منفی باشند

از نویسه بک‌اسلش (\) می‌توان برای خنثی‌سازی (escape) یک نویسه استفاده کرد تا به عنوان نویسه خاص تفسیر نشود.

حداکثر طول نام یک بخش ۴۰۹۶ نویسه است. تمام بخش‌هایی که از این حد فراتر بروند نادیده گرفته می‌شوند.

بخش‌های فایل EditorConfig شامل ویژگی‌ها (properties) هستند که جفت‌های نام-مقدار جداشده با علامت مساوی (=) می‌باشند. افزونه‌های EditorConfig نام‌های ویژگی ناشناخته و ویژگی‌های دارای مقادیر نامعتبر را نادیده خواهند گرفت.

در ادامه فهرست تمام نام‌های ویژگی که برای EditorConfig قابل فهم هستند و تمامی مقادیر معتبر برای این ویژگی‌ها آورده شده است:

  • indent_style: برای استفاده از تب‌های سخت یا نرم (فاصله) به ترتیب روی "tab" یا "space" تنظیم می‌شود. این مقادیر به حروف بزرگ و کوچک حساس نیستند.
  • indent_size: یک عدد صحیح که تعداد ستون‌های استفاده‌شده برای هر سطح تورفتگی و همچنین عرض تب‌های نرم (در صورت پشتیبانی) را مشخص می‌کند. اگر این مقدار برابر با "tab" باشد، indent_size روی اندازه تب تنظیم می‌شود؛ که اگر tab_width مشخص شده باشد برابر با tab_width خواهد بود، و در غیر این صورت برابر با اندازه تب تنظیم‌شده توسط ویرایشگر خواهد بود. این مقادیر به حروف بزرگ و کوچک حساس نیستند.
  • tab_width: یک عدد صحیح که تعداد ستون‌های مورد استفاده برای نمایش یک نویسه تب را مشخص می‌کند. مقدار پیش‌فرض آن برابر با مقدار indent_size است و معمولاً نیازی به مشخص کردن آن نیست.
  • end_of_line: برای کنترل نحوه نمایش شکستگی خطوط، روی "lf"، "cr" یا "crlf" تنظیم می‌شود. این مقادیر به حروف بزرگ و کوچک حساس نیستند.
  • charset: برای کنترل مجموعه نویسه‌ها روی "latin1"، "utf-8"، "utf-8-bom"، "utf-16be" یا "utf-16le" تنظیم می‌شود. استفاده از "utf-8-bom" توصیه نمی‌شود.
  • trim_trailing_whitespace: برای حذف هرگونه نویسه فاصله قبل از کاراکترهای خط جدید روی "true" و برای اطمینان از حذف نشدن آن روی "false" تنظیم می‌شود.
  • insert_final_newline: برای اطمینان از این‌که فایل هنگام ذخیره با یک خط جدید پایان می‌یابد روی "true" و در غیر این صورت روی "false" تنظیم می‌شود.
  • root: ویژگی خاصی که باید در بالاترین بخش فایل و خارج از تمامی بخش‌ها مشخص شود. برای متوقف کردن جستجوی فایل‌های .editorconfig برای فایل جاری، روی "true" تنظیم می‌شود. این مقدار به حروف بزرگ و کوچک حساس نیست.

برای هر ویژگی، مقدار "unset" اثر آن ویژگی را حذف می‌کند، حتی اگر قبلاً مقداردهی شده باشد. برای نمونه، افزودن "indent_size =unset" برای لغو تعریف ویژگی indent_size (و استفاده از مقدار پیش‌فرض ویرایشگر) استفاده می‌شود.

نام‌های ویژگی به حروف بزرگ و کوچک حساس نیستند و هنگام تجزیه تمام نام‌های ویژگی به حروف کوچک تبدیل می‌شوند. حداکثر طول نام یک ویژگی ۵۰ نویسه و حداکثر طول مقدار یک ویژگی ۲۵۵ نویسه است. هر ویژگی که فراتر از این محدودیت‌ها باشد نادیده گرفته خواهد شد.

EditorConfig