NAME

stdisplay - Sanitize text to be safely printed to the terminal

SYNOPSIS

stprint [TEXT...]
stecho [TEXT...]
stcat [FILE...]
stcatn [FILE...]
sttee [FILE...]
stsponge [FILE]

DESCRIPTION

stdisplay is a Python library used to safely print text from untrusted sources, sanitizing non-ASCII characters and dangerous ANSI escape sequences. From the latter, only a strict subset of SGR (Select Graphic Rendition) attributes, line feeds (\n), and horizontal tabs (\t) are allowed.

The following tests are done in order to verify if SGR should be enabled and how large its set should be:

1.

If the environment variable $NO_COLOR is set to a non-empty value, SGR is disabled.

2.

If the environment variable $COLORTERM is set to truecolor, 24-bit SGR is enabled.

3.

If none of the above match, the terminal referenced by the environment variable $TERM is queried for its colors capability, which returns how many colors the terminal supports.

Tools based on this library have no option parameters. Everything is treated either as text or file, depending on the tool used. Therefore, -- is interpreted as text and not as the end of options.

Each tool behaves as if their shell utility counterpart was used without any options:

RETURN VALUES

• 0 Successfully printed text.
• Any other return value is an error.

EXAMPLE: SGR CONTROL

Enable 24-bit SGR if the terminfo database is outdated:

COLORTERM=truecolor stprint "$(printf '%b' "\033[38;2;0;0;255mSome color\033[m")"

Disable SGR:

NO_COLOR=1 stprint "$(printf '%b' "\033[31mNo color\033[m")"
TERM=dumb stprint "$(printf '%b' "\033[31mNo color\033[m")"

EXAMPLE: STCAT/STCATN

Copy standard input to standard output:

printf '%s' "${untrusted_string}" | stcat
stcat < /untrusted/file
.
untrusted-cmd 2>&1 | stcat
stcat < <(untrusted-cmd 2>&1)

Concatenate files:

stcat /untrusted/file /untrusted/log

Piping to a pager (can also be sttee):

data | stcat | less -R
GIT_PAGER="stcat | less -R" git log

Print an ownership-restricted file with external programs:

sudo -- stcat /untrusted/log

The tool stcatn differs by:

• Adding a newline at the end of each file in case it is not empty and does not end with a newline.
• Trimming trailing whitespace.

EXAMPLE: STTEE/STSPONGE

The tools sttee and stsponge have the same usage but differ when writing. While sttee always writes to standard output as soon as it is read, stsponge only writes to standard output if no file is provided, and the write is atomic.

Copy standard input to standard output and optionally to a file:

printf '%s' "${untrusted_string}" | sttee
printf '%s' "${untrusted_string}" | sttee /trusted/file
sttee /trusted/file < /untrusted/file</br>

Only stsponge can sanitize a file in-place:

stsponge /untrusted/file < /untrusted/file

EXAMPLE: STPRINT/STECHO

The tools stprint and stecho have the same usage but differ in formatting. While stprint prints text as-is, stecho adds a space between each argument and a newline at the end of the string.

Printing a variable value is simple:

stprint "${untrusted_string}"

Note that items are joined without word-splitting (no space separation):

stprint "${untrusted_string}" "${another_untrusted_string}"

To have space-separated items, simply add a space between them:

stprint "${untrusted_string} ${another_untrusted_string}"
stprint "${untrusted_string}" " ${another_untrusted_string}"

Print with heredoc to avoid quoting problems:

stprint <<EOF
${untrusted_string}
EOF

Or Bash/Zsh syntax:<br>

printf -v var '%s' "$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"
.

Raw print:<br>

printf '%s' "${var}" </code>

Interpret wanted escapes before passing them:

red="$(printf '%b' "\033[31m")"
nocolor="$(printf '%b' "\033[m")"

Or Bash/Zsh syntax:<br>

red=$"\033[31m"
nocolor=$"\033[m"
.

Raw assignment:<br>

var="$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"

AUTHOR

This man page has been written by Benjamin Grande M. S. (ben.grande.b@gmail.com).