ansi opt for platform

Command Type

built-in

Signature

> ansi opt {flags}

Flags

• --visual: Only keep what is visible: spaces, line feeds and erased areas don't get colors they can't show.
• --rep: Write runs of one character with REP (CSI n b).
• --compat, -c: Avoid shorthand that old terminals may reject: empty parameters, BEL ending strings.
• --stats, -s: Return the sizes and what kinds of bytes were saved, as a record.
• --show: Return the result with its escape sequences made visible.
• --diff: Return each place between two pieces of text where the sequences changed, and the bytes saved there, as a table.
• --explain: Return what happened to every input sequence, and why, as a table, including sequences kept as they were.
• --hotspot: Return each line with the escape bytes spent on it, its text shaded by cost, as a table.
• --html: Return an HTML report combining all the views.

Input/output types:

Examples

Shorten a string: the second reset does nothing, and the first and the red can be one sequence

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt
hi

Shorten an external command's colored output as it streams

> ^ls --color=always | ansi opt

Show the result with its escape sequences made visible

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt --show
\e[;31mhi\e[m

Only keep what is visible: spaces show no foreground color, so the words can stay red across them

> "\e[0m\e[31mfoo \e[0m \e[31mbar\e[0m" | ansi opt --visual --show
\e[;31mfoo  bar\e[m

Write a run of one character with REP, for a terminal that supports it

> '────────' | ansi opt --rep --show
─\e[7b

Shorten as far as possible for a terminal that supports REP: spaces don't need their color, and repeated characters become REP

> "\e[0m\e[31m──── \e[0m \e[31m────\e[0m" | ansi opt --visual --rep --show
\e[;31m─\e[3b  ─\e[3b\e[m

Avoid shorthand that old terminals may reject: the reset is written as 0 instead of left empty

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt --compat --show
\e[0;31mhi\e[m

See how many bytes were saved

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt --stats | get input output saved
╭───┬──────╮
│ 0 │ 19 B │
│ 1 │ 11 B │
│ 2 │  8 B │
╰───┴──────╯

List each place where the sequences changed, and the bytes saved there

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt --diff
╭───┬────────────────────┬─────────┬───────╮
│ # │        from        │   to    │ saved │
├───┼────────────────────┼─────────┼───────┤
│ 0 │ \e[0m \e[0m \e[31m │ \e[;31m │   7 B │
│ 1 │ \e[0m              │ \e[m    │   1 B │
╰───┴────────────────────┴─────────┴───────╯

List what happened to every escape sequence, and why any was left out

> $'(ansi reset)(ansi reset)(ansi red)hi(ansi reset)' | ansi opt --explain
╭───┬──────────┬─────────┬───────────┬─────────┬───────────────────╮
│ # │ sequence │ meaning │  outcome  │ output  │        why        │
├───┼──────────┼─────────┼───────────┼─────────┼───────────────────┤
│ 0 │ \e[0m    │ reset   │ folded    │ \e[;31m │                   │
│ 1 │ \e[0m    │ reset   │ no effect │         │ already in effect │
│ 2 │ \e[31m   │ fg red  │ folded    │ \e[;31m │                   │
│ 3 │ \e[0m    │ reset   │ folded    │ \e[m    │                   │
╰───┴──────────┴─────────┴───────────┴─────────┴───────────────────╯

Find the lines of an external command's output that spend the most bytes on escape sequences

> ^ls --color=always | ansi opt --hotspot | sort-by escapes_in --reverse | first 5

Write an HTML report of what changed in a captured file

> open --raw capture.ansi | ansi opt --html | save report.html

Notes

Repeated resets, colors that are set again before anything uses them, and cursor movements that cancel out are removed, and what is left is written in its shortest form. Anything ansi opt doesn't understand is kept byte for byte. It assumes nothing about the terminal's state, so the result also looks the same wherever it is printed.

--visual --rep together give the smallest output, on terminals that support REP (what the ansiopt tool calls --aggressive). Neither is safe everywhere: --visual can drop colors from blank cells that some tools still copy or record, and a terminal without REP drops the repeated characters.

The result is meant to be written to a terminal as a whole. It can rely on colors carried over from one line to the next, so splitting it into lines (for example with lines) can lose colors.

A byte stream is shortened as it arrives. In that case the result is not guaranteed to be shorter than the input, which a whole string or binary is.

The flags --stats, --show, --diff, --explain, --hotspot and --html each return a view of what changed in place of the result, and only one can be used at a time.