DETOXRC(5)

🎀 DETOXRC — the detoxrc config file for detox(1) 💅

okay bestie, listen. this is the File Formats Manual page for detoxrc, and it's literally the instruction booklet for how you tell detox what to do. it's not that deep, i promise. let's go ✨

---

🌸 OVERVIEW

detox lets you configure its sequences through config files. that's it, that's the whole vibe. this document describes how these files work. 🦋

---

🚨 IMPORTANT (read this one, fr fr)

when you're setting up a new set of rules, the safe and wipeup filters should always be run after a translating filter (or a whole series of them), like the utf_8 or the uncgi filters.

otherwise you're introducing the risk of difficult characters sneaking into the filename. and we do NOT want that energy in the group chat. 💀

---

✨ SYNTAX ✨

the format of this config file is C-like. it's based loosely off the config files used by named. every statement is semicolon terminated, and modifiers on a particular statement are generally contained within braces. periodt.

• sequence "name" {sequence; ...}; — defines a sequence of filters to run a filename through. name specifies how the user will refer to that particular sequence during runtime. the quotes around the sequence name are generally optional, but you should use them if the sequence name does not start with a letter.

there's a special sequence called default, which is the default sequence detox uses. you can override it through the command line option -s or the environmental variable DETOX_SEQUENCE.

sequence names are case sensitive and unique throughout all sequences — like, if a system-wide file defines normal_seq and a user has a sequence with the same name in their .detoxrc, the user's normal_seq will replace the system-wide version. user stays winning 👑

• ignore {filename "filename"; ...}; — any filename listed here will be ignored during recursion. note that all files beginning with a period, such as .git or .config, will be ignored by detox during recursion. (yes, even your precious dotfiles. sorry babe 🙈)
• # comments — anything after a # on any line is ignored. say it with your chest and then forget about it 💬

---

🧚 SEQUENCES 🧚

all of these statements occur within a sequence block. like, they live inside the braces. house rules 🏠

• iso8859_1;
• iso8859_1 {builtin "name";};
• iso8859_1 {filename "/path/to/filename";};

this transcodes ISO-8859-1 characters between 0xA0 and 0xFF into their UTF-8 equivalents, with a few exceptions. the output is not necessarily safe, and should also be run through the safe filter. no cap.

if builtin is specified, a builtin table with the name specified will be used.

under normal circumstances, the filename syntax is not needed. detox looks in several locations for a file called iso8859_1.tbl, which is a set of rules defining how an ISO-8859-1 character should be translated. if detox can't find the translation table, it will fall back on the builtin table iso8859_1.

you can also download or create your own, and tell detox the location of it using the filename syntax shown above. diy queen 💅

you can chain together multiple iso8859_1 filters, as long as the default value of all but the last one is empty. this is explained in detox.tbl(5).

this filter is mutually exclusive with the utf_8 filter. pick a lane bestie 😭

• utf_8;
• utf_8 {builtin "name";};
• utf_8 {filename "/path/to/filename";};

this filters Unicode control characters, encoded using UTF-8.

this operates in a manner similar to iso8859_1, except it looks for a translation table called unicode.tbl.

similar to the iso8859_1 filter, an internal table exists, based on the stock translation table, called unicode.

• uncgi; — this translates CGI-escaped strings into their ASCII equivalents. the output of this is not necessarily safe, and should be run through the safe filter, at the least. minimum effort, maximum safety 🫶
• safe;
• safe {builtin "name";};
• safe {filename "/path/to/filename";};

this could also be called "safe for Unix-like operating systems". it translates characters that are difficult to work with in Unix environments into characters that are not. iconic behavior honestly.

similar to the iso8859_1 and utf_8 filters, this can be controlled using a translation table. this filter also has an internal version of the translation table, which can be accessed via the builtin table safe.

• wipeup;
• wipeup {remove_trailing;};

reduces any series of underscores or dashes to a single character. the dash takes precedence. 🥇

if remove_trailing is set, then periods are added to the set of characters to work on. the period then takes precedence, followed by the dash.

if a hash character, underscore, or dash are present at the start of the filename, they will be removed. clean slate energy ✨

• max_length {length value;}; — this trims a filename down to the length specified (or less). it is conscious of extensions and attempts to preserve anything following the last period in a filename.

for instance, given a max length of 12, and a filename of this_is_my_file.txt, the filter would output this_is_.txt. the extension stays, the vibes are preserved 🎀

• lower; — this translates uppercase characters into lowercase characters. it only works on ASCII characters. lowercase is a lifestyle 💜

---

👑 BUILTIN TABLES 👑

• cp1252 — a translation table for transcoding CP-1252 characters to UTF-8, with a few exceptions. this is no longer a common use case, and has been moved to a separate table. it's giving retired legend 💀
• iso8859_1 — a translation table for transcoding single-byte characters with the high bit set from ISO-8859-1 to UTF-8.
• safe — a replacement table for characters that are hard to work with under Unix and Unix-like OSs.
• unicode — a translation table for converting multi-byte control characters encoded in UTF-8 to safe characters.

---

🔥 EXAMPLES 🔥

# filter UTF-8 control characters to ASCII (using chained tables), clean up
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;
  };
};
# decode CGI, transcode CP-1252 to UTF-8, clean up
sequence "cgi-cp1252" {
  uncgi;
  iso8859_1 {
    builtin "cp1252";
  };
  safe {
    builtin "safe";
  };
};

like, copy paste and go. you ate that 🍓

---

🌈 SEE ALSO

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

---

💖 AUTHORS

detox was written by Doug Harple. thank you king 🫡

---

and that's the whole page bestie — this one came from the Debian crew, dated February 24, 2021, and it's DETOXRC(5) in the File Formats Manual. go forth and sanitize your filenames, no cap 💅✨