.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.

.TH STRIS 1

.SH NAME

stris \(en test the character types of string arguments

.SH SYNOPSIS

stris
.RB ( -7bcdlu )
.RB ( -i [ inclusions ])
.RB [ strings... ]

.SH DESCRIPTION

Stris tests each rune in an arbitrary quantity of string arguments, ensuring
each meets any of the parameters specified in the program options.

.SH OPTIONS

.B -7
.RS
Tests to see if runes are fit within seven bits; that is, that they are encoded
with ASCII.
.RE

.B -b
.RS
Tests to see if runes are blank or "whitespace"; characters that do not print
but fill a predictable amount of space.
.RE

.B -c
.RS
Tests to see if runes are control characters; characters that are not printing
or graphical.
.RE

.B -d
.RS
Tests to see if runes are numeric. This test does not only allow the ASCII
digits but any numeric symbol.
.RE

.B -i
.RS
Permits, in addition to the given specified parameters, all of the runes
supplied in its option argument.
.RE

.B -l
.RS
Tests to see if runes are in their lower case.
.RE

.B -u
.RS
Tests to see if runes are in their upper case, or capitalized.
.RE

.SH DIAGNOSTICS

Stris exits successfully if all runes in all given strings meet any of the
specified parameters, or if no parameters were specified but all given strings
were legibly encoded. It exits unsuccessfully if the previous is untrue, and if
invalid options were given, or if no strings were given, a usage synopsis will
be printed to the standard error.

.SH BUGS

There's no way of knowing which argument failed the test without re-testing
arguments individually.

Some runes that can losslessly be encoded into ASCII from UTF-8 but in an
"overlong encoding", where the rune was encoded with unnecessary leading
zeroes causing it to span multiple bytes, won't be detected as ASCII.

.SH EXAMPLES

This is an sh(1p) snippet that checks to see if an environment variable is an
ASCII digit.

.RS
.R stris -7 "$v" && stris -d "$v" && echo ASCII digit.
.RE

This is an sh(1p) snippet that checks to see if an environment variable is a
hexadecimal number.

.RS
.R stris -7 "$v" && stris -di ABCDEFabcdef "$v" && echo Hexadecimal number.
.RE

.SH AUTHOR

Written by DTB <trinity@trinity.moe>.

.SH HISTORY

Stris replaces the former str(1) which took the name of a function from
ctype(3) as its first argument and checked the following strings against it;
str(1) exited unsuccessfully when it encountered any non-ASCII runes and could
only have one parameter specified.

.SH COPYRIGHT

Copyright © 2023–2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.

.SH SEE ALSO

ascii(7), ctype(3p), strcmp(1)