harakit/docs/intcmp.1

106 lines
2.4 KiB
Groff
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.\" Copyright (c) 20232024 DTB <trinity@trinity.moe>
.\" Copyright (c) 20232024 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 2024-06-06 "Harakit X.X.X"
.SH NAME
intcmp \(en compare integers
.\"
.SH SYNOPSIS
intcmp
.RB ( -egl )
.RB [ integer ]
.RB [ integer... ]
.SH DESCRIPTION
Compare integers to each other.
.\"
.SH OPTIONS
.IP \fB-e\fP
Permits given integers to be equal to each other.
.IP \fB-g\fP
Permits a given integer to be greater than the following integer.
.IP \fB-l\fP
Permits a given integer to be less than the following integer.
.\"
.SH EXAMPLES
It may help to think of the
.BR -e ,
.BR -g ,
and
.B -l
options as equivalent to the infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq
operators respectively, with each option putting its symbol between every given
integer. The following example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
\"
.RS
intcmp -l 1 2 3
.RE
.\"
.SH DIAGNOSTICS
The program will exit with a successfully for a valid expression and with an
error code of 1 for an invalid expression.
In the event of an error, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH BUGS
.BR -egl ,
\(lqequal to or less than or greater than\(rq, always exits successfully for
valid program usage and may be abused to function as an integer validator. Use
.BR str (1)
instead.
.\"
.SH CAVEATS
There are multiple ways to express compound comparisons; \(lqless than or equal
to\(rq can be
.B -le
or
.BR -el ,
for example.
The inequality comparison is
.B -gl
.B or
.B -lg
for \(lqless than or greater than\(rq;
this is elegant but unintuitive.
.\"
.SH RATIONALE
The traditional tool for integer comparisons in POSIX and other Unix shells has
been
.BR test (1).
This tool also handles string comparisons and file scrutiny. These parts of its
functionality have been broken out into multiple utilities.
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
.\"
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
.BR scrut (1),
.BR strcmp (1),
.BR str (1),
.BR test (1p)