نام (NAME)

detoxrc — فایل پیکربندی برای detox(1)

نمای کلی (OVERVIEW)

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

مهم (IMPORTANT)

هنگام تنظیم مجموعه‌ای جدید از قواعد، فیلترهای safe و wipeup همواره باید پس از یک فیلتر تبدیل (یا مجموعه‌ای از آن‌ها)، مانند فیلترهای utf_8 یا uncgi اجرا شوند. در غیر این صورت، خطر ورود نویسه‌های دشوار و مشکل‌ساز به نام فایل وجود خواهد داشت.

ساختار دستوری (SYNTAX)

قالب این فایل پیکربندی مشابه زبان C است. این قالب به‌طور تقریبی بر اساس فایل‌های پیکربندی مورداستفاده توسط named طراحی شده است. هر دستور با یک نقطه-ویرگول خاتمه می‌یابد و اصلاح‌کننده‌ها در یک دستور خاص معمولاً درون آکولاد قرار می‌گیرند.

sequence "name" {sequence; ...};

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

یک توالی ویژه به نام default وجود دارد که توالی پیش‌فرض مورداستفاده توسط detox است. این مقدار را می‌توان از طریق گزینه خط فرمان -s یا متغیر محیطی DETOX_SEQUENCE تغییر داد و بازنویسی کرد.

نام‌های توالی به بزرگی و کوچکی حروف حساس بوده و در سراسر تمام توالی‌ها یکتا هستند؛ به این معنا که اگر یک فایل سراسری در سیستم، توالی normal_seq را تعریف کرده باشد و کاربر نیز توالی‌ای با همین نام در فایل .detoxrc خود داشته باشد، نسخه کاربر normal_seq جایگزین نسخه سراسری سیستم خواهد شد.

ignore {filename "filename"; ...};

هر نام فایلی که در اینجا فهرست شود، در طول پیمایش بازگشتی نادیده گرفته خواهد شد. توجه داشته باشید که تمامی فایل‌هایی که با نقطه شروع می‌شوند، مانند .git یا .config ، توسط detox در طول پیمایش بازگشتی نادیده گرفته می‌شوند.

# comments

هر متنی پس از نویسه # در هر سطری نادیده گرفته می‌شود.

توالی‌ها (SEQUENCES)

تمام این دستورات درون یک بلوک sequence قرار می‌گیرند.

iso8859_1;

iso8859_1 {builtin "name";};

iso8859_1 {filename "/path/to/filename";};

این فیلتر نویسه‌های ISO-8859-1 بین 0xA0 و 0xFF را به معادل‌های UTF-8 آن‌ها، به‌جز چند استثنا، تبدیل کدگذاری می‌کند. خروجی لزوماً امن نیست و باید از فیلتر safe نیز عبور داده شود.

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

در شرایط عادی، نیازی به استفاده از ساختار filename نیست. ابزار detox چندین مسیر را برای یافتن فایلی به نام iso8859_1.tbl جستجو می‌کند؛ این فایل مجموعه‌ای از قواعد است که نحوه ترجمه نویسه‌های ISO-8859-1 را مشخص می‌سازد. اگر detox نتواند این جدول ترجمه را پیدا کند، به جدول توکار iso8859_1 رجوع خواهد کرد.

همچنین می‌توانید جدول دلخواه خود را دانلود یا ایجاد کرده و با استفاده از ساختار filename که در بالا نشان داده شده، مسیر آن را به detox اعلام کنید.

می‌توان چندین فیلتر iso8859_1 را به‌صورت زنجیره‌ای به یکدیگر متصل کرد، به‌شرطی که مقدار پیش‌فرض همه آن‌ها به جز آخرین مورد، خالی باشد. این موضوع در detox.tbl(5) توضیح داده شده است.

این فیلتر با فیلتر utf_8 مانعة‌الجمع (ناهمساز) است.

utf_8;

utf_8 {builtin "name";};

utf_8 {filename "/path/to/filename";};

این فیلتر نویسه‌های کنترلی یونیکد کدگذاری‌شده با UTF-8 را فیلتر می‌کند.

عملکرد این فیلتر مشابه iso8859_1 است، با این تفاوت که به دنبال جدول ترجمه‌ای به نام unicode.tbl می‌گردد.

مشابه فیلتر iso8859_1 ، یک جدول داخلی بر اساس جدول ترجمه استاندارد به نام unicode نیز وجود دارد.

uncgi;

این فیلتر رشته‌های دارای فرار CGI (CGI-escaped) را به معادل‌های ASCII آن‌ها ترجمه می‌کند. خروجی این فیلتر لزوماً امن نیست و دست‌کم باید از فیلتر safe عبور داده شود.

safe;

safe {builtin "name";};

safe {filename "/path/to/filename";};

این فیلتر را می‌توان «امن برای سیستم‌عامل‌های شبه‌یونیکس» نیز نامید. این فیلتر نویسه‌هایی را که کار با آن‌ها در محیط‌های یونیکس دشوار است، به نویسه‌های بدون مشکل تبدیل می‌کند.

مشابه فیلترهای iso8859_1 و utf_8 ، این مورد را نیز می‌توان با استفاده از یک جدول ترجمه کنترل کرد. این فیلتر همچنین نسخه داخلی جدول ترجمه را دارد که از طریق جدول توکار safe قابل دسترسی است.

wipeup;

wipeup {remove_trailing;};

هر توالی متوالی از زیرخط‌ها یا خط‌های تیره را به یک نویسه کاهش می‌دهد. خط تیره اولویت دارد.

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

اگر نویسه هش (#)، زیرخط یا خط تیره در ابتدای نام فایل وجود داشته باشد، حذف خواهد شد.

max_length {length value;};

نام فایل را تا طول مشخص‌شده (یا کمتر) کوتاه می‌کند. این فیلتر پسوند فایل را تشخیص داده و تلاش می‌کند هر آنچه را که پس از آخرین نقطه در نام فایل قرار دارد حفظ کند.

به‌عنوان مثال، با فرض حداکثر طول ۱۲ و نام فایل this_is_my_file.txt ، خروجی فیلتر برابر با this_is_.txt خواهد بود.

lower;

این فیلتر نویسه‌های بزرگ را به نویسه‌های کوچک تبدیل می‌کند. این فیلتر فقط روی نویسه‌های ASCII عمل می‌کند.

جدول‌های توکار (BUILTIN TABLES)

cp1252: یک جدول ترجمه برای تبدیل کدگذاری نویسه‌های CP-1252 به UTF-8، به‌جز چند استثنا. این مورد دیگر یک کاربرد متداول نیست و به یک جدول جداگانه منتقل شده است.
iso8859_1: یک جدول ترجمه برای تبدیل کدگذاری نویسه‌های تک‌بایتی با بیت بالاییِ فعال از ISO-8859-1 به UTF-8.
safe: یک جدول جایگزینی برای نویسه‌هایی که کار با آن‌ها در یونیکس و سیستم‌عامل‌های شبه‌یونیکس دشوار است.
unicode: یک جدول ترجمه برای تبدیل نویسه‌های کنترلی چندبایتی کدگذاری‌شده در UTF-8 به نویسه‌های امن.

مثال‌ها (EXAMPLES)

# فیلتر کردن نویسه‌های کنترلی UTF-8 به ASCII (با استفاده از جدول‌های زنجیره‌ای)، پاک‌سازی
sequence utf8 {
  utf_8 {
    filename "/usr/local/share/detox/custom.tbl";
  };
  utf_8 {
    builtin "unicode";
  };
  safe {
    builtin "safe";
  };
  wipeup {
    remove_trailing;
  };
  max_length {
    length 128;
  };
};
# رمزگشایی CGI، تبدیل کدگذاری CP-1252 به UTF-8، پاک‌سازی
sequence "cgi-cp1252" {
  uncgi;
  iso8859_1 {
    builtin "cp1252";
  };
  safe {
    builtin "safe";
  };
};

همچنین ببینید (SEE ALSO)

detox(1), inline-detox(1), detox.tbl(5), ascii(7), iso_8859-1(7), unicode(7), utf-8(7)

نویسندگان (AUTHORS)

ابزار detox توسط Doug Harple نوشته شده است.