forked from bonsai/harakit
intcmp(1): new tool; npc(1): new tool; scrut(1): new tool; str(1): new tool; strcmp(1): new tool; tests: added POSIX compatibility test and C compiler compatibility test; Makefile: converted to GNUmakefile; README: added README; docs: added docs
This commit is contained in:
35
docs/false.1
Normal file
35
docs/false.1
Normal file
@@ -0,0 +1,35 @@
|
||||
.\" Copyright (c) 2022 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 FALSE 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
false \(en do nothing, unsuccessfully
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
False does nothing regardless of operands or standard input.
|
||||
False will always return an exit code of 1.
|
||||
|
||||
.SH RATIONALE
|
||||
|
||||
False exists for the construction of control flow and loops based on a failure.
|
||||
|
||||
False functions as described in POSIX.1-2017.
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
This work is marked with CC0 1.0. To see a copy of this license, visit
|
||||
<http://creativecommons.org/publicdomain/zero/1.0>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
true(1)
|
||||
78
docs/intcmp.1
Normal file
78
docs/intcmp.1
Normal file
@@ -0,0 +1,78 @@
|
||||
.\" Copyright (c) 2023 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 intcmp 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
intcmp \(en compare integers
|
||||
|
||||
.SH SYNOPSIS
|
||||
|
||||
intcmp
|
||||
.RB ( -eghl )
|
||||
.RB [ integer ]
|
||||
.RB [ integer... ]
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
Intcmp compares integers.
|
||||
|
||||
.SH USAGE
|
||||
|
||||
The -e option permits given integers to be equal to each other. If combined
|
||||
with -g or -l, only adjacent integers in the argument sequence can be equal.
|
||||
.PP
|
||||
The -g option permits a given integer to be greater than the following integer.
|
||||
.PP
|
||||
The -l option permits a given integer to be less than the following integer.
|
||||
.PP
|
||||
It may help to think of the -e, -g, and -l options as equivalent to the
|
||||
infix algebraic “=”, “>”, and “<” operators respectively, with each option
|
||||
putting its symbol between every given integer. For example,
|
||||
.R intcmp -l 1 2 3
|
||||
is equivalent to evaluating "1 < 2 < 3".
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Intcmp exits 0 for a valid expression and 1 for an invalid expression.
|
||||
.PP
|
||||
Intcmp prints a debug message and exits with the appropriate sysexits(3) error
|
||||
code in the event of an error.
|
||||
|
||||
.SH BUGS
|
||||
|
||||
There are multiple ways to express compound comparisons; “less than or equal
|
||||
to” can be -le or -el, for example.
|
||||
.PP
|
||||
The inequality comparison is -gl or -lg for “less than or greater than”; this
|
||||
is elegant but unintuitive.
|
||||
.PP
|
||||
-egl, "equal to or less than or greater than", exits 0 no matter what for valid
|
||||
program usage and may be abused to function as an integer validator.
|
||||
Use str(1) instead.
|
||||
|
||||
.SH RATIONALE
|
||||
|
||||
The traditional tool for integer comparisons in POSIX and other Unix shells has
|
||||
been test(1). This tool also handles string comparisons and file scrutiny.
|
||||
These parts of its functionality have been broken out into multiple utilities.
|
||||
|
||||
Strcmp’s functionality may be performed on a POSIX-compliant system with
|
||||
test(1p).
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/gpl.html>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
strcmp(1), scrut(1), str(1), test(1)
|
||||
68
docs/npc.1
Normal file
68
docs/npc.1
Normal file
@@ -0,0 +1,68 @@
|
||||
.\" Copyright (c) 2023 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 npc 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
npc \(en show non-printing characters
|
||||
|
||||
.SH SYNOPSIS
|
||||
|
||||
npc
|
||||
.RB ( -eht )
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
Npc reads from standard input and writes to standard output, replacing non-
|
||||
printing characters with printable equivalents. Control characters print as a
|
||||
carat ('^') followed by the character '@' through '_' corresponding to the
|
||||
character replaced (e.g. control-X becomes "^X"). The delete character (0x7F)
|
||||
becomes "^?". Characters with the high bit set (>127) are printed as "M-"
|
||||
followed by the graphical representation for the same character without the
|
||||
high bit set.
|
||||
.PP
|
||||
The
|
||||
.B -e
|
||||
option prints a currency sign ('$') before each line ending.
|
||||
.PP
|
||||
The
|
||||
.B -t
|
||||
option prints tab characters as "^I" rather than a literal horizontal tab.
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Npc prints a debug message and exits with the appropriate sysexits(3) error
|
||||
code in the event of an error, otherwise it exits successfully.
|
||||
|
||||
.SH BUGS
|
||||
|
||||
Npc operates in single-byte chunks regardless of intended encoding.
|
||||
|
||||
.SH RATIONALE
|
||||
|
||||
POSIX currently lacks a way to display non-printing characters in the terminal
|
||||
using a standard tool. A popular extension to cat(1p), the -v option, is the
|
||||
bandage solution GNU and other software suites use.
|
||||
|
||||
This functionality should be a separate tool because its usefulness extends
|
||||
beyond that of cat(1p).
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/agpl.html>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
cat(1), cat-v(1)
|
||||
|
||||
.I UNIX Style, or cat -v Considered Harmful
|
||||
by Rob Pike
|
||||
58
docs/str.1
Normal file
58
docs/str.1
Normal file
@@ -0,0 +1,58 @@
|
||||
.\" Copyright (c) 2023 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 STR 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
str \(en test the character types of string arguments
|
||||
|
||||
.SH SYNOPSIS
|
||||
|
||||
str
|
||||
.RB [ type ]
|
||||
.RB [ string... ]
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
Str tests each character in an arbitrary quantity of string arguments against
|
||||
the function of the same name within ctype(3).
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Str exits successfully if all tests pass and unsuccessfully if a test failed.
|
||||
.PP
|
||||
Str will exit unsuccessfully if a string is empty, as none of its contents
|
||||
passed the test.
|
||||
.PP
|
||||
Str will print a message to standard error and exit unsuccessfully if used
|
||||
improperly.
|
||||
|
||||
.SH DEPRECATED FEATURES
|
||||
|
||||
Str used to have an "isvalue" type as an extension to ctype(3). This was
|
||||
removed in favor of using strcmp(1) to compare strings against the empty string
|
||||
('').
|
||||
|
||||
.SH BUGS
|
||||
|
||||
There's no way of knowing which argument failed the test without re-testing
|
||||
arguments individually.
|
||||
.PP
|
||||
If a character in a string isn't valid ASCII str will exit unsuccessfully.
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/gpl.html>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
ctype(3), strcmp(1), ascii(7)
|
||||
63
docs/strcmp.1
Normal file
63
docs/strcmp.1
Normal file
@@ -0,0 +1,63 @@
|
||||
.\" Copyright (c) 2023 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 STRCMP 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
strcmp \(en compare strings
|
||||
|
||||
.SH SYNOPSIS
|
||||
|
||||
strcmp
|
||||
.RM [ string ]
|
||||
.RB [ strings... ]
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
Strcmp checks whether the given strings are the same.
|
||||
Strcmp exits successfully if the strings are identical. Otherwise, strcmp exits
|
||||
with the value 1 if an earlier string has a greater byte value than a later
|
||||
string (e.g.
|
||||
.R strcmp b a
|
||||
)
|
||||
and 255 if an earlier string has a lesser byte value (e.g.
|
||||
.R strcmp a b
|
||||
).
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Strcmp will print an error message and exit unsuccessfully with a status
|
||||
described in sysexits(3) if used incorrectly (given less than two operands).
|
||||
|
||||
.SH UNICODE
|
||||
|
||||
Strcmp will exit unsuccessfully if the given strings are not identical;
|
||||
Unicode strings may need to be normalized if the intent is to check visual
|
||||
similarity and not byte similarity.
|
||||
|
||||
.SH RATIONALE
|
||||
|
||||
The traditional tool for string comparisons in POSIX and other Unix shells has
|
||||
been test(1). This tool also handles integer comparisons and file scrutiny.
|
||||
These parts of its functionality have been broken out into multiple utilities.
|
||||
|
||||
Strcmp’s functionality may be performed on a POSIX-compliant system with
|
||||
test(1p).
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/gpl.html>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
strcmp(3), intcmp(1), scrut(1), test(1)
|
||||
35
docs/true.1
Normal file
35
docs/true.1
Normal file
@@ -0,0 +1,35 @@
|
||||
.\" Copyright (c) 2022 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 TRUE 1
|
||||
|
||||
.SH NAME
|
||||
|
||||
true \(en do nothing, successfully
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
True does nothing regardless of operands or standard input.
|
||||
True will always return an exit code of 0.
|
||||
|
||||
.SH RATIONALE
|
||||
|
||||
True exists for the construction of control flow and loops based on a success.
|
||||
|
||||
True functions as described in POSIX.1-2017.
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
.SH COPYRIGHT
|
||||
|
||||
This work is marked with CC0 1.0. To see a copy of this license, visit
|
||||
<http://creativecommons.org/publicdomain/zero/1.0>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
false(1)
|
||||
Reference in New Issue
Block a user