1 Overview

GNU Teseq (the author pronounces it: "tea" + "seek") is a tool for analyzing files that contain control characters and terminal control sequences, by printing these control sequences and their meanings in readable English. It is intended to be useful for debugging terminal emulators, and programs that make heavy use of advanced terminal features such as cursor movement, coloring, and other effects.

Teseq is useful for:

• creating animated, interactive demos to run on the terminal (see https://asciinema.org/a/7445 for a video on how to do this),
• knowing the exact output of a program (Did it have spaces at the end of the line? Or maybe it contains invisible control characters?),
• examining a text file’s contents unambiguously, a la cat -v or the ed program’s l command (but with much more information),
• stripping control sequences from a text file, e.g. to produce a plain ascii text file from a typescript file generated by the script command (see example below),
• examining the invisible control sequences within a text file, that affect graphical formatting or character encoding, in order to understand how they work and where they appear in the file, or
• debugging graphical terminal applications, and terminal emulators (its originally-intended purpose).

GNU Teseq is free software. See Copying, for copying conditions.

A Quick Example

You can’t beat a short example to demonstrate what a program does, so here goes (note: a video version of this example may be seen at the main Teseq project page, or at https://asciinema.org/a/7443. Suppose you’ve got a program that writes the following output to a terminal.

Hi there, world

A simple text string, using a boldface font to render the first word.

Suppose that, after a moment or two, the program then replaced the final word “world” with the word “earth”.

In order to achieve this effect, the program would have to send special controls to the terminal to ask it to start writing in bold text, and then to revert back to normal text for the rest. To replace the final word, it might have to issue a series of backspaces before issuing the replacement word. All of this will be handled transparently by the terminal, and you wouldn’t see any of the special c aracters the program sent to the terminal—unless perhaps you convinced the program to write to a text file as if it were writing to a terminal, or ran the program under a terminal capture utility such as the script command.

You may be able to produce this effect yourself with the following shell command.

$ printf '\033[1mHi\033[m there, world'; sleep 1; \
    printf '\b\b\b\b\bearth\n'

If you were to examine the output from such a command with a text editor, it might look something like this.

^[[1mHi^[[m there, world^H^H^H^H^Hearth

Not very readable, is it? That’s where Teseq comes in! When you run that gibberish through the teseq command with the default settings, you’ll get the following output.

: Esc [ 1 m
& SGR: SELECT GRAPHIC RENDITION
" Set bold text.
|Hi|
: Esc [ 0 m
& SGR: SELECT GRAPHIC RENDITION
" Clear graphic rendition to defaults.
| there, world|
. BS/^H BS/^H BS/^H BS/^H BS/^H
|earth|.

Note that the special control sequences that tell the terminal to start and stop writing in boldface text are separated out on their own lines (prefixed with a colon ‘:’), and followed by an identification (prefixed with an ampersand ‘&’) and a description of what it does (prefixed with a quote character ‘"’).

The actual text appears in lines bracketed by pipe ‘|’ characters.

The series of single-character backspace controls appear on a line prefixed with a period ‘.’, identified by its identifying acronym (BS for BACKSPACE), and its control-key representation (Control-H).

The final word, “earth”, is followed by a period just after the closing pipe symbol; this indicates a following linefeed (or “newline”) character.

The reseq command may be used to reverse the procedure, accepting the above input and printing out the original set of escape sequences that produced it. See Reseq.

Stripping out escapes

The teseq command can be instructed to recognize, but not output, escapes encountered in the input. This is useful for stripping out the formatting strings that are invisible on display, but which get in the way during editing, or make the content inappropriate for inclusion in documentation, etc.

To sanitize a typescript file or other text file containing control sequences, try the following command:

$ teseq -EDLC your-file.txt | reseq - - | col -b > new-file.txt

The -EDLC options tell teseq not to output recognized escape sequences or identify them, and otherwise to abbreviate its output. Then, reseq takes the output from teseq and turns it back into raw text (minus the now elided escape sequences). Finally, col -b (a fairly standard Unix tool) interprets common control characters such as backspaces and carriage returns, resolving them into a text file that displays the same, but doesn’t contain those controls.