bonsai/harakit
5
4
Fork 3
Code Issues 37 Pull Requests 4 Projects 1 Releases 30 Activity

stris.1: makes consistent with other docs

Browse Source
This commit is contained in:
Emma Tebibyte 2025-02-25 00:02:01 -07:00
parent 28f6d2508f
commit ee9d5be015
Signed by: emma
GPG Key ID: 427287A2F16F44FA
1 changed files with 67 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
docs/stris.1
View File

@ -1,118 +1,104 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–2024 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
.\"
.TH STRIS 1 2024-10-22 "Harakit X.X.X"
.SH NAME
stris \(en test the character types of string arguments
.\"
.SH SYNOPSIS
stris
.RB ( -7bcdlu )
.RB ( -i [ inclusions ])
.RB [ strings... ]
.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.
Test each character in any number of string arguments, ensuring each meets any
of the parameters specified by 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
.IP \fB-7\fP
Tests if the character encoding is ASCII.
.IP \fB-b\fP
Tests if characters are whitespace.
.IP \fB-c\fP
Tests if characters are control characters.
.IP \fB-d\fP
Tests if characters are numeric.
.IP \fB-i\fP \fIinclusions...\fP
In addition to specified options, also permits characters in
.IR inclusions .
.IP \fB-l\fP
Tests if characters are in lower case.
.IP \fB-u\fP
Tests if characters are in upper case.
.\"
.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.
If no test cases pass for a character in
.IR strings ,
the program will exit unsuccessfully.
.SH BUGS
.SH CAVEATS
There's no way of knowing which argument failed the test without re-testing
arguments individually.
If no options are specified, the program will exit successfully as long as the
input
.I strings
are legibly encoded.
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.
Neither which test failed nor which of the
.I strings
failed a test cannot be known without further invocations of the program.
Characters that can be encoded losslessly into ASCII from UTF-8 but which
are in an \(lqoverlong encoding\(rq, where the character was encoded with
unnecessary leading zeroes causing it to span multiple bytes, won\(cqt be
detected as ASCII.
.\"
.SH EXAMPLES
This is an sh(1p) snippet that checks to see if an environment variable is an
ASCII digit.
This is an
.BR sh (1p)
snippet which tests if an environment variable is an ASCII digit.
.RS
.R stris -7 "$v" && stris -d "$v" && echo ASCII digit.
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.
This is an
.BR sh (1p)
snippet that tests if an environment variable is a hexadecimal number.
.RS
.R stris -7 "$v" && stris -di ABCDEFabcdef "$v" && echo Hexadecimal number.
stris -7 "$v" && stris -di ABCDEFabcdef "$v" && echo Hexadecimal number.
.RE
.\"
.SH AUTHOR
Written by DTB <trinity@trinity.moe>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.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
This program replaces the former str(1) which took the name of a function from
.BR ctype (3p)
as its first argument and checked the following strings against it;
.BR str (1)
exited unsuccessfully when it encountered any non-ASCII characters and could
only have one parameter specified.
.\"
.SH COPYRIGHT
Copyright © 2023–2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2023\(en2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
ascii(7), ctype(3p), strcmp(1)
.BR ascii (7),
.BR ctype (3p),
.BR strcmp (1)