GNU Teseq is a tool for translating files that contain control characters and terminal control sequences, into human-understandable text. It is intended to aid in debugging problems in terminal emulators, software that makes use of special terminal features, and interactions between the two.
It is primarily targeted at individuals who possess a basic understanding of terminal control sequences, especially csi sequences; however, by default Teseq will try to identify and describe the sequences that it encounters, and the behavior they might produce in a terminal.
Teseq describes control functions as they are interpreted by VT100-compatible terminals, and/or terminals compliant with the Ecma-48 / ISO/IEC 6429 standard. Teseq does not support describing control functions according to terminal-specific definitions in a database such as termcap or terminfo, though future versions may include limited support for that (see Future Enhancements). Therefore, the descriptions Teseq uses for control functions may not necessarily match their actual interpretation by whatever terminal device the characters were actually intended for.
GNU Teseq is free software. See Copying, for copying conditions.
You can't beat a short example to demonstrate what a program does, so here goes. 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 characters 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.