DIVERT(1)

🎀 NAME 🎀

Divert — the Text Diversion Filter ✨

okay bestie, real talk: this is the DIVERT(1) page from the EN Tools manual set, and it's genuinely one of the most underrated little text filters out there. no cap. 💖

---

✨ SYNOPSIS ✨

divert [-o outputfile] [-q] [-v] [inputfile]

---

🦋 DESCRIPTION 🦋

So divert reads inputfile — or stdin if you don't hand it a file — and runs a 2-pass diversion filter over whatever's in there. Pass 1 gathers up all the diversion locations, and pass 2 recursively expands those locations at their dump positions. 🌸

And like… how does it know what to do? The whole filter is steered by directives you drop straight into the input data:

• {#NAME#} (or <<NAME>>) — this defines the dump position of the location NAME. All the accumulated data that finally has to be diverted to NAME gets inserted right at this data position. Notice: the final data of a location NAME doesn't have to be known at this point, because expanding those location dumps happens in pass 2. 💅 You can dump a location more than once too, but the contents is always the same, no matter what data position the location dump tag sits at. NAME can be any symbolic name matching [a-zA-Z][a-zA-Z0-9_]*.
• {#[!]NAME[!]#: (or ..[!]NAME[!]>>) — this enters the location NAME, i.e. it diverts the data flow to it (hence the name of this filter, iykyk). In other words: the data flow now goes on at location NAME, and all following data — up to end of file or the next location leave tag — gets appended to location NAME. 📎 You can nest diversions by entering other locations at any point, because the locations are remembered on a stack. The default entered location is named "main". The top most location is named "null", which neither can be entered nor leaved explicitly. But of course the "null" diversion can be manually dumped, for instance when you're using it for error messages.

There are two special features for diverting data, and they're controlled by the ! characters preceding or following the NAME identifier:

• !NAME — sets the data flow position to the begin of location NAME, i.e. it actually discards the current (already diverted) contents of location NAME before entering it. Use this to overwrite a location's contents. 🔥
• NAME! — marks this location entry as overwritable, i.e. it enters location NAME, but when the corresponding leave tag is found, the data-flow position for NAME gets automatically reset to its begin. Use this if you want to set the default contents for a location that only gets used if no other diversions occur to it (because any following diversions to this location will overwrite the contents). This feature is usually used for a template scheme. ✨
• !NAME! — just the combination of the above two features. Use this to both discard the current contents of location NAME and set a new default for it.

• :#[NAME]#} (or <<[NAME]..) — this leaves the current location, i.e. it enters again the location that was active when this location was entered. There's no need to leave all locations at the end of the input data — all still-entered locations are automatically left at end of file, because that's essential for a template scheme. 🫶

---

Notice that there are two ways of using (and thinking) about the filtering mechanism this program provides:

🌈 Macro Mechanism

This is the "predefined" way of thinking here. Use it like this:

FOO
{#BAR#}
QUUX
{#BAR#:
BAZ
:##}

Here you're thinking of the mechanism as a macro mechanism, where you expand a macro at one data position while you define it via begin and end tags. 💖

🦋 Diversion Mechanism

This is the alternative way of thinking. Use it like this:

FOO
<<BAR>>
QUUX
..BAR>>
BAZ
<<..

In other words: you're thinking of the mechanism as a diversion mechanism, where you dump a location at one data position while you divert to it by entering and leaving the location (here BAR) at other positions. 🎀

You can even intermix both ways, because both are just alternative syntax variants that are treated the same. no cap, fr fr.

---

🌸 EXAMPLE 🌸

{#HEAD#}
{#BODY#}
{#FOOT#}

{#FOOT#:
Quux
:##}

{#BODY#:
Bar
:##}

{#HEAD#:
Foo
:##}

---

💅 OPTIONS 💅

• -o outputfile — redirects the output to outputfile. Usually the output gets sent to stdout if no such option is specified, or if outputfile is "-". 📤
• -q — sets quiet mode, where warnings are suppressed. 🤫
• -v — sets verbose mode, where some processing information will be given on stderr. 👀

---

👑 AUTHORS 👑

• Ralf S. Engelschall — rse@engelschall.com — www.engelschall.com
• Denis Barbier — barbier@engelschall.com

---

and that's the whole page, bestie!! this one's from EN Tools, dated 2020-11-29, and it's the DIVERT(1) entry of your manual set — go forth and divert, you absolute icon. 💖✨🎀🦋