STDISPLAY(1)

NAME
stdisplay - Sanitize text to be safely printed to the terminal

SYNOPSIS
stprint [TEXT...]
stecho [TEXT...]
stcat [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 sequenes, 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 it's 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 matches, 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 end of options.

Each tool behaves as if their shell utility counterpart was used without any options:
Tool | Sanitizer
strint | printf
stecho | echo
stcat | cat
sttee | tee
stsponge | sponge

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
Copy standard input to standard output:

printf '%s' "${untrusted_string}" | stcat
stcat < /untrusted/file
.
untrusted-cmd 2>&1 | stcat
# Or with Bash/Zsh syntax:
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 a ownership restricted file with external programs:

sudo -- stcat /untrusted/log

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

Copy standrd 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 does print text as is, stecho adds a space between each argument and a newline at the end of the string.

Print 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

  EXAMPLE: STPRINT WITH VARIABLES
Print a variable as is:

var="$(stprint "${untrusted_string}")"
## Or Bash/Zsh syntax:
printf -v var '%s' "$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"
.
## Raw print:
printf '%s' "${var}"

Interpret wanted escapes before passing them:

red="$(printf '%b' "\033[31m")"
nocolor="$(printf '%b' "\033[m")"
## Or Bash/Zsh syntax:
red=$"\033[31m"
nocolor=$"\033[m"
.
## Raw assignment:
var="$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"

  EXAMPLE: STPRINT MISUSE
Warning: Reinterpreting the escapes from the data returned from stprint is insecure. Stack of escaped escape sequences not interpreted before will be evaluated.

Do NOT reinterpret the escape sequences on variable assignment (dangerous when printing to the terminal later:

var="$(stprint "${untrusted_string}")" # OK
# Or with Bash/Zsh syntax:
printf -v var "$(stprint "${untrusted_string}")" # DANGER (format is '%b')
printf -v var '%b' "$(stprint "${untrusted_string}")" # DANGER

Do NOT reinterpret the escape sequences when printing a variable, one more layer of escapes will be interpreted:

var="$(stprint "${untrusted_string}")" # OK
printf "${var}" # DANGER (format is '%b')
printf '%b' "${var}" # DANGER
echo -e "${var}" # DANGER
echo "${var}" # DANGER (may default to use '-e')
echo -E "${var}" # DANGER (var may have '-e' prefix)

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